Package io.permazen.kv

Class KVPairIterator

java.lang.Object
io.permazen.kv.KVPairIterator
All Implemented Interfaces:
CloseableIterator<KVPair>, Closeable, AutoCloseable, Iterator<KVPair>
public class KVPairIterator extends Object implements CloseableIterator<KVPair>
An Iterator that iterates over all key/value pairs in a KVStore within a range of keys, without using the KVStore.getRange() method.

This class can be used to implement KVStore.getRange() in KVStore implementations that don't natively support iteration. Instances support forward and reverse iteration and java.util.Iterator.remove().

The iteration is instead implemented using KVStore.getAtLeast(), KVStore.getAtMost(), and KVStore.remove().

Repositioning

Instances support arbitrary repositioning via setNextTarget().

Key Restrictions

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

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

Concurrent Modification

Instances are thread safe, and always reflect the current state of the underlying KVStore, even if it is mutated concurrently.

  • Constructor Details

    • KVPairIterator

      public KVPairIterator(KVStore kv, KeyRange keyRange)
      Convenience constructor for forward iteration over a specified range. Equivalent to: 
        KVPairIterator(kv, keyRange, null, false)
      Parameters:
      kv - underlying KVStore
      keyRange - range restriction on visible keys, or null for none
      Throws:
      IllegalArgumentException - if kv is null

    • KVPairIterator

      public KVPairIterator(KVStore kv, byte[] prefix)
      Convenience constructor for forward iteration over all keys having a given prefix. Equivalent to: 
        KVPairIterator(kv, prefix, false)
      Parameters:
      kv - underlying KVStore
      prefix - range prefix
      Throws:
      IllegalArgumentException - if any parameter is null

    • KVPairIterator

      public KVPairIterator(KVStore kv, byte[] prefix, boolean reverse)
      Convenience constructor for iteration over all keys having a given prefix. Equivalent to: 
        KVPairIterator(kv, KeyRange.forPrefix(prefix), null, reverse)
      Parameters:
      kv - underlying KVStore
      prefix - range prefix
      reverse - true to iterate in a reverse direction, false to iterate in a forward direction
      Throws:
      IllegalArgumentException - if any parameter is null

    • KVPairIterator

      public KVPairIterator(KVStore kv, KeyRange keyRange, KeyFilter keyFilter, boolean reverse)
      Primary constructor.
      Parameters:
      kv - underlying KVStore
      keyRange - range restriction on visible keys, or null for none
      keyFilter - filter restriction on visible keys, or null for none
      reverse - true to iterate in a reverse direction, false to iterate in a forward direction
      Throws:
      IllegalArgumentException - if kv is null

  • Method Details

    • getKVStore

      public KVStore getKVStore()
      Get the KVStore associated with this instance.
      Returns:
      this instance's transaction

    • getKeyRange

      public KeyRange getKeyRange()
      Get the KeyRange instance used to restrict the range of visible keys, if any.
      Returns:
      KeyRange over which this iterator iterates, or null if it iterates over all keys

    • getKeyFilter

      public KeyFilter getKeyFilter()
      Get the KeyFilter instance used to filter visible keys, if any.
      Returns:
      KeyFilter in which all keys returned by this iterator must be contained, or null if keys are not filtered

    • isReverse

      public boolean isReverse()
      Determine if this instance is going forward or backward.
      Returns:
      true if this instance is reversed

    • isVisible

      public boolean isVisible(byte[] key)
      Determine if the given key would be visible in this instance. Tests the key against the configured KeyRange and/or KeyFilter, if any.
      Parameters:
      key - to test
      Returns:
      true if key is both in range and not filtered out
      Throws:
      IllegalArgumentException - if key is null

    • setNextTarget

      public void setNextTarget(byte[] targetKey)
      Reposition this instance by setting the next "target" key.

      The target key is the key we will use to find the next element via KVStore.getAtLeast(), or KVStore.getAtMost() if this is a reverse iterator. In the forward case, the target key is an inclusive lower bound on the next key, while in the reverse case it is an exclusive upper bound on the next key.

      This method may be used to reposition an interator during iteration or restart an iterator that has been exhausted. Invoking this method does not affect the behavior of remove(), i.e., you can still remove() the previously returned element even if you have invoked this method since invoking next().

      A null targetKey means to reposition this instance at the beginning of the iteration.

      This instance's configured KeyRange and KeyFilter, if any, still apply: if targetKey is not visible to this instance, the next visible key after targetKey will be next in the iteration.

      Parameters:
      targetKey - next lower bound (exclusive) if going forward, or upper bound (exclusive) if going backward; or null to restart this instance at the beginning of its iteration

    • hasNext

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

    • next

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

    • remove

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

    • close

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