tessl/maven-com-tencent--mmkv

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

—

Pending

Overview

Eval results

Files

Instance Management

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

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

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 with customize process mode and encryption.
 * @param mode The process mode (SINGLE_PROCESS_MODE or MULTI_PROCESS_MODE)
 * @param cryptKey The encryption key (no more than 16 bytes), null for no encryption
 * @return The default MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV defaultMMKV(int mode, String cryptKey);

Usage Example:

import com.tencent.mmkv.MMKV;

// Get default instance (single-process, no encryption)
MMKV kv = MMKV.defaultMMKV();

// Get default instance with multi-process support
MMKV multiProcessKv = MMKV.defaultMMKV(MMKV.MULTI_PROCESS_MODE, null);

// Get default instance with encryption
MMKV encryptedKv = MMKV.defaultMMKV(MMKV.SINGLE_PROCESS_MODE, "my-secret-key");

Named Instances

Create MMKV instances with unique IDs for data separation.

/**
 * Create an MMKV instance with a unique ID (in single-process mode).
 * @param mmapID The unique ID of the MMKV instance
 * @return The 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 (SINGLE_PROCESS_MODE or MULTI_PROCESS_MODE)
 * @return The MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV mmkvWithID(String mmapID, int mode);

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

Usage Example:

// Create separate instances for different data types
MMKV userPrefs = MMKV.mmkvWithID("user_preferences");
MMKV gameData = MMKV.mmkvWithID("game_data");
MMKV cache = MMKV.mmkvWithID("cache_data");

// Multi-process instance for sharing between processes
MMKV sharedData = MMKV.mmkvWithID("shared_data", MMKV.MULTI_PROCESS_MODE);

// Instance with pre-allocated capacity for performance
MMKV largeDr = MMKV.mmkvWithID("large_data", MMKV.SINGLE_PROCESS_MODE, 1024 * 1024); // 1MB

Encrypted Instances

Create MMKV instances with encryption for sensitive data.

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

Usage Example:

// Create encrypted instance for sensitive data
MMKV secureStorage = MMKV.mmkvWithID("secure_data", 
                                     MMKV.SINGLE_PROCESS_MODE, 
                                     "encryption-key");

// Store sensitive information
secureStorage.encode("access_token", "secret-token-value");
secureStorage.encode("user_password", "hashed-password");

Custom Directory Instances

Create MMKV instances in custom directories for data organization.

/**
 * Create an MMKV instance in customize folder.
 * @param mmapID The unique ID of the MMKV instance
 * @param rootPath The folder of the MMKV instance
 * @return The 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 capacity.
 * @param mmapID The unique ID of the MMKV instance
 * @param rootPath The folder of the MMKV instance
 * @param expectedCapacity The file size expected
 * @return The MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV mmkvWithID(String mmapID, String rootPath, long expectedCapacity);

Usage Example:

// Create instance in custom directory
File customDir = new File(getExternalFilesDir(null), "app_data");
MMKV customKv = MMKV.mmkvWithID("custom_data", customDir.getAbsolutePath());

// Separate user data by user ID
String userDir = getFilesDir().getAbsolutePath() + "/users/" + userId;
MMKV userKv = MMKV.mmkvWithID("user_" + userId, userDir);

Complete Configuration

Create MMKV instances with all customization options.

/**
 * Create an MMKV instance with all customize settings.
 * @param mmapID The unique ID of the MMKV instance
 * @param mode The process mode
 * @param cryptKey The encryption key (null for no encryption)
 * @param rootPath The folder of the MMKV instance
 * @param expectedCapacity The file size expected
 * @return The MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV mmkvWithID(String mmapID, int mode, String cryptKey, 
                             String rootPath, long expectedCapacity);

/**
 * Create an MMKV instance with all settings except capacity.
 * @param mmapID The unique ID of the MMKV instance
 * @param mode The process mode
 * @param cryptKey The encryption key
 * @param rootPath The folder of the MMKV instance
 * @return The MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
public static MMKV mmkvWithID(String mmapID, int mode, String cryptKey, String rootPath);

Usage Example:

// Full configuration example
MMKV fullyConfigured = MMKV.mmkvWithID(
    "app_config",                    // Unique ID
    MMKV.MULTI_PROCESS_MODE,        // Multi-process support
    "config-encryption-key",         // Encryption key
    getFilesDir() + "/config",       // Custom directory
    512 * 1024                       // 512KB expected capacity
);

Backup Instance

Create backed-up MMKV instances for data resilience.

/**
 * Get a backed-up MMKV instance with customize settings.
 * @param mmapID The unique ID of the MMKV instance
 * @param mode The process mode
 * @param cryptKey The encryption key
 * @param rootPath The backup folder of the MMKV instance
 * @return The backed-up 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 in separate directory
File backupDir = new File(getExternalFilesDir(null), "backup");
MMKV backupKv = MMKV.backedUpMMKVWithID("main_backup", 
                                        MMKV.SINGLE_PROCESS_MODE,
                                        null,
                                        backupDir.getAbsolutePath());

Anonymous Shared Memory Instances

Create MMKV instances based on anonymous shared memory for inter-process communication without disk files.

/**
 * Create an MMKV instance base on Anonymous Shared Memory.
 * Not synced to any disk files.
 * @param context The Android app context
 * @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
 * @param cryptKey The encryption key
 * @return The ashmem-based 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 from file descriptors.
 * @param mmapID The unique ID of the MMKV instance
 * @param fd The file descriptor of the ashmem MMKV file
 * @param metaFD The file descriptor of the ashmem MMKV crc file
 * @param cryptKey The encryption key
 * @return The ashmem-based 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 inter-process sharing (main process)
MMKV ashmemKv = MMKV.mmkvWithAshmemID(this, 
                                      "shared_memory", 
                                      1024 * 1024,  // 1MB size
                                      MMKV.MULTI_PROCESS_MODE,
                                      null);

// In another process, get the same instance via ContentProvider
// (handled automatically by MMKV's ContentProvider)

Instance Information

Get information about MMKV instances.

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

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

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

Usage Example:

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

String id = kv.mmapID();                    // "example"
boolean isMultiProcess = kv.isMultiProcess(); // true
boolean isReadOnly = kv.isReadOnly();        // false

Log.d("MMKV", String.format("Instance %s: multiProcess=%b, readOnly=%b", 
                            id, isMultiProcess, isReadOnly));

File Validation and Existence

Static methods for checking MMKV file status.

/**
 * Check whether the MMKV file is valid or not.
 * @param mmapID The unique ID of the MMKV instance
 * @return True if valid, false otherwise
 */
public static boolean isFileValid(String mmapID);

/**
 * Check whether the MMKV file is valid in customize folder.
 * @param mmapID The unique ID of the MMKV instance
 * @param rootPath The folder of the MMKV instance
 * @return True if valid, false otherwise
 */
public static boolean isFileValid(String mmapID, String rootPath);

/**
 * Check existence of the MMKV file.
 * @param mmapID The unique ID of the MMKV instance
 * @return True if exists, false otherwise
 */
public static boolean checkExist(String mmapID);

/**
 * Check existence of the MMKV file in customize folder.
 * @param mmapID The unique ID of the MMKV instance
 * @param rootPath The folder of the MMKV instance
 * @return True if exists, false otherwise
 */
public static boolean checkExist(String mmapID, String rootPath);

Usage Example:

// Check if MMKV files exist and are valid before creating instances
if (MMKV.checkExist("user_data")) {
    if (MMKV.isFileValid("user_data")) {
        MMKV userKv = MMKV.mmkvWithID("user_data");
        // File exists and is valid, safe to use
    } else {
        Log.w("MMKV", "User data file exists but is corrupted");
        // Handle corruption - maybe delete and recreate
    }
} else {
    Log.i("MMKV", "User data file doesn't exist, will be created");
    MMKV userKv = MMKV.mmkvWithID("user_data");
}

Constants

// Process mode constants
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;

Install with Tessl CLI

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

docs

instance-management.md

multi-process.md

namespace.md

tile.json

tessl/maven-com-tencent--mmkv