Package io.permazen.kv.util

Class AbstractKVIterator<E>

java.lang.Object
io.permazen.kv.util.AbstractKVIterator<E>
Type Parameters:
E - iteration element type
All Implemented Interfaces:
CloseableIterator<E>, Closeable, AutoCloseable, Iterator<E>
public abstract class AbstractKVIterator<E> extends Object implements CloseableIterator<E>
Iterator implementation whose values derive from key/value byte[] pairs in a KVStore. Instances support either forward or reverse iteration.

Subclass Methods

Subclasses must implement decodePair() to convert key/value pairs into iteration elements.

This class provides a read-only implementation; for a mutable implementation, subclasses should also implement doRemove().

Prefix Mode

Instances support "prefix mode" where the byte[] keys may have arbitrary trailing garbage, which is ignored, and so by definition no key can be a prefix of any other key. The length of the prefix is determined implicitly by the number of key bytes consumed by decodePair(). When not in prefix mode, decodePair() must consume the entire key to preserve correct semantics. If it fails to do so, an error is logged and, if assertions are enabled, an AssertionError is thrown.

Key Restrictions

Instances are configured with an (optional) KeyRange that restricts the iteration to the specified range.

Instances also support filtering visible values using a KeyFilter. To be visible in the iteration, keys must both be within the KeyRange and pass the KeyFilter.

Concurrent Modification

Instances of this class are thread safe.

Internally, when not in prefix mode and no KeyFilter is configured, this instance will rely on the iteration from KVStore.getRange(); otherwise, it will use a KVPairIterator. Therefore, in the former case, whether this iteration always reflects the current state of the underlying KVStore depends on the behavior of KVStore.getRange().

See Also:

  • Field Details

    • kv

      protected final KVStore kv
      The underlying KVStore.

    • prefixMode

      protected final boolean prefixMode
      Whether we are in "prefix" mode.

    • reversed

      protected final boolean reversed
      Whether this instance is iterating in the reverse direction.

  • Constructor Details

    • AbstractKVIterator

      protected AbstractKVIterator(KVStore kv, boolean prefixMode, boolean reversed)
      Convenience constructor for when there are no range restrictions.
      Parameters:
      kv - underlying KVStore
      prefixMode - whether to allow keys to have trailing garbage
      reversed - whether to iterate in the reverse direction

    • AbstractKVIterator

      protected AbstractKVIterator(KVStore kv, boolean prefixMode, boolean reversed, byte[] prefix)
      Convenience constructor for when the range of visible KVStore keys is all keys sharing a given byte[] prefix.
      Parameters:
      kv - underlying KVStore
      prefixMode - whether to allow keys to have trailing garbage
      reversed - whether to iterate in the reverse direction
      prefix - prefix defining minimum and maximum keys
      Throws:
      IllegalArgumentException - if prefix is null or empty

    • AbstractKVIterator

      protected AbstractKVIterator(KVStore kv, boolean prefixMode, boolean reversed, KeyRange keyRange, KeyFilter keyFilter)
      Primary constructor.
      Parameters:
      kv - underlying KVStore
      prefixMode - whether to allow keys to have trailing garbage
      reversed - whether to iterate in the reverse direction
      keyRange - key range restriction, or null for none
      keyFilter - key filter, or null for none
      Throws:
      IllegalArgumentException - if kv is null

  • Method Details

    • hasNext

      public boolean hasNext()
      Specified by:
      hasNext in interface Iterator<E>

    • next

      public E next()
      Specified by:
      next in interface Iterator<E>

    • remove

      public void remove()
      Specified by:
      remove in interface Iterator<E>

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Specified by:
      close in interface CloseableIterator<E>

    • decodePair

      protected abstract E decodePair(KVPair pair, ByteReader keyReader)
      Decode an iteration element from a key/value pair.

      If not in prefix mode, all of keyReader must be consumed; otherwise, the consumed portion is the prefix and any following keys with the same prefix are ignored.

      Parameters:
      pair - key/value pair
      keyReader - key input
      Returns:
      decoded iteration element

    • doRemove

      protected void doRemove(E value, KVPair pair)
      Remove the previously iterated value.

      The implementation in AbstractKVIterator always throws UnsupportedOperationException. Subclasses should override to make the iterator mutable.

      Parameters:
      value - most recent value returned by next()
      pair - the key/value pair corresponding to value