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. Therefore, it can be used to implement KVStore.getRange() in KVStore implementations that don't natively support iteration. Instances support forward or 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 Summary

Constructors

Constructor and Description
KVPairIterator(KVStore kv, byte[] prefix) Convenience constructor for forward iteration over all keys having a given prefix.
KVPairIterator(KVStore kv, byte[] prefix, boolean reverse) Convenience constructor for iteration over all keys having a given prefix.
KVPairIterator(KVStore kv, KeyRange keyRange) Convenience constructor for forward iteration over a specified range.
KVPairIterator(KVStore kv, KeyRange keyRange, KeyFilter keyFilter, boolean reverse) Primary constructor.

Method Summary

Modifier and Type	Method and Description
void	close()
KeyFilter	getKeyFilter() Get the KeyFilter instance used to filter visible keys, if any.
KeyRange	getKeyRange() Get the KeyRange instance used to restrict the range of visible keys, if any.
KVStore	getKVStore() Get the KVStore associated with this instance.
boolean	hasNext()
boolean	isReverse() Determine if this instance is going forward or backward.
boolean	isVisible(byte[] key) Determine if the given key would be visible in this instance.
KVPair	next()
void	remove()
void	setNextTarget(byte[] targetKey) Reposition this instance by setting the next "target" key.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.permazen.util.CloseableIterator

wrap, wrap

Methods inherited from interface java.util.Iterator

forEachRemaining

Constructor Detail

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 Detail

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 CloseableIterator<KVPair>

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable