tessl/maven-com-tencent--mmkv-shared

MMKV is an efficient, small, easy-to-use mobile key-value storage framework used in the WeChat application.

—

Pending

Overview

Eval results

Files

Instance Management

Name: tessl/maven-com-tencent--mmkv-shared
Author: tessl

MMKV instance creation and management with various configuration options including encryption, multi-process modes, and custom storage locations. Instances can be created with unique IDs for logical separation of data.

Capabilities

Default Instance

Get the default MMKV instance for simple use cases.

/**
 * Create the default MMKV instance in single-process mode.
 * @return The default MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV defaultMMKV();

/**
 * Create the default MMKV instance in customize process mode, with an encryption key.
 * @param mode The process mode of the MMKV instance, defaults to SINGLE_PROCESS_MODE
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
 * @return The default MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV defaultMMKV(int mode, String cryptKey);

Usage Example:

// Simple default instance
MMKV kv = MMKV.defaultMMKV();
kv.encode("user_id", 12345);

// Default instance with encryption
MMKV encryptedKv = MMKV.defaultMMKV(MMKV.SINGLE_PROCESS_MODE, "my_secret_key");
encryptedKv.encode("sensitive_data", "confidential_info");

// Default instance with multi-process support
MMKV multiProcessKv = MMKV.defaultMMKV(MMKV.MULTI_PROCESS_MODE, null);
multiProcessKv.encode("shared_config", "value");

Named Instances

Create MMKV instances with unique IDs for logical data separation.

/**
 * Create an MMKV instance with an unique ID (in single-process mode).
 * @param mmapID The unique ID of the MMKV instance
 * @return MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV mmkvWithID(String mmapID);

/**
 * Create an MMKV instance in single-process or multi-process mode.
 * @param mmapID The unique ID of the MMKV instance
 * @param mode The process mode of the MMKV instance, defaults to SINGLE_PROCESS_MODE
 * @return MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV mmkvWithID(String mmapID, int mode);

/**
 * Create an MMKV instance in single-process or multi-process mode with expected capacity.
 * @param mmapID The unique ID of the MMKV instance
 * @param mode The process mode of the MMKV instance
 * @param expectedCapacity The file size you expected when opening or creating file
 * @return MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV mmkvWithID(String mmapID, int mode, long expectedCapacity);

Usage Example:

// Separate instances for different data types
MMKV userPrefs = MMKV.mmkvWithID("user_preferences");
MMKV gameData = MMKV.mmkvWithID("game_data");
MMKV cacheData = MMKV.mmkvWithID("cache_data");

userPrefs.encode("theme", "dark");
gameData.encode("high_score", 15000);
cacheData.encode("last_sync", System.currentTimeMillis());

// Multi-process instance for shared data
MMKV sharedData = MMKV.mmkvWithID("shared_config", MMKV.MULTI_PROCESS_MODE);
sharedData.encode("app_version", "2.1.0");

// Pre-allocate file size for performance
MMKV largeDataset = MMKV.mmkvWithID("large_data", MMKV.SINGLE_PROCESS_MODE, 10 * 1024 * 1024); // 10MB

Encrypted Instances

Create MMKV instances with encryption for sensitive data protection.

/**
 * Create an MMKV instance in customize process mode, with an encryption key.
 * @param mmapID The unique ID of the MMKV instance
 * @param mode The process mode of the MMKV instance
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
 * @return MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV mmkvWithID(String mmapID, int mode, String cryptKey);

/**
 * Create an MMKV instance with customize settings all in one.
 * @param mmapID The unique ID of the MMKV instance
 * @param mode The process mode of the MMKV instance
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
 * @param rootPath The folder of the MMKV instance, defaults to $(FilesDir)/mmkv
 * @param expectedCapacity The file size you expected when opening or creating file
 * @return MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV mmkvWithID(String mmapID, int mode, String cryptKey, String rootPath, long expectedCapacity);

Usage Example:

// Encrypted user credentials
MMKV credentials = MMKV.mmkvWithID("user_credentials", MMKV.SINGLE_PROCESS_MODE, "encryption_key");
credentials.encode("username", "alice");
credentials.encode("auth_token", "secret_token_12345");

// Encrypted multi-process instance
MMKV secureShared = MMKV.mmkvWithID("secure_shared", MMKV.MULTI_PROCESS_MODE, "shared_secret");
secureShared.encode("api_key", "confidential_api_key");

// Full customization with encryption
File customDir = new File(getFilesDir(), "secure_storage");
MMKV fullyCustom = MMKV.mmkvWithID(
    "custom_encrypted",
    MMKV.SINGLE_PROCESS_MODE,
    "my_encrypt_key",
    customDir.getAbsolutePath(),
    5 * 1024 * 1024 // 5MB capacity
);

Custom Root Path Instances

Create MMKV instances with custom storage locations.

/**
 * Create an MMKV instance in customize folder.
 * @param mmapID The unique ID of the MMKV instance
 * @param rootPath The folder of the MMKV instance, defaults to $(FilesDir)/mmkv
 * @return MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV mmkvWithID(String mmapID, String rootPath);

/**
 * Create an MMKV instance in customize folder with expected capacity.
 * @param mmapID The unique ID of the MMKV instance
 * @param rootPath The folder of the MMKV instance
 * @param expectedCapacity The file size you expected when opening or creating file
 * @return MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV mmkvWithID(String mmapID, String rootPath, long expectedCapacity);

Usage Example:

// Store cache data on external storage
File externalDir = new File(getExternalFilesDir(null), "mmkv_cache");
MMKV cacheStorage = MMKV.mmkvWithID("image_cache", externalDir.getAbsolutePath());

// Temporary data with custom location and capacity
File tempDir = new File(getCacheDir(), "temp_mmkv");
MMKV tempStorage = MMKV.mmkvWithID("temp_data", tempDir.getAbsolutePath(), 2 * 1024 * 1024);

Backup and Restore Instances

Create instances specifically designed for backup scenarios.

/**
 * Get a backed-up MMKV instance with customize settings all in one.
 * @param mmapID The unique ID of the MMKV instance
 * @param mode The process mode of the MMKV instance
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
 * @param rootPath The backup folder of the MMKV instance
 * @return MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV backedUpMMKVWithID(String mmapID, int mode, String cryptKey, String rootPath);

Usage Example:

// Create backup instance
File backupDir = new File(getExternalFilesDir(null), "mmkv_backup");
MMKV backupInstance = MMKV.backedUpMMKVWithID(
    "user_data_backup",
    MMKV.SINGLE_PROCESS_MODE,
    "backup_key",
    backupDir.getAbsolutePath()
);

Anonymous Shared Memory Instances

Create MMKV instances using Anonymous Shared Memory for inter-process communication without persistent storage.

/**
 * Create an MMKV instance base on Anonymous Shared Memory, aka not synced to any disk files.
 * @param context The context of Android App, usually from Application
 * @param mmapID The unique ID of the MMKV instance
 * @param size The maximum size of the underlying Anonymous Shared Memory
 * @param mode The process mode of the MMKV instance
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
 * @return MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV mmkvWithAshmemID(Context context, String mmapID, int size, int mode, String cryptKey);

/**
 * Get an ashmem MMKV instance that has been initiated by another process.
 * @param mmapID The unique ID of the MMKV instance
 * @param fd The file descriptor of the ashmem of the MMKV file
 * @param metaFD The file descriptor of the ashmem of the MMKV crc file
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
 * @return MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV mmkvWithAshmemFD(String mmapID, int fd, int metaFD, String cryptKey);

Usage Example:

// Create ashmem instance for temporary inter-process data
MMKV ashmemKv = MMKV.mmkvWithAshmemID(
    this,
    "temp_shared_data",
    1024 * 1024, // 1MB size limit
    MMKV.MULTI_PROCESS_MODE,
    null
);

// Use for temporary data sharing between processes
ashmemKv.encode("current_state", "processing");
ashmemKv.encode("progress", 45);

Instance Information

Get information about MMKV instances.

/**
 * Get the unique ID of the MMKV instance.
 * @return The unique ID of the MMKV instance
 */
public String mmapID();

/**
 * Check if this instance is in multi-process mode.
 * @return true if multi-process mode, false otherwise
 */
public boolean isMultiProcess();

/**
 * Check if this instance is in read-only mode.
 * @return true if read-only mode, false otherwise
 */
public boolean isReadOnly();

Usage Example:

MMKV kv = MMKV.mmkvWithID("test_instance", MMKV.MULTI_PROCESS_MODE);

String instanceId = kv.mmapID(); // Returns "test_instance"
boolean isMultiProcess = kv.isMultiProcess(); // Returns true
boolean isReadOnly = kv.isReadOnly(); // Returns false

Log.d("MMKV", "Instance: " + instanceId + ", Multi-process: " + isMultiProcess);

Instance Lifecycle

Manage MMKV instance lifecycle and cleanup.

/**
 * Call this method if the MMKV instance is no longer needed in the near future.
 * Any subsequent call to any MMKV instances with the same ID is undefined behavior.
 */
public void close();

/**
 * Clear memory cache of the MMKV instance.
 * You can call it on memory warning.
 * Any subsequent call to the MMKV instance will trigger all key-values loading from the file again.
 */
public void clearMemoryCache();

Usage Example:

MMKV tempKv = MMKV.mmkvWithID("temporary_data");
// Use instance...

// Clear memory cache on memory pressure
@Override
public void onTrimMemory(int level) {
    super.onTrimMemory(level);
    if (level >= TRIM_MEMORY_MODERATE) {
        tempKv.clearMemoryCache();
    }
}

// Close instance when no longer needed
@Override
protected void onDestroy() {
    super.onDestroy();
    tempKv.close();
}

Constants

// Process modes
public static final int SINGLE_PROCESS_MODE = 1 << 0;  // Single-process mode. The default mode
public static final int MULTI_PROCESS_MODE = 1 << 1;   // Multi-process mode
public static final int READ_ONLY_MODE = 1 << 5;       // Read-only mode

Install with Tessl CLI

npx tessl i tessl/maven-com-tencent--mmkv-shared

docs

instance-management.md

multi-process.md

storage-operations.md

tile.json

tessl/maven-com-tencent--mmkv-shared