0
# Initialization and Setup
1

2
Core initialization functionality for setting up MMKV in Android applications. MMKV must be initialized once during application startup before creating any MMKV instances.
3

4
## Capabilities
5

6
### Basic Initialization
7

8
Initialize MMKV with default settings using application context.
9

10
```java { .api }
11
/**
12
 * Initialize MMKV with default configuration.
13
 * You must call one of the initialize() methods on App startup process before using MMKV.
14
 * @param context The context of Android App, usually from Application
15
 * @return The root folder of MMKV, defaults to $(FilesDir)/mmkv
16
 */
17
public static String initialize(Context context);
18
```
19

20
**Usage Example:**
21

22
```java
23
public class MyApplication extends Application {
24
    @Override
25
    public void onCreate() {
26
        super.onCreate();
27
        
28
        // Initialize MMKV with default settings
29
        String rootDir = MMKV.initialize(this);
30
        Log.d("MMKV", "MMKV initialized with root: " + rootDir);
31
    }
32
}
33
```
34

35
### Initialization with Log Level
36

37
Initialize MMKV with custom log level for debugging or production builds.
38

39
```java { .api }
40
/**
41
 * Initialize MMKV with customize log level.
42
 * @param context The context of Android App, usually from Application
43
 * @param logLevel The log level of MMKV, defaults to MMKVLogLevel.LevelInfo
44
 * @return The root folder of MMKV
45
 */
46
public static String initialize(Context context, MMKVLogLevel logLevel);
47
```
48

49
**Usage Example:**
50

51
```java
52
// Debug build with verbose logging
53
String rootDir = MMKV.initialize(this, MMKVLogLevel.LevelDebug);
54

55
// Production build with minimal logging
56
String rootDir = MMKV.initialize(this, MMKVLogLevel.LevelError);
57
```
58

59
### Initialization with Custom Root Directory
60

61
Initialize MMKV with a custom storage directory.
62

63
```java { .api }
64
/**
65
 * Initialize MMKV with customize root folder.
66
 * @param context The context of Android App, usually from Application
67
 * @param rootDir The root folder of MMKV, defaults to $(FilesDir)/mmkv
68
 * @return The root folder of MMKV
69
 */
70
public static String initialize(Context context, String rootDir);
71

72
/**
73
 * Initialize MMKV with customize root folder and log level.
74
 * @param context The context of Android App, usually from Application
75
 * @param rootDir The root folder of MMKV
76
 * @param logLevel The log level of MMKV
77
 * @return The root folder of MMKV
78
 */
79
public static String initialize(Context context, String rootDir, MMKVLogLevel logLevel);
80
```
81

82
**Usage Example:**
83

84
```java
85
// Use custom directory on external storage
86
File customDir = new File(getExternalFilesDir(null), "custom_mmkv");
87
String rootDir = MMKV.initialize(this, customDir.getAbsolutePath());
88
```
89

90
### Initialization with Library Loader
91

92
Initialize MMKV with a custom library loader (e.g., ReLinker) for enhanced native library loading reliability.
93

94
```java { .api }
95
/**
96
 * Initialize MMKV with a 3rd library loader.
97
 * @param context The context of Android App, usually from Application
98
 * @param loader The 3rd library loader (for example, the ReLinker)
99
 * @return The root folder of MMKV
100
 */
101
public static String initialize(Context context, LibLoader loader);
102

103
/**
104
 * Initialize MMKV with a 3rd library loader and customize log level.
105
 * @param context The context of Android App, usually from Application
106
 * @param loader The 3rd library loader
107
 * @param logLevel The log level of MMKV
108
 * @return The root folder of MMKV
109
 */
110
public static String initialize(Context context, LibLoader loader, MMKVLogLevel logLevel);
111
```
112

113
**Usage Example:**
114

115
```java
116
// Using ReLinker for safer native library loading
117
MMKV.LibLoader relinkerLoader = new MMKV.LibLoader() {
118
    @Override
119
    public void loadLibrary(String libName) {
120
        ReLinker.loadLibrary(MyApplication.this, libName);
121
    }
122
};
123
String rootDir = MMKV.initialize(this, relinkerLoader, MMKVLogLevel.LevelInfo);
124
```
125

126
### Full Initialization
127

128
Complete initialization with all customization options including error handling callbacks.
129

130
```java { .api }
131
/**
132
 * Initialize MMKV with customize settings.
133
 * @param context The context of Android App, usually from Application
134
 * @param rootDir The root folder of MMKV
135
 * @param loader The 3rd library loader (optional)
136
 * @param logLevel The log level of MMKV
137
 * @param handler The callback handler for error recovery and logging (optional)
138
 * @return The root folder of MMKV
139
 */
140
public static String initialize(Context context, String rootDir, LibLoader loader, MMKVLogLevel logLevel, MMKVHandler handler);
141
```
142

143
**Usage Example:**
144

145
```java
146
MMKVHandler customHandler = new MMKVHandler() {
147
    @Override
148
    public MMKVRecoverStrategic onMMKVCRCCheckFail(String mmapID) {
149
        Log.w("MMKV", "CRC check failed for " + mmapID);
150
        return MMKVRecoverStrategic.OnErrorRecover;
151
    }
152
    
153
    @Override
154
    public MMKVRecoverStrategic onMMKVFileLengthError(String mmapID) {
155
        Log.w("MMKV", "File length error for " + mmapID);
156
        return MMKVRecoverStrategic.OnErrorRecover;
157
    }
158
    
159
    @Override
160
    public boolean wantLogRedirecting() {
161
        return true; // Redirect MMKV logs to custom handler
162
    }
163
    
164
    @Override
165
    public void mmkvLog(MMKVLogLevel level, String file, int line, String function, String message) {
166
        Log.d("MMKV-Custom", message);
167
    }
168
};
169

170
String rootDir = MMKV.initialize(
171
    this,
172
    getFilesDir().getAbsolutePath() + "/mmkv",
173
    null,
174
    MMKVLogLevel.LevelInfo,
175
    customHandler
176
);
177
```
178

179
### Global Settings
180

181
Static methods for managing global MMKV settings.
182

183
```java { .api }
184
/**
185
 * Set the log level of MMKV.
186
 * @param level Defaults to MMKVLogLevel.LevelInfo
187
 */
188
public static void setLogLevel(MMKVLogLevel level);
189

190
/**
191
 * Get the root folder of MMKV.
192
 * @return The root folder of MMKV, defaults to $(FilesDir)/mmkv
193
 */
194
public static String getRootDir();
195

196
/**
197
 * Get the device's memory page size.
198
 * @return The device's memory page size
199
 */
200
public static int pageSize();
201

202
/**
203
 * Get the version of MMKV.
204
 * @return The version of MMKV
205
 */
206
public static String version();
207

208
/**
209
 * Notify MMKV that App is about to exit. It's totally fine not calling it at all.
210
 */
211
public static void onExit();
212
```
213

214
**Usage Example:**
215

216
```java
217
// Change log level at runtime
218
MMKV.setLogLevel(MMKVLogLevel.LevelDebug);
219

220
// Get version information
221
String version = MMKV.version();
222
Log.i("MMKV", "Using MMKV version: " + version);
223

224
// Get system page size
225
int pageSize = MMKV.pageSize();
226
Log.i("MMKV", "System page size: " + pageSize + " bytes");
227

228
// Cleanup on app exit (optional)
229
@Override
230
protected void onDestroy() {
231
    super.onDestroy();
232
    MMKV.onExit();
233
}
234
```
235

236
### Process Mode Management
237

238
Control process mode checking for debugging multi-process access patterns.
239

240
```java { .api }
241
/**
242
 * Manually enable the process mode checker.
243
 * By default, it's automatically enabled in DEBUG build, and disabled in RELEASE build.
244
 */
245
public static void enableProcessModeChecker();
246

247
/**
248
 * Manually disable the process mode checker.
249
 * By default, it's automatically enabled in DEBUG build, and disabled in RELEASE build.
250
 */
251
public static void disableProcessModeChecker();
252
```
253

254
**Usage Example:**
255

256
```java
257
// Enable process mode checking in production for debugging
258
if (BuildConfig.DEBUG || isDebuggingMultiProcess) {
259
    MMKV.enableProcessModeChecker();
260
} else {
261
    MMKV.disableProcessModeChecker();
262
}
263
```
264

265
## Types
266

267
```java { .api }
268
public interface LibLoader {
269
    void loadLibrary(String libName);
270
}
271

272
public interface MMKVHandler {
273
    MMKVRecoverStrategic onMMKVCRCCheckFail(String mmapID);
274
    MMKVRecoverStrategic onMMKVFileLengthError(String mmapID);
275
    boolean wantLogRedirecting();
276
    void mmkvLog(MMKVLogLevel level, String file, int line, String function, String message);
277
}
278

279
public enum MMKVLogLevel {
280
    LevelDebug,    // Debug level. Not available for release/production build
281
    LevelInfo,     // Info level. The default level
282
    LevelWarning,  // Warning level
283
    LevelError,    // Error level
284
    LevelNone      // Special level for disabling all logging
285
}
286

287
public enum MMKVRecoverStrategic {
288
    OnErrorDiscard,  // The default strategic is to discard everything on errors
289
    OnErrorRecover   // The recover strategic will try to recover as much data as possible
290
}
291
```