Initialization and Setup

/**
 * Initialize MMKV with default configuration.
 * You must call one of the initialize() methods on App startup process before using MMKV.
 * 
 * @param context The context of Android App, usually from Application
 * @return The root folder of MMKV, defaults to $(FilesDir)/mmkv
 */
static String initialize(Context context);

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        
        // Initialize MMKV with default settings
        String rootDir = MMKV.initialize(this);
        Log.d("MMKV", "Initialized with root: " + rootDir);
    }
}

/**
 * Initialize MMKV with customize log level.
 * You must call one of the initialize() methods on App startup process before using MMKV.
 * 
 * @param context The context of Android App, usually from Application
 * @param logLevel The log level of MMKV, defaults to LevelInfo
 * @return The root folder of MMKV, defaults to $(FilesDir)/mmkv
 */
static String initialize(Context context, MMKVLogLevel logLevel);

// Debug build with verbose logging
String rootDir = MMKV.initialize(this, MMKVLogLevel.LevelDebug);

// Production build with minimal logging
String rootDir = MMKV.initialize(this, MMKVLogLevel.LevelError);

/**
 * Initialize MMKV with a 3rd library loader.
 * You must call one of the initialize() methods on App startup process before using MMKV.
 * 
 * @param context The context of Android App, usually from Application
 * @param loader The 3rd library loader (for example, the ReLinker)
 * @return The root folder of MMKV, defaults to $(FilesDir)/mmkv
 */
static String initialize(Context context, LibLoader loader);

/**
 * Initialize MMKV with a 3rd library loader, and customize log level.
 * 
 * @param context The context of Android App, usually from Application
 * @param loader The 3rd library loader (for example, the ReLinker)
 * @param logLevel The log level of MMKV, defaults to LevelInfo
 * @return The root folder of MMKV, defaults to $(FilesDir)/mmkv
 */
static String initialize(Context context, LibLoader loader, MMKVLogLevel logLevel);

// Using ReLinker for safer native library loading
MMKV.initialize(this, new LibLoader() {
    @Override
    public void loadLibrary(String libName) {
        ReLinker.loadLibrary(MyApplication.this, libName);
    }
});

/**
 * Initialize MMKV with customize root folder.
 * You must call one of the initialize() methods on App startup process before using MMKV.
 * 
 * @param context The context of Android App, usually from Application
 * @param rootDir The root folder of MMKV, defaults to $(FilesDir)/mmkv
 * @return The root folder of MMKV
 */
static String initialize(Context context, String rootDir);

/**
 * Initialize MMKV with customize root folder, and log level.
 * 
 * @param context The context of Android App, usually from Application
 * @param rootDir The root folder of MMKV, defaults to $(FilesDir)/mmkv
 * @param logLevel The log level of MMKV, defaults to LevelInfo
 * @return The root folder of MMKV
 */
static String initialize(Context context, String rootDir, MMKVLogLevel logLevel);

// Store MMKV files in external storage
File externalDir = new File(getExternalFilesDir(null), "mmkv");
String rootDir = MMKV.initialize(this, externalDir.getAbsolutePath());

/**
 * Initialize MMKV with customize settings.
 * You must call one of the initialize() methods on App startup process before using MMKV.
 * 
 * @param context The context of Android App, usually from Application
 * @param rootDir The root folder of MMKV, defaults to $(FilesDir)/mmkv
 * @param loader The 3rd library loader (for example, the ReLinker)
 * @param logLevel The log level of MMKV, defaults to LevelInfo
 * @param handler Custom handler for error recovery and log redirection
 * @return The root folder of MMKV
 */
static String initialize(Context context, String rootDir, LibLoader loader, 
                        MMKVLogLevel logLevel, MMKVHandler handler);

MMKV.initialize(
    this,
    customRootDir,
    customLoader,
    MMKVLogLevel.LevelInfo,
    new MMKVHandler() {
        @Override
        public MMKVRecoverStrategic onMMKVCRCCheckFail(String mmapID) {
            // Try to recover data on CRC failures
            return MMKVRecoverStrategic.OnErrorRecover;
        }
        
        @Override
        public MMKVRecoverStrategic onMMKVFileLengthError(String mmapID) {
            // Discard data on file length errors
            return MMKVRecoverStrategic.OnErrorDiscard;
        }
        
        @Override
        public boolean wantLogRedirecting() {
            return true; // Enable custom log handling
        }
        
        @Override
        public void mmkvLog(MMKVLogLevel level, String file, int line, 
                           String function, String message) {
            // Custom log implementation
            Log.println(level.ordinal(), "MMKV", message);
        }
    }
);

/**
 * Set the log level of MMKV.
 * 
 * @param level Defaults to LevelInfo
 */
static void setLogLevel(MMKVLogLevel level);

/**
 * Get the root folder of MMKV.
 * 
 * @return The root folder of MMKV, defaults to $(FilesDir)/mmkv
 */
static String getRootDir();

/**
 * Notify MMKV that App is about to exit. 
 * It's totally fine not calling it at all.
 */
static void onExit();

// Change log level at runtime
MMKV.setLogLevel(MMKVLogLevel.LevelWarning);

// Get current root directory
String currentRoot = MMKV.getRootDir();

// Optional cleanup on app exit
@Override
protected void onDestroy() {
    super.onDestroy();
    MMKV.onExit();
}

/**
 * The interface for providing a 3rd library loader (the ReLinker, etc).
 */
interface LibLoader {
    void loadLibrary(String libName);
}

/**
 * Callback handler for MMKV.
 * Callback is called on the operating thread of the MMKV instance.
 */
interface MMKVHandler {
    /**
     * By default MMKV will discard all data on crc32-check failure.
     * @param mmapID The unique ID of the MMKV instance
     * @return Return OnErrorRecover to recover any data on the file
     */
    MMKVRecoverStrategic onMMKVCRCCheckFail(String mmapID);
    
    /**
     * By default MMKV will discard all data on file length mismatch.
     * @param mmapID The unique ID of the MMKV instance
     * @return Return OnErrorRecover to recover any data on the file
     */
    MMKVRecoverStrategic onMMKVFileLengthError(String mmapID);
    
    /**
     * @return Return False if you don't want log redirecting
     */
    boolean wantLogRedirecting();
    
    /**
     * Log Redirecting.
     * @param level The level of this log
     * @param file The file name of this log
     * @param line The line of code of this log
     * @param function The function name of this log
     * @param message The content of this log
     */
    void mmkvLog(MMKVLogLevel level, String file, int line, String function, String message);
}

/**
 * Exception thrown for unsupported architectures (32-bit apps).
 */
class UnsupportedArchitectureException extends RuntimeException {
    UnsupportedArchitectureException(String message);
}