0
# Core Store Operations
1

2
The KVStore interface provides the fundamental operations for persisting, retrieving, and managing data in the key-value store. All operations are thread-safe and support automatic serialization and indexing.
3

4
## Capabilities
5

6
### KVStore Interface
7

8
Main abstraction for local key/value store operations with automatic serialization and indexing support.
9

10
```java { .api }
11
/**
12
 * Abstraction for a local key/value store for storing app data.
13
 * Thread-safe for both reads and writes.
14
 */
15
public interface KVStore extends Closeable {
16
    
17
    /**
18
     * Returns app-specific metadata from the store, or null if not set.
19
     * @param klass The class type of the metadata to retrieve
20
     * @return The metadata object or null if not found
21
     * @throws Exception if retrieval fails
22
     */
23
    <T> T getMetadata(Class<T> klass) throws Exception;
24
    
25
    /**
26
     * Writes the given value in the store metadata key.
27
     * @param value The metadata object to store
28
     * @throws Exception if write fails
29
     */
30
    void setMetadata(Object value) throws Exception;
31
    
32
    /**
33
     * Read a specific instance of an object by its natural key.
34
     * @param klass The class type to read
35
     * @param naturalKey The object's natural key (must not be null)
36
     * @return The retrieved object
37
     * @throws java.util.NoSuchElementException if key does not exist
38
     * @throws Exception if read fails
39
     */
40
    <T> T read(Class<T> klass, Object naturalKey) throws Exception;
41
    
42
    /**
43
     * Writes the given object to the store, including indexed fields.
44
     * @param value The object to write (must not be null)
45
     * @throws Exception if write fails
46
     */
47
    void write(Object value) throws Exception;
48
    
49
    /**
50
     * Removes an object and all related data from the store.
51
     * @param type The object's type
52
     * @param naturalKey The object's natural key (must not be null)
53
     * @throws java.util.NoSuchElementException if key does not exist
54
     * @throws Exception if deletion fails
55
     */
56
    void delete(Class<?> type, Object naturalKey) throws Exception;
57
    
58
    /**
59
     * Returns a configurable view for iterating over entities.
60
     * @param type The class type to iterate over
61
     * @return A configurable view instance
62
     * @throws Exception if view creation fails
63
     */
64
    <T> KVStoreView<T> view(Class<T> type) throws Exception;
65
    
66
    /**
67
     * Returns the number of items of the given type in the store.
68
     * @param type The class type to count
69
     * @return The count of items
70
     * @throws Exception if count fails
71
     */
72
    long count(Class<?> type) throws Exception;
73
    
74
    /**
75
     * Returns the number of items matching the given indexed value.
76
     * @param type The class type to count
77
     * @param index The index name to query
78
     * @param indexedValue The value to match in the index
79
     * @return The count of matching items
80
     * @throws Exception if count fails
81
     */
82
    long count(Class<?> type, String index, Object indexedValue) throws Exception;
83
    
84
    /**
85
     * Efficiently remove multiple items by index values.
86
     * @param klass The class type of items to remove
87
     * @param index The index name to use for matching
88
     * @param indexValues Collection of index values to remove
89
     * @return true if any items were removed
90
     * @throws Exception if removal fails
91
     */
92
    <T> boolean removeAllByIndexValues(Class<T> klass, String index, Collection<?> indexValues) throws Exception;
93
    
94
    /**
95
     * Close the store and release resources.
96
     * @throws Exception if close fails
97
     */
98
    void close() throws Exception;
99
}
100
```
101

102
**Usage Examples:**
103

104
```java
105
import org.apache.spark.util.kvstore.*;
106
import java.io.File;
107

108
// Create store instance
109
KVStore store = new LevelDB(new File("/path/to/store"));
110

111
// Basic CRUD operations
112
public class Task {
113
    @KVIndex
114
    public String id;
115
    
116
    @KVIndex("status")
117
    public String status;
118
    
119
    public Task(String id, String status) {
120
        this.id = id;
121
        this.status = status;
122
    }
123
}
124

125
// Write data
126
Task task = new Task("task-1", "running");
127
store.write(task);
128

129
// Read data
130
Task retrieved = store.read(Task.class, "task-1");
131

132
// Count items
133
long totalTasks = store.count(Task.class);
134
long runningTasks = store.count(Task.class, "status", "running");
135

136
// Batch operations
137
Collection<String> completedIds = Arrays.asList("task-2", "task-3");
138
store.removeAllByIndexValues(Task.class, "id", completedIds);
139

140
// Metadata operations
141
AppConfig config = new AppConfig("v1.0", true);
142
store.setMetadata(config);
143
AppConfig retrievedConfig = store.getMetadata(AppConfig.class);
144

145
// Always close when done
146
store.close();
147
```
148

149
### Serialization and Compression
150

151
The KVStore automatically handles serialization using Jackson with GZIP compression for non-string data.
152

153
```java { .api }
154
/**
155
 * Serializer for translating between app-defined types and disk storage.
156
 * Based on Jackson ObjectMapper with automatic GZIP compression for non-strings.
157
 */
158
public class KVStoreSerializer {
159
    protected final ObjectMapper mapper;
160
    
161
    public KVStoreSerializer();
162
    
163
    /**
164
     * Serialize object to bytes. Uses UTF-8 encoding for strings, 
165
     * GZIP compression with Jackson JSON for other objects.
166
     * @param o The object to serialize
167
     * @return Serialized byte array
168
     * @throws Exception if serialization fails
169
     */
170
    public byte[] serialize(Object o) throws Exception;
171
    
172
    /**
173
     * Deserialize bytes to object. Handles UTF-8 strings and 
174
     * GZIP-compressed JSON for other objects.
175
     * @param data The byte array to deserialize
176
     * @param klass The target class type
177
     * @return The deserialized object
178
     * @throws Exception if deserialization fails
179
     */
180
    public <T> T deserialize(byte[] data, Class<T> klass) throws Exception;
181
    
182
    /**
183
     * Serialize long value to UTF-8 string bytes.
184
     * @param value The long value to serialize
185
     * @return Serialized byte array
186
     */
187
    final byte[] serialize(long value);
188
    
189
    /**
190
     * Deserialize UTF-8 string bytes to long value.
191
     * @param data The byte array to deserialize
192
     * @return The long value
193
     */
194
    final long deserializeLong(byte[] data);
195
}
196
```
197

198
### Exception Handling
199

200
```java { .api }
201
/**
202
 * Exception thrown when store version is incompatible.
203
 */
204
public class UnsupportedStoreVersionException extends IOException {
205
    // Standard IOException constructors
206
}
207
```
208

209
**Error Handling Examples:**
210

211
```java
212
try {
213
    Task task = store.read(Task.class, "nonexistent");
214
} catch (NoSuchElementException e) {
215
    System.out.println("Task not found: " + e.getMessage());
216
}
217

218
try {
219
    KVStore store = new LevelDB(new File("/invalid/path"));
220
} catch (UnsupportedStoreVersionException e) {
221
    System.out.println("Store version incompatible: " + e.getMessage());
222
}
223
```