0
# Core Store Operations
1

2
Basic CRUD operations for storing and retrieving objects with automatic key management and serialization. These operations form the foundation of the KVStore API and handle all data persistence operations.
3

4
## Capabilities
5

6
### Reading Objects
7

8
Retrieves a specific object instance by its natural key from the store.
9

10
```java { .api }
11
/**
12
 * Read a specific instance of an object.
13
 * @param klass - The object's class type
14
 * @param naturalKey - The object's "natural key", which uniquely identifies it. Null keys are not allowed.
15
 * @return The retrieved object instance
16
 * @throws java.util.NoSuchElementException If an element with the given key does not exist
17
 * @throws Exception If serialization or store access fails
18
 */
19
<T> T read(Class<T> klass, Object naturalKey) throws Exception;
20
```
21

22
**Usage Examples:**
23

24
```java
25
// Read a person by ID
26
Person person = store.read(Person.class, "person123");
27

28
// Read configuration by key
29
Config config = store.read(Config.class, "app.settings");
30
```
31

32
### Writing Objects
33

34
Writes objects to the store with automatic indexing and serialization. Creates or updates entries based on the natural key.
35

36
```java { .api }
37
/**
38
 * Writes the given object to the store, including indexed fields. Indices are updated based
39
 * on the annotated fields of the object's class.
40
 * 
41
 * Writes may be slower when the object already exists in the store, since it will involve
42
 * updating existing indices.
43
 * 
44
 * @param value - The object to write. Cannot be null.
45
 * @throws Exception If serialization or store access fails
46
 */
47
void write(Object value) throws Exception;
48
```
49

50
**Usage Examples:**
51

52
```java
53
// Write a new person
54
Person newPerson = new Person("p123", "John Doe", 25);
55
store.write(newPerson);
56

57
// Update existing person (same natural key)
58
Person updated = new Person("p123", "John Smith", 26);
59
store.write(updated); // Overwrites previous entry
60
```
61

62
### Deleting Objects
63

64
Removes objects and all associated data including index entries from the store.
65

66
```java { .api }
67
/**
68
 * Removes an object and all data related to it, like index entries, from the store.
69
 * @param type - The object's type
70
 * @param naturalKey - The object's "natural key", which uniquely identifies it. Null keys are not allowed.
71
 * @throws java.util.NoSuchElementException If an element with the given key does not exist
72
 * @throws Exception If store access fails
73
 */
74
void delete(Class<?> type, Object naturalKey) throws Exception;
75
```
76

77
**Usage Examples:**
78

79
```java
80
// Delete a person by ID
81
store.delete(Person.class, "person123");
82

83
// Delete configuration entry
84
store.delete(Config.class, "app.settings");
85
```
86

87
### Counting Objects
88

89
Returns the total number of objects of a given type or matching specific index values.
90

91
```java { .api }
92
/**
93
 * Returns the number of items of the given type currently in the store.
94
 * @param type - The object type to count
95
 * @return Total count of objects of the specified type
96
 * @throws Exception If store access fails
97
 */
98
long count(Class<?> type) throws Exception;
99

100
/**
101
 * Returns the number of items of the given type which match the given indexed value.
102
 * @param type - The object type to count
103
 * @param index - The index name to filter by
104
 * @param indexedValue - The value to match in the index
105
 * @return Count of objects matching the indexed value
106
 * @throws Exception If store access fails
107
 */
108
long count(Class<?> type, String index, Object indexedValue) throws Exception;
109
```
110

111
**Usage Examples:**
112

113
```java
114
// Count all persons in the store
115
long totalPersons = store.count(Person.class);
116

117
// Count persons with specific age
118
long adultsCount = store.count(Person.class, "age", 30);
119

120
// Count persons with specific status
121
long activeUsers = store.count(Person.class, "status", "active");
122
```
123

124
### Bulk Removal Operations
125

126
Efficiently removes multiple items from the store based on index values.
127

128
```java { .api }
129
/**
130
 * A cheaper way to remove multiple items from the KVStore
131
 * @param klass - The object type to remove from
132
 * @param index - The index name to filter by
133
 * @param indexValues - Collection of index values to match for removal
134
 * @return true if any items were removed, false otherwise
135
 * @throws Exception If store access fails
136
 */
137
<T> boolean removeAllByIndexValues(Class<T> klass, String index, Collection<?> indexValues) throws Exception;
138
```
139

140
**Usage Examples:**
141

142
```java
143
// Remove all persons with specific IDs
144
List<String> idsToRemove = Arrays.asList("p1", "p2", "p3");
145
boolean removed = store.removeAllByIndexValues(Person.class, KVIndex.NATURAL_INDEX_NAME, idsToRemove);
146

147
// Remove all persons with specific ages
148
List<Integer> agesToRemove = Arrays.asList(25, 30, 35);
149
store.removeAllByIndexValues(Person.class, "age", agesToRemove);
150
```
151

152
### Metadata Operations
153

154
Store and retrieve application-specific metadata that persists across store sessions.
155

156
```java { .api }
157
/**
158
 * Returns app-specific metadata from the store, or null if it's not currently set.
159
 * The metadata type is application-specific. This is a convenience method so that applications
160
 * don't need to define their own keys for this information.
161
 * @param klass - The metadata class type
162
 * @return The metadata object or null if not set
163
 * @throws Exception If deserialization or store access fails
164
 */
165
<T> T getMetadata(Class<T> klass) throws Exception;
166

167
/**
168
 * Writes the given value in the store metadata key.
169
 * @param value - The metadata object to store, or null to remove
170
 * @throws Exception If serialization or store access fails
171
 */
172
void setMetadata(Object value) throws Exception;
173
```
174

175
**Usage Examples:**
176

177
```java
178
// Store application configuration as metadata
179
AppConfig config = new AppConfig("1.0", "production");
180
store.setMetadata(config);
181

182
// Retrieve application configuration
183
AppConfig retrievedConfig = store.getMetadata(AppConfig.class);
184
if (retrievedConfig != null) {
185
    System.out.println("Version: " + retrievedConfig.version);
186
}
187

188
// Remove metadata
189
store.setMetadata(null);
190
```
191

192
### Resource Management
193

194
Properly close the store to release resources and ensure data persistence.
195

196
```java { .api }
197
/**
198
 * Closes the store and releases all associated resources.
199
 * For persistent stores like LevelDB, ensures all data is written to disk.
200
 * @throws IOException If there are issues closing the underlying storage
201
 */
202
void close() throws IOException;
203
```
204

205
**Usage Examples:**
206

207
```java
208
KVStore store = new LevelDB(new File("./mystore"));
209
try {
210
    // Use the store
211
    store.write(someObject);
212
    // ... other operations
213
} finally {
214
    // Always close the store
215
    store.close();
216
}
217

218
// Or use try-with-resources
219
try (KVStore store = new InMemoryStore()) {
220
    store.write(someObject);
221
    // Store automatically closed
222
}
223
```