0
# SharedPreferences Compatibility
1

2
MMKV provides full compatibility with Android's SharedPreferences interface, serving as a drop-in replacement with significantly better performance. The MMKV class implements both SharedPreferences and SharedPreferences.Editor interfaces.
3

4
## Capabilities
5

6
### SharedPreferences Interface
7

8
MMKV implements the standard SharedPreferences interface for seamless migration from existing code.
9

10
```java { .api }
11
/**
12
 * Retrieve all values. Intentionally not supported by MMKV.
13
 * Use allKeys() instead.
14
 * @throws UnsupportedOperationException Always thrown
15
 */
16
Map<String, ?> getAll();
17

18
/**
19
 * Retrieve a string value
20
 * @param key The name of the preference to retrieve
21
 * @param defValue Value to return if this preference does not exist
22
 * @return The preference value if it exists, or defValue
23
 */
24
String getString(String key, String defValue);
25

26
/**
27
 * Retrieve a string set value
28
 * @param key The name of the preference to retrieve
29
 * @param defValues Values to return if this preference does not exist
30
 * @return The preference value if it exists, or defValues
31
 */
32
Set<String> getStringSet(String key, Set<String> defValues);
33

34
/**
35
 * Retrieve an integer value
36
 * @param key The name of the preference to retrieve
37
 * @param defValue Value to return if this preference does not exist
38
 * @return The preference value if it exists, or defValue
39
 */
40
int getInt(String key, int defValue);
41

42
/**
43
 * Retrieve a long value
44
 * @param key The name of the preference to retrieve
45
 * @param defValue Value to return if this preference does not exist
46
 * @return The preference value if it exists, or defValue
47
 */
48
long getLong(String key, long defValue);
49

50
/**
51
 * Retrieve a float value
52
 * @param key The name of the preference to retrieve
53
 * @param defValue Value to return if this preference does not exist
54
 * @return The preference value if it exists, or defValue
55
 */
56
float getFloat(String key, float defValue);
57

58
/**
59
 * Retrieve a boolean value
60
 * @param key The name of the preference to retrieve
61
 * @param defValue Value to return if this preference does not exist
62
 * @return The preference value if it exists, or defValue
63
 */
64
boolean getBoolean(String key, boolean defValue);
65

66
/**
67
 * Checks whether the preferences contains a preference
68
 * @param key The name of the preference to check
69
 * @return True if the preference exists in the preferences, otherwise false
70
 */
71
boolean contains(String key);
72

73
/**
74
 * Create a new Editor for these preferences, through which you can make
75
 * modifications to the data in the preferences and atomically commit those changes
76
 * @return Returns an instance of the Editor interface
77
 */
78
SharedPreferences.Editor edit();
79
```
80

81
**Usage Examples:**
82

83
```java
84
// Replace SharedPreferences with MMKV
85
// OLD: SharedPreferences prefs = getSharedPreferences("app_prefs", MODE_PRIVATE);
86
MMKV prefs = MMKV.mmkvWithID("app_prefs");
87

88
// Use exactly like SharedPreferences
89
String username = prefs.getString("username", "guest");
90
int userId = prefs.getInt("user_id", -1);
91
boolean isLoggedIn = prefs.getBoolean("logged_in", false);
92

93
// Check for key existence
94
if (prefs.contains("user_settings")) {
95
    // Key exists
96
}
97
```
98

99
### SharedPreferences.Editor Interface
100

101
MMKV implements the SharedPreferences.Editor interface for familiar data modification patterns.
102

103
```java { .api }
104
/**
105
 * Set a string value in the preferences editor
106
 * @param key The name of the preference to modify
107
 * @param value The new value for the preference (can be null)
108
 * @return Returns a reference to the same Editor object
109
 */
110
SharedPreferences.Editor putString(String key, String value);
111

112
/**
113
 * Set a string value with expiration
114
 * @param key The name of the preference to modify
115
 * @param value The new value for the preference (can be null)
116
 * @param expireDurationInSecond Override the default duration, 0 means never expire
117
 * @return Returns a reference to the same Editor object
118
 */
119
SharedPreferences.Editor putString(String key, String value, int expireDurationInSecond);
120

121
/**
122
 * Set a string set value in the preferences editor
123
 * @param key The name of the preference to modify
124
 * @param values The new values for the preference (can be null)
125
 * @return Returns a reference to the same Editor object
126
 */
127
SharedPreferences.Editor putStringSet(String key, Set<String> values);
128

129
/**
130
 * Set a string set value with expiration
131
 * @param key The name of the preference to modify
132
 * @param values The new values for the preference (can be null)
133
 * @param expireDurationInSecond Override the default duration, 0 means never expire
134
 * @return Returns a reference to the same Editor object
135
 */
136
SharedPreferences.Editor putStringSet(String key, Set<String> values, int expireDurationInSecond);
137

138
/**
139
 * Set an integer value in the preferences editor
140
 * @param key The name of the preference to modify
141
 * @param value The new value for the preference
142
 * @return Returns a reference to the same Editor object
143
 */
144
SharedPreferences.Editor putInt(String key, int value);
145

146
/**
147
 * Set an integer value with expiration
148
 * @param key The name of the preference to modify
149
 * @param value The new value for the preference
150
 * @param expireDurationInSecond Override the default duration, 0 means never expire
151
 * @return Returns a reference to the same Editor object
152
 */
153
SharedPreferences.Editor putInt(String key, int value, int expireDurationInSecond);
154

155
/**
156
 * Set a long value in the preferences editor
157
 * @param key The name of the preference to modify
158
 * @param value The new value for the preference
159
 * @return Returns a reference to the same Editor object
160
 */
161
SharedPreferences.Editor putLong(String key, long value);
162

163
/**
164
 * Set a long value with expiration
165
 * @param key The name of the preference to modify
166
 * @param value The new value for the preference
167
 * @param expireDurationInSecond Override the default duration, 0 means never expire
168
 * @return Returns a reference to the same Editor object
169
 */
170
SharedPreferences.Editor putLong(String key, long value, int expireDurationInSecond);
171

172
/**
173
 * Set a float value in the preferences editor
174
 * @param key The name of the preference to modify
175
 * @param value The new value for the preference
176
 * @return Returns a reference to the same Editor object
177
 */
178
SharedPreferences.Editor putFloat(String key, float value);
179

180
/**
181
 * Set a float value with expiration
182
 * @param key The name of the preference to modify
183
 * @param value The new value for the preference
184
 * @param expireDurationInSecond Override the default duration, 0 means never expire
185
 * @return Returns a reference to the same Editor object
186
 */
187
SharedPreferences.Editor putFloat(String key, float value, int expireDurationInSecond);
188

189
/**
190
 * Set a boolean value in the preferences editor
191
 * @param key The name of the preference to modify
192
 * @param value The new value for the preference
193
 * @return Returns a reference to the same Editor object
194
 */
195
SharedPreferences.Editor putBoolean(String key, boolean value);
196

197
/**
198
 * Set a boolean value with expiration
199
 * @param key The name of the preference to modify
200
 * @param value The new value for the preference
201
 * @param expireDurationInSecond Override the default duration, 0 means never expire
202
 * @return Returns a reference to the same Editor object
203
 */
204
SharedPreferences.Editor putBoolean(String key, boolean value, int expireDurationInSecond);
205

206
/**
207
 * Mark in the editor that a preference value should be removed
208
 * @param key The name of the preference to remove
209
 * @return Returns a reference to the same Editor object
210
 */
211
SharedPreferences.Editor remove(String key);
212

213
/**
214
 * Mark in the editor to remove all values from the preferences
215
 * @return Returns a reference to the same Editor object
216
 */
217
SharedPreferences.Editor clear();
218

219
/**
220
 * Commit your preferences changes synchronously.
221
 * DEPRECATED: This method is only for compatibility. MMKV doesn't rely on commit().
222
 * @deprecated Use sync() or async() instead if you worry about data persistence
223
 * @return Always returns true
224
 */
225
@Deprecated
226
boolean commit();
227

228
/**
229
 * Commit your preferences changes asynchronously.
230
 * DEPRECATED: This method is only for compatibility. MMKV doesn't rely on apply().
231
 * @deprecated Use async() instead if you worry about data persistence
232
 */
233
@Deprecated
234
void apply();
235
```
236

237
**Usage Examples:**
238

239
```java
240
// Use editor pattern like SharedPreferences
241
MMKV prefs = MMKV.mmkvWithID("app_prefs");
242

243
// Chain editor operations
244
prefs.edit()
245
    .putString("username", "john_doe")
246
    .putInt("user_id", 12345)
247
    .putBoolean("logged_in", true)
248
    .commit(); // Optional - MMKV persists immediately
249

250
// Or use without explicit commit (recommended)
251
prefs.putString("username", "john_doe");
252
prefs.putInt("user_id", 12345);
253
prefs.putBoolean("logged_in", true);
254

255
// MMKV extensions with expiration
256
prefs.edit()
257
    .putString("session_token", "abc123", MMKV.ExpireInHour)
258
    .putInt("daily_score", 1500, MMKV.ExpireInDay);
259
```
260

261
### MMKV Extensions to SharedPreferences
262

263
MMKV provides additional methods beyond the standard SharedPreferences interface.
264

265
```java { .api }
266
/**
267
 * Set a byte array value (MMKV extension)
268
 * @param key The name of the preference to modify
269
 * @param bytes The new byte array value (can be null)
270
 * @return Returns a reference to the same Editor object
271
 */
272
SharedPreferences.Editor putBytes(String key, byte[] bytes);
273

274
/**
275
 * Set a byte array value with expiration (MMKV extension)
276
 * @param key The name of the preference to modify
277
 * @param bytes The new byte array value (can be null)
278
 * @param expireDurationInSecond Override the default duration, 0 means never expire
279
 * @return Returns a reference to the same Editor object
280
 */
281
SharedPreferences.Editor putBytes(String key, byte[] bytes, int expireDurationInSecond);
282

283
/**
284
 * Get a byte array value (MMKV extension)
285
 * @param key The name of the preference to retrieve
286
 * @param defValue Value to return if this preference does not exist
287
 * @return The preference value if it exists, or defValue
288
 */
289
byte[] getBytes(String key, byte[] defValue);
290
```
291

292
**Usage Examples:**
293

294
```java
295
// Use MMKV extensions
296
byte[] imageData = loadImageAsBytes();
297
prefs.putBytes("profile_image", imageData);
298

299
// Retrieve binary data
300
byte[] storedImage = prefs.getBytes("profile_image", null);
301
```
302

303
### Migration from SharedPreferences
304

305
MMKV provides a convenient method for migrating existing SharedPreferences data.
306

307
```java { .api }
308
/**
309
 * Atomically migrate all key-values from an existent SharedPreferences to the MMKV instance.
310
 * @param preferences The SharedPreferences to import from
311
 * @return The total count of key-values imported
312
 */
313
int importFromSharedPreferences(SharedPreferences preferences);
314
```
315

316
**Usage Examples:**
317

318
```java
319
// Migrate from existing SharedPreferences
320
SharedPreferences oldPrefs = getSharedPreferences("old_prefs", MODE_PRIVATE);
321
MMKV newPrefs = MMKV.mmkvWithID("new_prefs");
322

323
// Import all data
324
int importedCount = newPrefs.importFromSharedPreferences(oldPrefs);
325
Log.d("Migration", "Imported " + importedCount + " preferences");
326

327
// Clear old preferences after successful migration
328
if (importedCount > 0) {
329
    oldPrefs.edit().clear().commit();
330
}
331
```
332

333
### Unsupported SharedPreferences Methods
334

335
MMKV intentionally does not support certain SharedPreferences methods that conflict with its design philosophy.
336

337
```java { .api }
338
/**
339
 * Intentionally not supported by MMKV. We believe it's better not for a storage framework 
340
 * to notify the change of data. Check registerContentChangeNotify for a potential replacement 
341
 * on inter-process scene.
342
 * @throws UnsupportedOperationException Always thrown
343
 */
344
void registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
345

346
/**
347
 * Intentionally not supported by MMKV. We believe it's better not for a storage framework 
348
 * to notify the change of data.
349
 * @throws UnsupportedOperationException Always thrown
350
 */
351
void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
352
```
353

354
**Migration Notes:**
355

356
```java
357
// OLD SharedPreferences code with listeners:
358
sharedPrefs.registerOnSharedPreferenceChangeListener(listener);
359

360
// MMKV alternative for inter-process notifications:
361
MMKV.registerContentChangeNotify(new MMKVContentChangeNotification() {
362
    @Override
363
    public void onContentChangedByOuterProcess(String mmapID) {
364
        // Handle inter-process content changes
365
    }
366
});
367
```
368

369
## Performance Comparison
370

371
| Operation | SharedPreferences | MMKV | Improvement |
372
|-----------|------------------|------|-------------|
373
| Read | ~100µs | ~1µs | ~100x faster |
374
| Write | ~10ms | ~1µs | ~10,000x faster |
375
| Startup | ~50ms | ~1ms | ~50x faster |
376
377
**Migration Checklist:**
378

379
1. Replace `getSharedPreferences()` calls with `MMKV.mmkvWithID()`
380
2. Remove `.commit()` and `.apply()` calls (optional in MMKV)
381
3. Replace preference change listeners with MMKV content change notifications
382
4. Use `importFromSharedPreferences()` for data migration
383
5. Test with multi-process scenarios if applicable