1 package org.ldk.structs;
3 import org.ldk.impl.bindings;
4 import org.ldk.enums.*;
6 import java.util.Arrays;
7 import java.lang.ref.Reference;
8 import javax.annotation.Nullable;
11 * Provides an interface that allows storage and retrieval of persisted values that are associated
14 * In order to avoid collisions the key space is segmented based on the given `primary_namespace`s
15 * and `secondary_namespace`s. Implementations of this trait are free to handle them in different
16 * ways, as long as per-namespace key uniqueness is asserted.
18 * Keys and namespaces are required to be valid ASCII strings in the range of
19 * [`KVSTORE_NAMESPACE_KEY_ALPHABET`] and no longer than [`KVSTORE_NAMESPACE_KEY_MAX_LEN`]. Empty
20 * primary namespaces and secondary namespaces (`\"\"`) are assumed to be a valid, however, if
21 * `primary_namespace` is empty, `secondary_namespace` is required to be empty, too. This means
22 * that concerns should always be separated by primary namespace first, before secondary
23 * namespaces are used. While the number of primary namespaces will be relatively small and is
24 * determined at compile time, there may be many secondary namespaces per primary namespace. Note
25 * that per-namespace uniqueness needs to also hold for keys *and* namespaces in any given
26 * namespace, i.e., conflicts between keys and equally named
27 * primary namespaces/secondary namespaces must be avoided.
29 * Note:** Users migrating custom persistence backends from the pre-v0.0.117 `KVStorePersister`
30 * interface can use a concatenation of `[{primary_namespace}/[{secondary_namespace}/]]{key}` to
31 * recover a `key` compatible with the data model previously assumed by `KVStorePersister::persist`.
33 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
34 public class KVStore extends CommonBase {
35 final bindings.LDKKVStore bindings_instance;
36 KVStore(Object _dummy, long ptr) { super(ptr); bindings_instance = null; }
37 private KVStore(bindings.LDKKVStore arg) {
38 super(bindings.LDKKVStore_new(arg));
39 this.ptrs_to.add(arg);
40 this.bindings_instance = arg;
42 @Override @SuppressWarnings("deprecation")
43 protected void finalize() throws Throwable {
44 if (ptr != 0) { bindings.KVStore_free(ptr); } super.finalize();
47 * Destroys the object, freeing associated resources. After this call, any access
48 * to this object may result in a SEGFAULT or worse.
50 * You should generally NEVER call this method. You should let the garbage collector
51 * do this for you when it finalizes objects. However, it may be useful for types
52 * which represent locks and should be closed immediately to avoid holding locks
55 public void destroy() {
56 if (ptr != 0) { bindings.KVStore_free(ptr); }
59 public static interface KVStoreInterface {
61 * Returns the data stored for the given `primary_namespace`, `secondary_namespace`, and
64 * Returns an [`ErrorKind::NotFound`] if the given `key` could not be found in the given
65 * `primary_namespace` and `secondary_namespace`.
67 * [`ErrorKind::NotFound`]: io::ErrorKind::NotFound
69 Result_CVec_u8ZIOErrorZ read(String primary_namespace, String secondary_namespace, String key);
71 * Persists the given data under the given `key`.
73 * Will create the given `primary_namespace` and `secondary_namespace` if not already present
76 Result_NoneIOErrorZ write(String primary_namespace, String secondary_namespace, String key, byte[] buf);
78 * Removes any data that had previously been persisted under the given `key`.
80 * If the `lazy` flag is set to `true`, the backend implementation might choose to lazily
81 * remove the given `key` at some point in time after the method returns, e.g., as part of an
82 * eventual batch deletion of multiple keys. As a consequence, subsequent calls to
83 * [`KVStore::list`] might include the removed key until the changes are actually persisted.
85 * Note that while setting the `lazy` flag reduces the I/O burden of multiple subsequent
86 * `remove` calls, it also influences the atomicity guarantees as lazy `remove`s could
87 * potentially get lost on crash after the method returns. Therefore, this flag should only be
88 * set for `remove` operations that can be safely replayed at a later time.
90 * Returns successfully if no data will be stored for the given `primary_namespace`,
91 * `secondary_namespace`, and `key`, independently of whether it was present before its
94 Result_NoneIOErrorZ remove(String primary_namespace, String secondary_namespace, String key, boolean lazy);
96 * Returns a list of keys that are stored under the given `secondary_namespace` in
97 * `primary_namespace`.
99 * Returns the keys in arbitrary order, so users requiring a particular order need to sort the
100 * returned keys. Returns an empty list if `primary_namespace` or `secondary_namespace` is unknown.
102 Result_CVec_StrZIOErrorZ list(String primary_namespace, String secondary_namespace);
104 private static class LDKKVStoreHolder { KVStore held; }
105 public static KVStore new_impl(KVStoreInterface arg) {
106 final LDKKVStoreHolder impl_holder = new LDKKVStoreHolder();
107 impl_holder.held = new KVStore(new bindings.LDKKVStore() {
108 @Override public long read(String primary_namespace, String secondary_namespace, String key) {
109 Result_CVec_u8ZIOErrorZ ret = arg.read(primary_namespace, secondary_namespace, key);
110 Reference.reachabilityFence(arg);
111 long result = ret.clone_ptr();
114 @Override public long write(String primary_namespace, String secondary_namespace, String key, byte[] buf) {
115 Result_NoneIOErrorZ ret = arg.write(primary_namespace, secondary_namespace, key, buf);
116 Reference.reachabilityFence(arg);
117 long result = ret.clone_ptr();
120 @Override public long remove(String primary_namespace, String secondary_namespace, String key, boolean lazy) {
121 Result_NoneIOErrorZ ret = arg.remove(primary_namespace, secondary_namespace, key, lazy);
122 Reference.reachabilityFence(arg);
123 long result = ret.clone_ptr();
126 @Override public long list(String primary_namespace, String secondary_namespace) {
127 Result_CVec_StrZIOErrorZ ret = arg.list(primary_namespace, secondary_namespace);
128 Reference.reachabilityFence(arg);
129 long result = ret.clone_ptr();
133 return impl_holder.held;
136 * Returns the data stored for the given `primary_namespace`, `secondary_namespace`, and
139 * Returns an [`ErrorKind::NotFound`] if the given `key` could not be found in the given
140 * `primary_namespace` and `secondary_namespace`.
142 * [`ErrorKind::NotFound`]: io::ErrorKind::NotFound
144 public Result_CVec_u8ZIOErrorZ read(java.lang.String primary_namespace, java.lang.String secondary_namespace, java.lang.String key) {
145 long ret = bindings.KVStore_read(this.ptr, primary_namespace, secondary_namespace, key);
146 Reference.reachabilityFence(this);
147 Reference.reachabilityFence(primary_namespace);
148 Reference.reachabilityFence(secondary_namespace);
149 Reference.reachabilityFence(key);
150 if (ret >= 0 && ret <= 4096) { return null; }
151 Result_CVec_u8ZIOErrorZ ret_hu_conv = Result_CVec_u8ZIOErrorZ.constr_from_ptr(ret);
156 * Persists the given data under the given `key`.
158 * Will create the given `primary_namespace` and `secondary_namespace` if not already present
161 public Result_NoneIOErrorZ write(java.lang.String primary_namespace, java.lang.String secondary_namespace, java.lang.String key, byte[] buf) {
162 long ret = bindings.KVStore_write(this.ptr, primary_namespace, secondary_namespace, key, buf);
163 Reference.reachabilityFence(this);
164 Reference.reachabilityFence(primary_namespace);
165 Reference.reachabilityFence(secondary_namespace);
166 Reference.reachabilityFence(key);
167 Reference.reachabilityFence(buf);
168 if (ret >= 0 && ret <= 4096) { return null; }
169 Result_NoneIOErrorZ ret_hu_conv = Result_NoneIOErrorZ.constr_from_ptr(ret);
174 * Removes any data that had previously been persisted under the given `key`.
176 * If the `lazy` flag is set to `true`, the backend implementation might choose to lazily
177 * remove the given `key` at some point in time after the method returns, e.g., as part of an
178 * eventual batch deletion of multiple keys. As a consequence, subsequent calls to
179 * [`KVStore::list`] might include the removed key until the changes are actually persisted.
181 * Note that while setting the `lazy` flag reduces the I/O burden of multiple subsequent
182 * `remove` calls, it also influences the atomicity guarantees as lazy `remove`s could
183 * potentially get lost on crash after the method returns. Therefore, this flag should only be
184 * set for `remove` operations that can be safely replayed at a later time.
186 * Returns successfully if no data will be stored for the given `primary_namespace`,
187 * `secondary_namespace`, and `key`, independently of whether it was present before its
190 public Result_NoneIOErrorZ remove(java.lang.String primary_namespace, java.lang.String secondary_namespace, java.lang.String key, boolean lazy) {
191 long ret = bindings.KVStore_remove(this.ptr, primary_namespace, secondary_namespace, key, lazy);
192 Reference.reachabilityFence(this);
193 Reference.reachabilityFence(primary_namespace);
194 Reference.reachabilityFence(secondary_namespace);
195 Reference.reachabilityFence(key);
196 Reference.reachabilityFence(lazy);
197 if (ret >= 0 && ret <= 4096) { return null; }
198 Result_NoneIOErrorZ ret_hu_conv = Result_NoneIOErrorZ.constr_from_ptr(ret);
203 * Returns a list of keys that are stored under the given `secondary_namespace` in
204 * `primary_namespace`.
206 * Returns the keys in arbitrary order, so users requiring a particular order need to sort the
207 * returned keys. Returns an empty list if `primary_namespace` or `secondary_namespace` is unknown.
209 public Result_CVec_StrZIOErrorZ list(java.lang.String primary_namespace, java.lang.String secondary_namespace) {
210 long ret = bindings.KVStore_list(this.ptr, primary_namespace, secondary_namespace);
211 Reference.reachabilityFence(this);
212 Reference.reachabilityFence(primary_namespace);
213 Reference.reachabilityFence(secondary_namespace);
214 if (ret >= 0 && ret <= 4096) { return null; }
215 Result_CVec_StrZIOErrorZ ret_hu_conv = Result_CVec_StrZIOErrorZ.constr_from_ptr(ret);