_ Git - ldk-java/blob - src/main/java/org/ldk/structs/KVStore.java

   1 package org.ldk.structs;
   2
   3 import org.ldk.impl.bindings;
   4 import org.ldk.enums.*;
   5 import org.ldk.util.*;
   6 import java.util.Arrays;
   7 import java.lang.ref.Reference;
   8 import javax.annotation.Nullable;
   9
  10 /**
  11  * Provides an interface that allows storage and retrieval of persisted values that are associated
  12  * with given keys.
  13  *
  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.
  17  *
  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.
  28  *
  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`.
  32  */
  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;
  41         }
  42         @Override @SuppressWarnings("deprecation")
  43         protected void finalize() throws Throwable {
  44                 if (ptr != 0) { bindings.KVStore_free(ptr); } super.finalize();
  45         }
  46         /**
  47          * Destroys the object, freeing associated resources. After this call, any access
  48          * to this object may result in a SEGFAULT or worse.
  49          *
  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
  53          * until the GC runs.
  54          */
  55         public void destroy() {
  56                 if (ptr != 0) { bindings.KVStore_free(ptr); }
  57                 ptr = 0;
  58         }
  59         public static interface KVStoreInterface {
  60                 /**
  61                  * Returns the data stored for the given `primary_namespace`, `secondary_namespace`, and
  62                  * `key`.
  63                  *
  64                  * Returns an [`ErrorKind::NotFound`] if the given `key` could not be found in the given
  65                  * `primary_namespace` and `secondary_namespace`.
  66                  *
  67                  * [`ErrorKind::NotFound`]: io::ErrorKind::NotFound
  68                  */
  69                 Result_CVec_u8ZIOErrorZ read(String primary_namespace, String secondary_namespace, String key);
  70                 /**
  71                  * Persists the given data under the given `key`.
  72                  *
  73                  * Will create the given `primary_namespace` and `secondary_namespace` if not already present
  74                  * in the store.
  75                  */
  76                 Result_NoneIOErrorZ write(String primary_namespace, String secondary_namespace, String key, byte[] buf);
  77                 /**
  78                  * Removes any data that had previously been persisted under the given `key`.
  79                  *
  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.
  84                  *
  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.
  89                  *
  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
  92                  * invokation or not.
  93                  */
  94                 Result_NoneIOErrorZ remove(String primary_namespace, String secondary_namespace, String key, boolean lazy);
  95                 /**
  96                  * Returns a list of keys that are stored under the given `secondary_namespace` in
  97                  * `primary_namespace`.
  98                  *
  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.
 101                  */
 102                 Result_CVec_StrZIOErrorZ list(String primary_namespace, String secondary_namespace);
 103         }
 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 == null ? 0 : ret.clone_ptr();
 112                                 return result;
 113                         }
 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 == null ? 0 : ret.clone_ptr();
 118                                 return result;
 119                         }
 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 == null ? 0 : ret.clone_ptr();
 124                                 return result;
 125                         }
 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 == null ? 0 : ret.clone_ptr();
 130                                 return result;
 131                         }
 132                 });
 133                 return impl_holder.held;
 134         }
 135         /**
 136          * Returns the data stored for the given `primary_namespace`, `secondary_namespace`, and
 137          * `key`.
 138          *
 139          * Returns an [`ErrorKind::NotFound`] if the given `key` could not be found in the given
 140          * `primary_namespace` and `secondary_namespace`.
 141          *
 142          * [`ErrorKind::NotFound`]: io::ErrorKind::NotFound
 143          */
 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);
 152                 return ret_hu_conv;
 153         }
 154
 155         /**
 156          * Persists the given data under the given `key`.
 157          *
 158          * Will create the given `primary_namespace` and `secondary_namespace` if not already present
 159          * in the store.
 160          */
 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);
 170                 return ret_hu_conv;
 171         }
 172
 173         /**
 174          * Removes any data that had previously been persisted under the given `key`.
 175          *
 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.
 180          *
 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.
 185          *
 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
 188          * invokation or not.
 189          */
 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);
 199                 return ret_hu_conv;
 200         }
 201
 202         /**
 203          * Returns a list of keys that are stored under the given `secondary_namespace` in
 204          * `primary_namespace`.
 205          *
 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.
 208          */
 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);
 216                 return ret_hu_conv;
 217         }
 218
 219 }