0
# MMKV
1
2
MMKV is a high-performance, cross-platform mobile key-value storage framework that provides efficient memory-mapped file-based persistence with protobuf encoding. It offers multi-process concurrency support, encryption capabilities, and serves as a drop-in replacement for Android SharedPreferences with significantly better performance characteristics.
3
4
## Package Information
5
6
- **Package Name**: com.tencent:mmkv
7
- **Package Type**: maven
8
- **Language**: Java (with native C++ components)
9
- **Installation**: Add to build.gradle: `implementation 'com.tencent:mmkv:2.2.2'`
10
11
## Core Imports
12
13
```java
14
import com.tencent.mmkv.MMKV;
15
import com.tencent.mmkv.MMKVLogLevel;
16
import com.tencent.mmkv.MMKVHandler;
17
import com.tencent.mmkv.NameSpace;
18
```
19
20
## Basic Usage
21
22
```java
23
import com.tencent.mmkv.MMKV;
24
25
public class MainActivity extends AppCompatActivity {
26
@Override
27
protected void onCreate(Bundle savedInstanceState) {
28
super.onCreate(savedInstanceState);
29
30
// Initialize MMKV (call once during app startup)
31
String rootDir = MMKV.initialize(this);
32
33
// Get default MMKV instance
34
MMKV kv = MMKV.defaultMMKV();
35
36
// Store values
37
kv.encode("user_id", 12345);
38
kv.encode("username", "john_doe");
39
kv.encode("is_premium", true);
40
kv.encode("score", 99.5f);
41
42
// Retrieve values
43
int userId = kv.decodeInt("user_id");
44
String username = kv.decodeString("username");
45
boolean isPremium = kv.decodeBool("is_premium");
46
float score = kv.decodeFloat("score");
47
}
48
}
49
```
50
51
## Architecture
52
53
MMKV is built around several key components:
54
55
- **Memory Mapping**: Uses mmap to keep memory synced with files for immediate persistence
56
- **Protobuf Encoding**: Efficient binary serialization for all data types
57
- **Multi-Process Support**: Safe concurrent access across different processes with file locking
58
- **Encryption Layer**: Optional AES encryption with custom keys up to 16 bytes
59
- **SharedPreferences Compatibility**: Drop-in replacement API for easy migration
60
- **Native Performance**: C++ core with JNI bridge for optimal performance
61
- **Namespace Support**: Custom root directories for data isolation
62
63
## Capabilities
64
65
### Initialization and Configuration
66
67
Core initialization methods for setting up MMKV with various configuration options including custom directories, log levels, library loaders, and error handlers.
68
69
```java { .api }
70
public static String initialize(Context context);
71
public static String initialize(Context context, MMKVLogLevel logLevel);
72
public static String initialize(Context context, String rootDir);
73
public static String initialize(Context context, String rootDir, MMKVLogLevel logLevel);
74
```
75
76
[Initialization and Configuration](./initialization.md)
77
78
### Instance Management
79
80
Methods for creating and managing MMKV instances with different configurations including single/multi-process modes, encryption, custom directories, and ashmem-based instances.
81
82
```java { .api }
83
public static MMKV mmkvWithID(String mmapID);
84
public static MMKV mmkvWithID(String mmapID, int mode);
85
public static MMKV mmkvWithID(String mmapID, int mode, String cryptKey);
86
public static MMKV defaultMMKV();
87
```
88
89
[Instance Management](./instance-management.md)
90
91
### Data Storage and Retrieval
92
93
Comprehensive data storage API supporting primitives, strings, byte arrays, string sets, and Parcelable objects with optional expiration times.
94
95
```java { .api }
96
public boolean encode(String key, boolean value);
97
public boolean encode(String key, int value);
98
public boolean encode(String key, String value);
99
public boolean decodeBool(String key, boolean defaultValue);
100
public int decodeInt(String key, int defaultValue);
101
public String decodeString(String key, String defaultValue);
102
```
103
104
[Data Storage and Retrieval](./data-storage.md)
105
106
### Encryption and Security
107
108
Built-in encryption capabilities with key management, supporting AES encryption for secure data storage and key transformation operations.
109
110
```java { .api }
111
public String cryptKey();
112
public boolean reKey(String cryptKey);
113
public void checkReSetCryptKey(String cryptKey);
114
```
115
116
[Encryption and Security](./encryption.md)
117
118
### Multi-Process Operations
119
120
Safe multi-process access with file locking, content change notifications, and process-aware instance management for applications with multiple processes.
121
122
```java { .api }
123
public void lock();
124
public void unlock();
125
public boolean tryLock();
126
public void checkContentChangedByOuterProcess();
127
public boolean isMultiProcess();
128
```
129
130
[Multi-Process Operations](./multi-process.md)
131
132
### Data Management
133
134
Advanced data management operations including key inspection, file operations, backup/restore capabilities, and performance optimization methods.
135
136
```java { .api }
137
public boolean containsKey(String key);
138
public String[] allKeys();
139
public long count();
140
public void removeValueForKey(String key);
141
public void clearAll();
142
public long totalSize();
143
public long actualSize();
144
```
145
146
[Data Management](./data-management.md)
147
148
### Namespace Support
149
150
Namespace functionality for organizing MMKV instances with custom root directories, providing data isolation and organizational capabilities.
151
152
```java { .api }
153
public static NameSpace nameSpace(String dir);
154
public static NameSpace defaultNameSpace();
155
```
156
157
[Namespace Support](./namespace.md)
158
159
## Types
160
161
```java { .api }
162
public enum MMKVLogLevel {
163
LevelDebug,
164
LevelInfo,
165
LevelWarning,
166
LevelError,
167
LevelNone
168
}
169
170
public enum MMKVRecoverStrategic {
171
OnErrorDiscard,
172
OnErrorRecover
173
}
174
175
public interface MMKVHandler {
176
MMKVRecoverStrategic onMMKVCRCCheckFail(String mmapID);
177
MMKVRecoverStrategic onMMKVFileLengthError(String mmapID);
178
boolean wantLogRedirecting();
179
void mmkvLog(MMKVLogLevel level, String file, int line, String function, String message);
180
}
181
182
public interface MMKVContentChangeNotification {
183
void onContentChangedByOuterProcess(String mmapID);
184
}
185
186
public final class ParcelableMMKV implements Parcelable {
187
public ParcelableMMKV(MMKV mmkv);
188
public MMKV toMMKV();
189
public int describeContents();
190
public void writeToParcel(Parcel dest, int flags);
191
public static final Parcelable.Creator<ParcelableMMKV> CREATOR;
192
}
193
194
public class UnsupportedArchitectureException extends RuntimeException {
195
public UnsupportedArchitectureException(String message);
196
}
197
198
public final class NativeBuffer {
199
public long pointer;
200
public int size;
201
public NativeBuffer(long ptr, int length);
202
}
203
204
public class MMKVContentProvider extends ContentProvider {
205
protected static final String KEY = "KEY";
206
protected static final String KEY_SIZE = "KEY_SIZE";
207
protected static final String KEY_MODE = "KEY_MODE";
208
protected static final String KEY_CRYPT = "KEY_CRYPT";
209
protected static final String FUNCTION_NAME = "mmkvFromAshmemID";
210
211
protected static Uri contentUri(Context context);
212
protected static String getProcessNameByPID(Context context, int pid);
213
public boolean onCreate();
214
public Bundle call(String method, String mmapID, Bundle extras);
215
public String getType(Uri uri);
216
}
217
```
218
219
## Constants
220
221
```java { .api }
222
// Process modes
223
public static final int SINGLE_PROCESS_MODE = 1 << 0;
224
public static final int MULTI_PROCESS_MODE = 1 << 1;
225
public static final int READ_ONLY_MODE = 1 << 5;
226
227
// Expiration constants
228
public static final int ExpireNever = 0;
229
public static final int ExpireInMinute = 60;
230
public static final int ExpireInHour = 3600;
231
public static final int ExpireInDay = 86400;
232
public static final int ExpireInMonth = 2592000;
233
public static final int ExpireInYear = 946080000;
234
```