Interface KeyValueStore

All Superinterfaces:
Namespaced<KeyValueStore>
All Known Implementing Classes:
DefaultKeyValueStore
public interface KeyValueStore extends Namespaced<KeyValueStore>
A simple interface for storing, retrieving, and removing key-value pairs.

This interface provides basic persistence operations such as storing values (with optional guarantees), retrieving them by key, conditionally storing only if absent, and deleting by key. Writes return futures and do not block. Use an explicit Guarantee.STORED and await its future when another operation depends on durable storage. Active tracking batches await registered write completions.

Note: This API is considered legacy in the Fluxzero Runtime. It is recommended to use the more advanced and flexible DocumentStore instead, which supports structured querying, indexing, updates, and document lifecycle features.

This interface is still supported internally for backward compatibility and simple data use cases.

See Also:

  • Method Details

    • forNamespace

      default KeyValueStore forNamespace(String namespace)
      Returns this key-value store scoped to the requested namespace.
      Specified by:
      forNamespace in interface Namespaced<KeyValueStore>
      Parameters:
      namespace - the namespace to which the returned store is scoped
      Returns:
      the key-value store associated with the specified namespace

    • store

      default CompletableFuture<Void> store(String key, Object value)
      Stores a value under the given key with the default Guarantee.DEFAULT delivery guarantee.
      Parameters:
      key - the key to store the value under
      value - the value to store
      Returns:
      delivery completion according to the application default

    • store

      CompletableFuture<Void> store(String key, Object value, io.fluxzero.common.Guarantee guarantee)
      Stores a value under the given key with the specified delivery guarantee.
      Parameters:
      key - the key to store the value under
      value - the value to store
      guarantee - the delivery guarantee (DEFAULT, NONE, SENT, or STORED)
      Returns:
      completion according to the selected guarantee

    • storeIfAbsent

      CompletableFuture<Boolean> storeIfAbsent(String key, Object value)
      Stores a value only if there is no existing value for the specified key. This always requests a stored result; the application delivery default does not weaken the conditional operation.
      Parameters:
      key - the key to store the value under
      value - the value to store
      Returns:
      a future with true if the value was stored, false if the key already had a value

    • get

      <R> R get(String key)
      Retrieves the value associated with the given key.
      Type Parameters:
      R - the expected result type
      Parameters:
      key - the key to retrieve
      Returns:
      the stored value, or null if not found

    • delete

      default CompletableFuture<Void> delete(String key)
      Removes the value associated with the given key.
      Parameters:
      key - the key to delete
      Returns:
      completion according to the application default

    • delete

      CompletableFuture<Void> delete(String key, io.fluxzero.common.Guarantee guarantee)
      Removes a value asynchronously with the specified delivery guarantee.
      Parameters:
      key - the key to delete
      guarantee - concrete guarantee or DEFAULT
      Returns:
      completion according to the selected guarantee