Interface SegmentedKeyValueStorage

All Superinterfaces:
AutoCloseable, Closeable
All Known Subinterfaces:
SnappableKeyValueStorage, SnappedKeyValueStorage
public interface SegmentedKeyValueStorage extends Closeable
Service provided by Besu to facilitate persistent data storage.

  • Method Details

    • get

      Optional<byte[]> get(SegmentIdentifier segment, byte[] key) throws StorageException
      Get the value from the associated segment and key.
      Parameters:
      segment - the segment
      key - Index into persistent data repository.
      Returns:
      The value persisted at the key index.
      Throws:
      StorageException - the storage exception

    • getNearestBefore

      Optional<SegmentedKeyValueStorage.NearestKeyValue> getNearestBefore(SegmentIdentifier segmentIdentifier, org.apache.tuweni.bytes.Bytes key) throws StorageException
      Finds the key and corresponding value that is "nearest before" the specified key. "Nearest before" is defined as the closest key that is either exactly matching the supplied key or lexicographically before it.
      Parameters:
      segmentIdentifier - The segment to scan for the nearest key.
      key - The key for which we are searching for the nearest match before it.
      Returns:
      An Optional of NearestKeyValue, wrapping the matched key and its corresponding value, if found.
      Throws:
      StorageException - If an error occurs during the retrieval process.

    • getNearestAfter

      Optional<SegmentedKeyValueStorage.NearestKeyValue> getNearestAfter(SegmentIdentifier segmentIdentifier, org.apache.tuweni.bytes.Bytes key) throws StorageException
      Finds the key and corresponding value that is "nearest after" the specified key. "Nearest after" is defined as the closest key that is either exactly matching the supplied key or lexicographically after it.

      This method aims to find the next key in sequence after the provided key, considering the order of keys within the specified segment. It is particularly useful for iterating over keys in a sorted manner starting from a given key.

      Parameters:
      segmentIdentifier - The segment to scan for the nearest key.
      key - The key for which we are searching for the nearest match after it.
      Returns:
      An Optional of NearestKeyValue, wrapping the matched key and its corresponding value, if found.
      Throws:
      StorageException - If an error occurs during the retrieval process.

    • containsKey

      default boolean containsKey(SegmentIdentifier segment, byte[] key) throws StorageException
      Contains key.
      Parameters:
      segment - the segment
      key - the key
      Returns:
      the boolean
      Throws:
      StorageException - the storage exception

    • startTransaction

      SegmentedKeyValueStorageTransaction startTransaction() throws StorageException
      Begins a transaction. Returns a transaction object that can be updated and committed.
      Returns:
      An object representing the transaction.
      Throws:
      StorageException - the storage exception

    • startLowPriorityTransaction

      default SegmentedKeyValueStorageTransaction startLowPriorityTransaction() throws StorageException
      Begins a transaction with low write priority. On RocksDB-backed storage this sets WriteOptions.low_pri = true, which causes RocksDB to throttle this transaction's writes more aggressively than normal writes when compaction back-pressure builds.

      Non-RocksDB implementations fall back to startTransaction().

      Returns:
      An object representing the transaction.
      Throws:
      StorageException - the storage exception

    • stream

      Stream<org.apache.commons.lang3.tuple.Pair<byte[],byte[]>> stream(SegmentIdentifier segmentIdentifier)
      Returns a stream of all keys for the segment.
      Parameters:
      segmentIdentifier - The segment identifier whose keys we want to stream.
      Returns:
      A stream of all keys in the specified segment.

    • streamFromKey

      Stream<org.apache.commons.lang3.tuple.Pair<byte[],byte[]>> streamFromKey(SegmentIdentifier segmentIdentifier, 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:
      segmentIdentifier - The segment identifier whose keys we want to stream.
      startKey - The key from which the stream should start.
      Returns:
      A stream of key-value pairs starting from the specified key.

    • streamFromKey

      Stream<org.apache.commons.lang3.tuple.Pair<byte[],byte[]>> streamFromKey(SegmentIdentifier segmentIdentifier, 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:
      segmentIdentifier - The segment identifier whose keys we want to stream.
      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(SegmentIdentifier segmentIdentifier)
      Stream keys.
      Parameters:
      segmentIdentifier - the segment identifier
      Returns:
      the stream

    • tryDelete

      boolean tryDelete(SegmentIdentifier segmentIdentifier, byte[] key) throws StorageException
      Delete the value corresponding to the given key in the given segment if a write lock can be instantly acquired on the underlying storage. Do nothing otherwise.
      Parameters:
      segmentIdentifier - The segment identifier whose keys we want to stream.
      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(SegmentIdentifier segmentIdentifier, Predicate<byte[]> returnCondition)
      Gets all keys that matches condition.
      Parameters:
      segmentIdentifier - the segment identifier
      returnCondition - the return condition
      Returns:
      set of result

    • getAllValuesFromKeysThat

      Set<byte[]> getAllValuesFromKeysThat(SegmentIdentifier segmentIdentifier, Predicate<byte[]> returnCondition)
      Gets all values from keys that matches condition.
      Parameters:
      segmentIdentifier - the segment identifier
      returnCondition - the return condition
      Returns:
      the set of result

    • clear

      void clear(SegmentIdentifier segmentIdentifier)
      Clear.
      Parameters:
      segmentIdentifier - the segment identifier

    • isClosed

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