Instance Creation and Management

/**
 * Create the default MMKV instance in single-process mode.
 * 
 * @throws RuntimeException if there's a runtime error
 */
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)
 * @throws RuntimeException if there's a runtime error
 */
static MMKV defaultMMKV(int mode, String cryptKey);

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

// Default instance with multi-process support and encryption
MMKV secureKv = MMKV.defaultMMKV(
    MMKV.MULTI_PROCESS_MODE, 
    "my-secret-key"
);

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

/**
 * 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
 * @param expectedCapacity The file size you expected when opening or creating file
 * @throws RuntimeException if there's a runtime error
 */
static MMKV mmkvWithID(String mmapID, int mode, long expectedCapacity);

// Separate instances for different data types
MMKV userPrefs = MMKV.mmkvWithID("user_preferences");
MMKV appSettings = MMKV.mmkvWithID("app_settings");
MMKV cache = MMKV.mmkvWithID("cache_data");

// Multi-process instance with expected capacity
MMKV sharedData = MMKV.mmkvWithID(
    "shared_data", 
    MMKV.MULTI_PROCESS_MODE, 
    1024 * 1024  // 1MB expected capacity
);

/**
 * 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, defaults to SINGLE_PROCESS_MODE
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
 * @throws RuntimeException if there's a runtime error
 */
static MMKV mmkvWithID(String mmapID, int mode, String cryptKey);

// Encrypted instance for sensitive user data
MMKV secureStorage = MMKV.mmkvWithID(
    "secure_user_data",
    MMKV.SINGLE_PROCESS_MODE,
    "my-encryption-key"
);

secureStorage.encode("credit_card", cardNumber);
secureStorage.encode("auth_token", token);

/**
 * 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
 * @throws RuntimeException if there's a runtime error
 */
static MMKV mmkvWithID(String mmapID, String rootPath);

/**
 * 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
 * @param expectedCapacity The file size you expected when opening or creating file
 * @throws RuntimeException if there's a runtime error
 */
static MMKV mmkvWithID(String mmapID, String rootPath, long expectedCapacity);

// Store temporary data in cache directory
File cacheDir = new File(getCacheDir(), "mmkv_temp");
MMKV tempStorage = MMKV.mmkvWithID("temp_data", cacheDir.getAbsolutePath());

// Large data storage with expected capacity
MMKV largeData = MMKV.mmkvWithID(
    "large_dataset",
    "/data/data/com.myapp/large_storage",
    10 * 1024 * 1024  // 10MB expected
);

/**
 * 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, defaults to SINGLE_PROCESS_MODE
 * @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
 * @throws RuntimeException if there's a runtime error
 */
static MMKV mmkvWithID(String mmapID, int mode, String cryptKey, 
                      String rootPath, long expectedCapacity);

/**
 * 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, defaults to SINGLE_PROCESS_MODE
 * @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
 * @throws RuntimeException if there's a runtime error
 */
static MMKV mmkvWithID(String mmapID, int mode, String cryptKey, String rootPath);

// Fully configured instance
MMKV fullyConfigured = MMKV.mmkvWithID(
    "my_custom_storage",           // Unique ID
    MMKV.MULTI_PROCESS_MODE,       // Multi-process support
    "secure-key-123",              // Encryption key
    "/custom/storage/path",        // Custom location
    5 * 1024 * 1024               // 5MB expected capacity
);

/**
 * Get an 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, defaults to SINGLE_PROCESS_MODE
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
 * @param rootPath The backup folder of the MMKV instance
 * @throws RuntimeException if there's a runtime error
 */
static MMKV backedUpMMKVWithID(String mmapID, int mode, String cryptKey, String rootPath);

// Create backup instance
MMKV backupInstance = MMKV.backedUpMMKVWithID(
    "user_data_backup",
    MMKV.SINGLE_PROCESS_MODE,
    "backup-key",
    "/backup/location"
);

/**
 * 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.
 *             Anonymous Shared Memory on Android can't grow dynamically, must set an appropriate size on creation
 * @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)
 * @throws RuntimeException if there's a runtime error
 */
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.
 * Normally you should just call mmkvWithAshmemID instead.
 * 
 * @param mmapID The unique ID of the MMKV instance
 * @param fd The file descriptor of the ashmem of the MMKV file, transferred from another process by binder
 * @param metaFD The file descriptor of the ashmem of the MMKV crc file, transferred from another process by binder
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
 * @throws RuntimeException If any failure in JNI or runtime
 */
static MMKV mmkvWithAshmemFD(String mmapID, int fd, int metaFD, String cryptKey);

// Temporary in-memory storage (not persisted to disk)
MMKV tempMemory = MMKV.mmkvWithAshmemID(
    this,
    "temp_session_data",
    1024 * 1024,              // 1MB max size
    MMKV.SINGLE_PROCESS_MODE,
    null                      // No encryption
);

// Store temporary session data
tempMemory.encode("session_id", sessionId);
tempMemory.encode("temp_cache", cacheData);

/**
 * @param dir the customize root directory of a NameSpace
 * @return a NameSpace with custom root dir
 * @throws RuntimeException if there's an runtime error
 */
static NameSpace nameSpace(String dir);

/**
 * Identical with the original MMKV with the global root dir
 * @throws RuntimeException if there's an runtime error
 */
static NameSpace defaultNameSpace();

// Create custom namespace
NameSpace userNamespace = MMKV.nameSpace("/user/storage/path");
MMKV userKv = userNamespace.mmkvWithID("user_data");

// Use default namespace
NameSpace defaultNS = MMKV.defaultNameSpace();
MMKV defaultKv = defaultNS.mmkvWithID("app_data");

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

/**
 * Check if this instance is in multi-process mode.
 */
boolean isMultiProcess();

/**
 * Check if this instance is in read-only mode.
 */
boolean isReadOnly();

/**
 * @return The file descriptor of the ashmem of the MMKV file
 */
int ashmemFD();

/**
 * @return The file descriptor of the ashmem of the MMKV crc file
 */
int ashmemMetaFD();

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

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

/**
 * A facade wraps custom root directory
 */
class NameSpace {
    /**
     * @return The root folder of this NameSpace
     */
    String getRootDir();
    
    // Instance creation methods (same signatures as MMKV static methods)
    MMKV mmkvWithID(String mmapID);
    MMKV mmkvWithID(String mmapID, int mode);
    MMKV mmkvWithID(String mmapID, int mode, long expectedCapacity);
    MMKV mmkvWithID(String mmapID, int mode, String cryptKey);
    MMKV mmkvWithID(String mmapID, int mode, String cryptKey, long expectedCapacity);
    
    // Utility methods for this namespace
    boolean isFileValid(String mmapID);
    boolean removeStorage(String mmapID);
    boolean checkExist(String mmapID);
    boolean backupOneToDirectory(String mmapID, String dstDir);
    boolean restoreOneMMKVFromDirectory(String mmapID, String srcDir);
}

/**
 * A helper class for MMKV based on Anonymous Shared Memory.
 */
class ParcelableMMKV implements Parcelable {
    ParcelableMMKV(MMKV mmkv);
    MMKV toMMKV();
    
    // Parcelable implementation
    int describeContents();
    void writeToParcel(Parcel dest, int flags);
    static final Parcelable.Creator<ParcelableMMKV> CREATOR;
}