0
# Initialization and Setup
1

2
MMKV requires initialization before any instances can be created or used. The initialization process loads native libraries, sets up the root storage directory, and configures logging and error handling.
3

4
## Capabilities
5

6
### Basic Initialization
7

8
Initialize MMKV with default settings using the 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
 * 
15
 * @param context The context of Android App, usually from Application
16
 * @return The root folder of MMKV, defaults to $(FilesDir)/mmkv
17
 */
18
static String initialize(Context context);
19
```
20

21
**Usage Example:**
22

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

36
### Initialize with Log Level
37

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

40
```java { .api }
41
/**
42
 * Initialize MMKV with customize log level.
43
 * You must call one of the initialize() methods on App startup process before using MMKV.
44
 * 
45
 * @param context The context of Android App, usually from Application
46
 * @param logLevel The log level of MMKV, defaults to LevelInfo
47
 * @return The root folder of MMKV, defaults to $(FilesDir)/mmkv
48
 */
49
static String initialize(Context context, MMKVLogLevel logLevel);
50
```
51

52
**Usage Example:**
53

54
```java
55
// Debug build with verbose logging
56
String rootDir = MMKV.initialize(this, MMKVLogLevel.LevelDebug);
57

58
// Production build with minimal logging
59
String rootDir = MMKV.initialize(this, MMKVLogLevel.LevelError);
60
```
61

62
### Initialize with Custom Library Loader
63

64
Initialize MMKV with a third-party library loader like ReLinker for more robust native library loading.
65

66
```java { .api }
67
/**
68
 * Initialize MMKV with a 3rd library loader.
69
 * You must call one of the initialize() methods on App startup process before using MMKV.
70
 * 
71
 * @param context The context of Android App, usually from Application
72
 * @param loader The 3rd library loader (for example, the ReLinker)
73
 * @return The root folder of MMKV, defaults to $(FilesDir)/mmkv
74
 */
75
static String initialize(Context context, LibLoader loader);
76

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

88
**Usage Example:**
89

90
```java
91
// Using ReLinker for safer native library loading
92
MMKV.initialize(this, new LibLoader() {
93
    @Override
94
    public void loadLibrary(String libName) {
95
        ReLinker.loadLibrary(MyApplication.this, libName);
96
    }
97
});
98
```
99

100
### Initialize with Custom Root Directory
101

102
Initialize MMKV with a custom storage directory instead of the default location.
103

104
```java { .api }
105
/**
106
 * Initialize MMKV with customize root folder.
107
 * You must call one of the initialize() methods on App startup process before using MMKV.
108
 * 
109
 * @param context The context of Android App, usually from Application
110
 * @param rootDir The root folder of MMKV, defaults to $(FilesDir)/mmkv
111
 * @return The root folder of MMKV
112
 */
113
static String initialize(Context context, String rootDir);
114

115
/**
116
 * Initialize MMKV with customize root folder, and log level.
117
 * 
118
 * @param context The context of Android App, usually from Application
119
 * @param rootDir The root folder of MMKV, defaults to $(FilesDir)/mmkv
120
 * @param logLevel The log level of MMKV, defaults to LevelInfo
121
 * @return The root folder of MMKV
122
 */
123
static String initialize(Context context, String rootDir, MMKVLogLevel logLevel);
124
```
125

126
**Usage Example:**
127

128
```java
129
// Store MMKV files in external storage
130
File externalDir = new File(getExternalFilesDir(null), "mmkv");
131
String rootDir = MMKV.initialize(this, externalDir.getAbsolutePath());
132
```
133

134
### Full Initialization with Handler
135

136
Complete initialization with all options including error handling and log redirection.
137

138
```java { .api }
139
/**
140
 * Initialize MMKV with customize settings.
141
 * You must call one of the initialize() methods on App startup process before using MMKV.
142
 * 
143
 * @param context The context of Android App, usually from Application
144
 * @param rootDir The root folder of MMKV, defaults to $(FilesDir)/mmkv
145
 * @param loader The 3rd library loader (for example, the ReLinker)
146
 * @param logLevel The log level of MMKV, defaults to LevelInfo
147
 * @param handler Custom handler for error recovery and log redirection
148
 * @return The root folder of MMKV
149
 */
150
static String initialize(Context context, String rootDir, LibLoader loader, 
151
                        MMKVLogLevel logLevel, MMKVHandler handler);
152
```
153

154
**Usage Example:**
155

156
```java
157
MMKV.initialize(
158
    this,
159
    customRootDir,
160
    customLoader,
161
    MMKVLogLevel.LevelInfo,
162
    new MMKVHandler() {
163
        @Override
164
        public MMKVRecoverStrategic onMMKVCRCCheckFail(String mmapID) {
165
            // Try to recover data on CRC failures
166
            return MMKVRecoverStrategic.OnErrorRecover;
167
        }
168
        
169
        @Override
170
        public MMKVRecoverStrategic onMMKVFileLengthError(String mmapID) {
171
            // Discard data on file length errors
172
            return MMKVRecoverStrategic.OnErrorDiscard;
173
        }
174
        
175
        @Override
176
        public boolean wantLogRedirecting() {
177
            return true; // Enable custom log handling
178
        }
179
        
180
        @Override
181
        public void mmkvLog(MMKVLogLevel level, String file, int line, 
182
                           String function, String message) {
183
            // Custom log implementation
184
            Log.println(level.ordinal(), "MMKV", message);
185
        }
186
    }
187
);
188
```
189

190
### Global Configuration
191

192
Utility methods for configuring MMKV behavior after initialization.
193

194
```java { .api }
195
/**
196
 * Set the log level of MMKV.
197
 * 
198
 * @param level Defaults to LevelInfo
199
 */
200
static void setLogLevel(MMKVLogLevel level);
201

202
/**
203
 * Get the root folder of MMKV.
204
 * 
205
 * @return The root folder of MMKV, defaults to $(FilesDir)/mmkv
206
 */
207
static String getRootDir();
208

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

216
**Usage Example:**
217

218
```java
219
// Change log level at runtime
220
MMKV.setLogLevel(MMKVLogLevel.LevelWarning);
221

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

225
// Optional cleanup on app exit
226
@Override
227
protected void onDestroy() {
228
    super.onDestroy();
229
    MMKV.onExit();
230
}
231
```
232

233
## Types
234

235
```java { .api }
236
/**
237
 * The interface for providing a 3rd library loader (the ReLinker, etc).
238
 */
239
interface LibLoader {
240
    void loadLibrary(String libName);
241
}
242

243
/**
244
 * Callback handler for MMKV.
245
 * Callback is called on the operating thread of the MMKV instance.
246
 */
247
interface MMKVHandler {
248
    /**
249
     * By default MMKV will discard all data on crc32-check failure.
250
     * @param mmapID The unique ID of the MMKV instance
251
     * @return Return OnErrorRecover to recover any data on the file
252
     */
253
    MMKVRecoverStrategic onMMKVCRCCheckFail(String mmapID);
254
    
255
    /**
256
     * By default MMKV will discard all data on file length mismatch.
257
     * @param mmapID The unique ID of the MMKV instance
258
     * @return Return OnErrorRecover to recover any data on the file
259
     */
260
    MMKVRecoverStrategic onMMKVFileLengthError(String mmapID);
261
    
262
    /**
263
     * @return Return False if you don't want log redirecting
264
     */
265
    boolean wantLogRedirecting();
266
    
267
    /**
268
     * Log Redirecting.
269
     * @param level The level of this log
270
     * @param file The file name of this log
271
     * @param line The line of code of this log
272
     * @param function The function name of this log
273
     * @param message The content of this log
274
     */
275
    void mmkvLog(MMKVLogLevel level, String file, int line, String function, String message);
276
}
277

278
/**
279
 * Exception thrown for unsupported architectures (32-bit apps).
280
 */
281
class UnsupportedArchitectureException extends RuntimeException {
282
    UnsupportedArchitectureException(String message);
283
}
284
```