Interface KeyValueStorage

All Superinterfaces:
AutoCloseable, Closeable
public interface KeyValueStorage extends Closeable
Responsible for storing values against keys.

Behaviour expected with regard to key to value mapping is that of a map, one key maps to one value, when a new value is added with an existing key, that key now points at the new value.

All keys and values must be non-null.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Deletes all keys and values from the storage.
    boolean
    containsKey(byte[] key)
    Whether the key-value storage contains the given key.
    Optional<byte[]>
    get(byte[] key)
    Retrieves the value associated with a given key.
    Set<byte[]>
    getAllKeysThat(Predicate<byte[]> returnCondition)
    Performs an evaluation against each key in the store, returning the set of entries that pass.
    Set<byte[]>
    getAllValuesFromKeysThat(Predicate<byte[]> returnCondition)
    Gets all values from keys that matches the predicate.
    boolean
    isClosed()
    Return Whether the underlying storage is closed.
    KeyValueStorageTransaction
    startTransaction()
    Begins a fresh transaction, for sequencing operations for later atomic execution.
    Stream<org.apache.commons.lang3.tuple.Pair<byte[],byte[]>>
    stream()
    Returns a stream of all keys and values.
    Stream<org.apache.commons.lang3.tuple.Pair<byte[],byte[]>>
    streamFromKey(byte[] startKey)
    Returns a stream of key-value pairs starting from the specified key.
    Stream<org.apache.commons.lang3.tuple.Pair<byte[],byte[]>>
    streamFromKey(byte[] startKey, byte[] endKey)
    Returns a stream of key-value pairs starting from the specified key, ending at the specified key.
    Stream<byte[]>
    streamKeys()
    Returns a stream of all keys.
    boolean
    tryDelete(byte[] key)
    Delete the value corresponding to the given key if a write lock can be instantly acquired on the underlying storage.

    Methods inherited from interface Closeable

    close

  • Method Details

    • clear

      void clear() throws StorageException
      Deletes all keys and values from the storage.
      Throws:
      StorageException - problem encountered when attempting to clear storage.

    • containsKey

      boolean containsKey(byte[] key) throws StorageException
      Whether the key-value storage contains the given key.
      Parameters:
      key - a key that might be contained in the key-value storage.
      Returns:
      true when the given key is present in keyset, false otherwise.
      Throws:
      StorageException - problem encountered when interacting with the key set.

    • get

      Optional<byte[]> get(byte[] key) throws StorageException
      Retrieves the value associated with a given key.
      Parameters:
      key - whose associated value is being retrieved.
      Returns:
      an Optional containing the value associated with the specified key, otherwise empty.
      Throws:
      StorageException - problem encountered during the retrieval attempt.

    • stream

      Stream<org.apache.commons.lang3.tuple.Pair<byte[],byte[]>> stream() throws StorageException
      Returns a stream of all keys and values.
      Returns:
      A stream of all keys and values in storage.
      Throws:
      StorageException - problem encountered during the retrieval attempt.

    • streamFromKey

      Stream<org.apache.commons.lang3.tuple.Pair<byte[],byte[]>> streamFromKey(byte[] startKey)
      Returns a stream of key-value pairs starting from the specified key. This method is used to retrieve a stream of data from the storage, starting from the given key. If no data is available from the specified key onwards, an empty stream is returned.
      Parameters:
      startKey - The key from which the stream should start.
      Returns:
      A stream of key-value pairs starting from the specified key.
      Throws:
      StorageException - If an error occurs while accessing the storage.

    • streamFromKey

      Stream<org.apache.commons.lang3.tuple.Pair<byte[],byte[]>> streamFromKey(byte[] startKey, byte[] endKey)
      Returns a stream of key-value pairs starting from the specified key, ending at the specified key. This method is used to retrieve a stream of data from the storage, starting from the given key. If no data is available from the specified key onwards, an empty stream is returned.
      Parameters:
      startKey - The key from which the stream should start.
      endKey - The key at which the stream should stop.
      Returns:
      A stream of key-value pairs starting from the specified key.

    • streamKeys

      Stream<byte[]> streamKeys() throws StorageException
      Returns a stream of all keys.
      Returns:
      A stream of all keys in storage.
      Throws:
      StorageException - problem encountered during the retrieval attempt.

    • tryDelete

      boolean tryDelete(byte[] key) throws StorageException
      Delete the value corresponding to the given key if a write lock can be instantly acquired on the underlying storage. Do nothing otherwise.
      Parameters:
      key - The key to delete.
      Returns:
      false if the lock on the underlying storage could not be instantly acquired, true otherwise
      Throws:
      StorageException - any problem encountered during the deletion attempt.

    • getAllKeysThat

      Set<byte[]> getAllKeysThat(Predicate<byte[]> returnCondition)
      Performs an evaluation against each key in the store, returning the set of entries that pass.
      Parameters:
      returnCondition - predicate to evaluate each key against, unless the result is null, the key is added to the returned list of keys.
      Returns:
      the set of keys that pass the condition.

    • getAllValuesFromKeysThat

      Set<byte[]> getAllValuesFromKeysThat(Predicate<byte[]> returnCondition)
      Gets all values from keys that matches the predicate.
      Parameters:
      returnCondition - the return condition
      Returns:
      the all values from keys that

    • startTransaction

      KeyValueStorageTransaction startTransaction() throws StorageException
      Begins a fresh transaction, for sequencing operations for later atomic execution.
      Returns:
      transaction to sequence key-value operations.
      Throws:
      StorageException - problem encountered when starting a new transaction.

    • isClosed

      boolean isClosed()
      Return Whether the underlying storage is closed.
      Returns:
      boolean indicating whether the storage is closed.