0
# Instance Creation and Management
1

2
MMKV supports multiple instances with unique identifiers, allowing applications to organize data into separate storage contexts. Instances can be configured for single or multi-process access, with optional encryption and custom storage locations.
3

4
## Capabilities
5

6
### Default Instance
7

8
Get the default MMKV instance, which is the most common usage pattern for simple applications.
9

10
```java { .api }
11
/**
12
 * Create the default MMKV instance in single-process mode.
13
 * 
14
 * @throws RuntimeException if there's a runtime error
15
 */
16
static MMKV defaultMMKV();
17

18
/**
19
 * Create the default MMKV instance in customize process mode, with an encryption key.
20
 * 
21
 * @param mode The process mode of the MMKV instance, defaults to SINGLE_PROCESS_MODE
22
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
23
 * @throws RuntimeException if there's a runtime error
24
 */
25
static MMKV defaultMMKV(int mode, String cryptKey);
26
```
27

28
**Usage Examples:**
29

30
```java
31
// Basic default instance
32
MMKV kv = MMKV.defaultMMKV();
33
kv.encode("user_id", 12345);
34

35
// Default instance with multi-process support and encryption
36
MMKV secureKv = MMKV.defaultMMKV(
37
    MMKV.MULTI_PROCESS_MODE, 
38
    "my-secret-key"
39
);
40
```
41

42
### Named Instances
43

44
Create MMKV instances with unique identifiers for organizing different types of data.
45

46
```java { .api }
47
/**
48
 * Create an MMKV instance with an unique ID (in single-process mode).
49
 * 
50
 * @param mmapID The unique ID of the MMKV instance
51
 * @throws RuntimeException if there's a runtime error
52
 */
53
static MMKV mmkvWithID(String mmapID);
54

55
/**
56
 * Create an MMKV instance in single-process or multi-process mode.
57
 * 
58
 * @param mmapID The unique ID of the MMKV instance
59
 * @param mode The process mode of the MMKV instance, defaults to SINGLE_PROCESS_MODE
60
 * @throws RuntimeException if there's a runtime error
61
 */
62
static MMKV mmkvWithID(String mmapID, int mode);
63

64
/**
65
 * Create an MMKV instance in single-process or multi-process mode.
66
 * 
67
 * @param mmapID The unique ID of the MMKV instance
68
 * @param mode The process mode of the MMKV instance, defaults to SINGLE_PROCESS_MODE
69
 * @param expectedCapacity The file size you expected when opening or creating file
70
 * @throws RuntimeException if there's a runtime error
71
 */
72
static MMKV mmkvWithID(String mmapID, int mode, long expectedCapacity);
73
```
74

75
**Usage Examples:**
76

77
```java
78
// Separate instances for different data types
79
MMKV userPrefs = MMKV.mmkvWithID("user_preferences");
80
MMKV appSettings = MMKV.mmkvWithID("app_settings");
81
MMKV cache = MMKV.mmkvWithID("cache_data");
82

83
// Multi-process instance with expected capacity
84
MMKV sharedData = MMKV.mmkvWithID(
85
    "shared_data", 
86
    MMKV.MULTI_PROCESS_MODE, 
87
    1024 * 1024  // 1MB expected capacity
88
);
89
```
90

91
### Encrypted Instances
92

93
Create MMKV instances with encryption for sensitive data storage.
94

95
```java { .api }
96
/**
97
 * Create an MMKV instance in customize process mode, with an encryption key.
98
 * 
99
 * @param mmapID The unique ID of the MMKV instance
100
 * @param mode The process mode of the MMKV instance, defaults to SINGLE_PROCESS_MODE
101
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
102
 * @throws RuntimeException if there's a runtime error
103
 */
104
static MMKV mmkvWithID(String mmapID, int mode, String cryptKey);
105
```
106

107
**Usage Examples:**
108

109
```java
110
// Encrypted instance for sensitive user data
111
MMKV secureStorage = MMKV.mmkvWithID(
112
    "secure_user_data",
113
    MMKV.SINGLE_PROCESS_MODE,
114
    "my-encryption-key"
115
);
116

117
secureStorage.encode("credit_card", cardNumber);
118
secureStorage.encode("auth_token", token);
119
```
120

121
### Custom Location Instances
122

123
Create MMKV instances in custom directories for organized storage.
124

125
```java { .api }
126
/**
127
 * Create an MMKV instance in customize folder.
128
 * 
129
 * @param mmapID The unique ID of the MMKV instance
130
 * @param rootPath The folder of the MMKV instance, defaults to $(FilesDir)/mmkv
131
 * @throws RuntimeException if there's a runtime error
132
 */
133
static MMKV mmkvWithID(String mmapID, String rootPath);
134

135
/**
136
 * Create an MMKV instance in customize folder.
137
 * 
138
 * @param mmapID The unique ID of the MMKV instance
139
 * @param rootPath The folder of the MMKV instance, defaults to $(FilesDir)/mmkv
140
 * @param expectedCapacity The file size you expected when opening or creating file
141
 * @throws RuntimeException if there's a runtime error
142
 */
143
static MMKV mmkvWithID(String mmapID, String rootPath, long expectedCapacity);
144
```
145

146
**Usage Examples:**
147

148
```java
149
// Store temporary data in cache directory
150
File cacheDir = new File(getCacheDir(), "mmkv_temp");
151
MMKV tempStorage = MMKV.mmkvWithID("temp_data", cacheDir.getAbsolutePath());
152

153
// Large data storage with expected capacity
154
MMKV largeData = MMKV.mmkvWithID(
155
    "large_dataset",
156
    "/data/data/com.myapp/large_storage",
157
    10 * 1024 * 1024  // 10MB expected
158
);
159
```
160

161
### Complete Configuration
162

163
Create MMKV instances with all available configuration options.
164

165
```java { .api }
166
/**
167
 * Create an MMKV instance with customize settings all in one.
168
 * 
169
 * @param mmapID The unique ID of the MMKV instance
170
 * @param mode The process mode of the MMKV instance, defaults to SINGLE_PROCESS_MODE
171
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
172
 * @param rootPath The folder of the MMKV instance, defaults to $(FilesDir)/mmkv
173
 * @param expectedCapacity The file size you expected when opening or creating file
174
 * @throws RuntimeException if there's a runtime error
175
 */
176
static MMKV mmkvWithID(String mmapID, int mode, String cryptKey, 
177
                      String rootPath, long expectedCapacity);
178

179
/**
180
 * Create an MMKV instance with customize settings all in one.
181
 * 
182
 * @param mmapID The unique ID of the MMKV instance
183
 * @param mode The process mode of the MMKV instance, defaults to SINGLE_PROCESS_MODE
184
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
185
 * @param rootPath The folder of the MMKV instance, defaults to $(FilesDir)/mmkv
186
 * @throws RuntimeException if there's a runtime error
187
 */
188
static MMKV mmkvWithID(String mmapID, int mode, String cryptKey, String rootPath);
189
```
190

191
**Usage Examples:**
192

193
```java
194
// Fully configured instance
195
MMKV fullyConfigured = MMKV.mmkvWithID(
196
    "my_custom_storage",           // Unique ID
197
    MMKV.MULTI_PROCESS_MODE,       // Multi-process support
198
    "secure-key-123",              // Encryption key
199
    "/custom/storage/path",        // Custom location
200
    5 * 1024 * 1024               // 5MB expected capacity
201
);
202
```
203

204
### Backup and Restore Instances
205

206
Create MMKV instances specifically for backup and restore operations.
207

208
```java { .api }
209
/**
210
 * Get an backed-up MMKV instance with customize settings all in one.
211
 * 
212
 * @param mmapID The unique ID of the MMKV instance
213
 * @param mode The process mode of the MMKV instance, defaults to SINGLE_PROCESS_MODE
214
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
215
 * @param rootPath The backup folder of the MMKV instance
216
 * @throws RuntimeException if there's a runtime error
217
 */
218
static MMKV backedUpMMKVWithID(String mmapID, int mode, String cryptKey, String rootPath);
219
```
220

221
**Usage Examples:**
222

223
```java
224
// Create backup instance
225
MMKV backupInstance = MMKV.backedUpMMKVWithID(
226
    "user_data_backup",
227
    MMKV.SINGLE_PROCESS_MODE,
228
    "backup-key",
229
    "/backup/location"
230
);
231
```
232

233
### Anonymous Shared Memory Instances
234

235
Create MMKV instances based on Anonymous Shared Memory for temporary, non-persistent storage.
236

237
```java { .api }
238
/**
239
 * Create an MMKV instance base on Anonymous Shared Memory, aka not synced to any disk files.
240
 * 
241
 * @param context The context of Android App, usually from Application
242
 * @param mmapID The unique ID of the MMKV instance
243
 * @param size The maximum size of the underlying Anonymous Shared Memory.
244
 *             Anonymous Shared Memory on Android can't grow dynamically, must set an appropriate size on creation
245
 * @param mode The process mode of the MMKV instance, defaults to SINGLE_PROCESS_MODE
246
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
247
 * @throws RuntimeException if there's a runtime error
248
 */
249
static MMKV mmkvWithAshmemID(Context context, String mmapID, int size, 
250
                            int mode, String cryptKey);
251

252
/**
253
 * Get an ashmem MMKV instance that has been initiated by another process.
254
 * Normally you should just call mmkvWithAshmemID instead.
255
 * 
256
 * @param mmapID The unique ID of the MMKV instance
257
 * @param fd The file descriptor of the ashmem of the MMKV file, transferred from another process by binder
258
 * @param metaFD The file descriptor of the ashmem of the MMKV crc file, transferred from another process by binder
259
 * @param cryptKey The encryption key of the MMKV instance (no more than 16 bytes)
260
 * @throws RuntimeException If any failure in JNI or runtime
261
 */
262
static MMKV mmkvWithAshmemFD(String mmapID, int fd, int metaFD, String cryptKey);
263
```
264

265
**Usage Examples:**
266

267
```java
268
// Temporary in-memory storage (not persisted to disk)
269
MMKV tempMemory = MMKV.mmkvWithAshmemID(
270
    this,
271
    "temp_session_data",
272
    1024 * 1024,              // 1MB max size
273
    MMKV.SINGLE_PROCESS_MODE,
274
    null                      // No encryption
275
);
276

277
// Store temporary session data
278
tempMemory.encode("session_id", sessionId);
279
tempMemory.encode("temp_cache", cacheData);
280
```
281

282
### Namespace Management
283

284
Work with custom namespaces that provide isolated storage contexts.
285

286
```java { .api }
287
/**
288
 * @param dir the customize root directory of a NameSpace
289
 * @return a NameSpace with custom root dir
290
 * @throws RuntimeException if there's an runtime error
291
 */
292
static NameSpace nameSpace(String dir);
293

294
/**
295
 * Identical with the original MMKV with the global root dir
296
 * @throws RuntimeException if there's an runtime error
297
 */
298
static NameSpace defaultNameSpace();
299
```
300

301
**Usage Examples:**
302

303
```java
304
// Create custom namespace
305
NameSpace userNamespace = MMKV.nameSpace("/user/storage/path");
306
MMKV userKv = userNamespace.mmkvWithID("user_data");
307

308
// Use default namespace
309
NameSpace defaultNS = MMKV.defaultNameSpace();
310
MMKV defaultKv = defaultNS.mmkvWithID("app_data");
311
```
312

313
### Instance Information
314

315
Get information about MMKV instances.
316

317
```java { .api }
318
/**
319
 * @return The unique ID of the MMKV instance
320
 */
321
String mmapID();
322

323
/**
324
 * Check if this instance is in multi-process mode.
325
 */
326
boolean isMultiProcess();
327

328
/**
329
 * Check if this instance is in read-only mode.
330
 */
331
boolean isReadOnly();
332

333
/**
334
 * @return The file descriptor of the ashmem of the MMKV file
335
 */
336
int ashmemFD();
337

338
/**
339
 * @return The file descriptor of the ashmem of the MMKV crc file
340
 */
341
int ashmemMetaFD();
342
```
343

344
**Usage Examples:**
345

346
```java
347
MMKV kv = MMKV.mmkvWithID("my_instance", MMKV.MULTI_PROCESS_MODE);
348

349
String id = kv.mmapID();                    // "my_instance"
350
boolean isMultiProcess = kv.isMultiProcess(); // true
351
boolean isReadOnly = kv.isReadOnly();         // false
352
```
353

354
## Types
355

356
```java { .api }
357
/**
358
 * A facade wraps custom root directory
359
 */
360
class NameSpace {
361
    /**
362
     * @return The root folder of this NameSpace
363
     */
364
    String getRootDir();
365
    
366
    // Instance creation methods (same signatures as MMKV static methods)
367
    MMKV mmkvWithID(String mmapID);
368
    MMKV mmkvWithID(String mmapID, int mode);
369
    MMKV mmkvWithID(String mmapID, int mode, long expectedCapacity);
370
    MMKV mmkvWithID(String mmapID, int mode, String cryptKey);
371
    MMKV mmkvWithID(String mmapID, int mode, String cryptKey, long expectedCapacity);
372
    
373
    // Utility methods for this namespace
374
    boolean isFileValid(String mmapID);
375
    boolean removeStorage(String mmapID);
376
    boolean checkExist(String mmapID);
377
    boolean backupOneToDirectory(String mmapID, String dstDir);
378
    boolean restoreOneMMKVFromDirectory(String mmapID, String srcDir);
379
}
380

381
/**
382
 * A helper class for MMKV based on Anonymous Shared Memory.
383
 */
384
class ParcelableMMKV implements Parcelable {
385
    ParcelableMMKV(MMKV mmkv);
386
    MMKV toMMKV();
387
    
388
    // Parcelable implementation
389
    int describeContents();
390
    void writeToParcel(Parcel dest, int flags);
391
    static final Parcelable.Creator<ParcelableMMKV> CREATOR;
392
}
393
```