or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

data-management.mddata-storage.mdencryption.mdindex.mdinitialization.mdinstance-management.mdmulti-process.mdnamespace.md
tile.json

tessl/maven-com-tencent--mmkv

High-performance mobile key-value storage framework with memory mapping, encryption, and multi-process support for Android applications.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.tencent/mmkv@2.2.x

To install, run

npx @tessl/cli install tessl/maven-com-tencent--mmkv@2.2.0

index.mddocs/

MMKV

MMKV is a high-performance, cross-platform mobile key-value storage framework that provides efficient memory-mapped file-based persistence with protobuf encoding. It offers multi-process concurrency support, encryption capabilities, and serves as a drop-in replacement for Android SharedPreferences with significantly better performance characteristics.

Package Information

  • Package Name: com.tencent:mmkv
  • Package Type: maven
  • Language: Java (with native C++ components)
  • Installation: Add to build.gradle: implementation 'com.tencent:mmkv:2.2.2'

Core Imports

import com.tencent.mmkv.MMKV;
import com.tencent.mmkv.MMKVLogLevel;
import com.tencent.mmkv.MMKVHandler;
import com.tencent.mmkv.NameSpace;

Basic Usage

import com.tencent.mmkv.MMKV;

public class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        // Initialize MMKV (call once during app startup)
        String rootDir = MMKV.initialize(this);
        
        // Get default MMKV instance
        MMKV kv = MMKV.defaultMMKV();
        
        // Store values
        kv.encode("user_id", 12345);
        kv.encode("username", "john_doe");
        kv.encode("is_premium", true);
        kv.encode("score", 99.5f);
        
        // Retrieve values
        int userId = kv.decodeInt("user_id");
        String username = kv.decodeString("username");
        boolean isPremium = kv.decodeBool("is_premium");
        float score = kv.decodeFloat("score");
    }
}

Architecture

MMKV is built around several key components:

  • Memory Mapping: Uses mmap to keep memory synced with files for immediate persistence
  • Protobuf Encoding: Efficient binary serialization for all data types
  • Multi-Process Support: Safe concurrent access across different processes with file locking
  • Encryption Layer: Optional AES encryption with custom keys up to 16 bytes
  • SharedPreferences Compatibility: Drop-in replacement API for easy migration
  • Native Performance: C++ core with JNI bridge for optimal performance
  • Namespace Support: Custom root directories for data isolation

Capabilities

Initialization and Configuration

Core initialization methods for setting up MMKV with various configuration options including custom directories, log levels, library loaders, and error handlers.

public static String initialize(Context context);
public static String initialize(Context context, MMKVLogLevel logLevel);
public static String initialize(Context context, String rootDir);
public static String initialize(Context context, String rootDir, MMKVLogLevel logLevel);

Initialization and Configuration

Instance Management

Methods for creating and managing MMKV instances with different configurations including single/multi-process modes, encryption, custom directories, and ashmem-based instances.

public static MMKV mmkvWithID(String mmapID);
public static MMKV mmkvWithID(String mmapID, int mode);
public static MMKV mmkvWithID(String mmapID, int mode, String cryptKey);
public static MMKV defaultMMKV();

Instance Management

Data Storage and Retrieval

Comprehensive data storage API supporting primitives, strings, byte arrays, string sets, and Parcelable objects with optional expiration times.

public boolean encode(String key, boolean value);
public boolean encode(String key, int value);
public boolean encode(String key, String value);
public boolean decodeBool(String key, boolean defaultValue);
public int decodeInt(String key, int defaultValue);
public String decodeString(String key, String defaultValue);

Data Storage and Retrieval

Encryption and Security

Built-in encryption capabilities with key management, supporting AES encryption for secure data storage and key transformation operations.

public String cryptKey();
public boolean reKey(String cryptKey);
public void checkReSetCryptKey(String cryptKey);

Encryption and Security

Multi-Process Operations

Safe multi-process access with file locking, content change notifications, and process-aware instance management for applications with multiple processes.

public void lock();
public void unlock();
public boolean tryLock();
public void checkContentChangedByOuterProcess();
public boolean isMultiProcess();

Multi-Process Operations

Data Management

Advanced data management operations including key inspection, file operations, backup/restore capabilities, and performance optimization methods.

public boolean containsKey(String key);
public String[] allKeys();
public long count();
public void removeValueForKey(String key);
public void clearAll();
public long totalSize();
public long actualSize();

Data Management

Namespace Support

Namespace functionality for organizing MMKV instances with custom root directories, providing data isolation and organizational capabilities.

public static NameSpace nameSpace(String dir);
public static NameSpace defaultNameSpace();

Namespace Support

Types

public enum MMKVLogLevel {
    LevelDebug,
    LevelInfo,
    LevelWarning,
    LevelError,
    LevelNone
}

public enum MMKVRecoverStrategic {
    OnErrorDiscard,
    OnErrorRecover
}

public interface MMKVHandler {
    MMKVRecoverStrategic onMMKVCRCCheckFail(String mmapID);
    MMKVRecoverStrategic onMMKVFileLengthError(String mmapID);
    boolean wantLogRedirecting();
    void mmkvLog(MMKVLogLevel level, String file, int line, String function, String message);
}

public interface MMKVContentChangeNotification {
    void onContentChangedByOuterProcess(String mmapID);
}

public final class ParcelableMMKV implements Parcelable {
    public ParcelableMMKV(MMKV mmkv);
    public MMKV toMMKV();
    public int describeContents();
    public void writeToParcel(Parcel dest, int flags);
    public static final Parcelable.Creator<ParcelableMMKV> CREATOR;
}

public class UnsupportedArchitectureException extends RuntimeException {
    public UnsupportedArchitectureException(String message);
}

public final class NativeBuffer {
    public long pointer;
    public int size;
    public NativeBuffer(long ptr, int length);
}

public class MMKVContentProvider extends ContentProvider {
    protected static final String KEY = "KEY";
    protected static final String KEY_SIZE = "KEY_SIZE";
    protected static final String KEY_MODE = "KEY_MODE";
    protected static final String KEY_CRYPT = "KEY_CRYPT";
    protected static final String FUNCTION_NAME = "mmkvFromAshmemID";
    
    protected static Uri contentUri(Context context);
    protected static String getProcessNameByPID(Context context, int pid);
    public boolean onCreate();
    public Bundle call(String method, String mmapID, Bundle extras);
    public String getType(Uri uri);
}

Constants

// Process modes
public static final int SINGLE_PROCESS_MODE = 1 << 0;
public static final int MULTI_PROCESS_MODE = 1 << 1;
public static final int READ_ONLY_MODE = 1 << 5;

// Expiration constants
public static final int ExpireNever = 0;
public static final int ExpireInMinute = 60;
public static final int ExpireInHour = 3600;
public static final int ExpireInDay = 86400;
public static final int ExpireInMonth = 2592000;
public static final int ExpireInYear = 946080000;