E - element typepublic abstract class AbstractKVNavigableSet<E> extends AbstractNavigableSet<E>
NavigableSet support superclass for sets backed by elements encoded as byte[]
keys in a KVStore and whose sort order is consistent with their byte[] key encoding.
There must be an equivalence between elements and byte[] key encodings (i.e., there must be
only one valid encoding per set element). The values corresponding to the keys are ignored.
Subclass Methods
Subclasses must implement the encode() and decode()
methods to convert elements to/from byte[] keys (associated values are ignored), and
createSubSet()
to allow creating reversed and restricted range sub-sets.
Subclasses must also implement comparator(), and the resulting sort order must be consistent with
the sort order of the encoded byte[] keys (possibly reversed).
This class provides a read-only implementation; for a mutable implementation, subclasses should also implement
add() (if appropriate), remove(), and AbstractCollection.clear(); note, these methods must verify
the key isVisible() before making any changes.
Additional subclass notes:
iterator() returns an Iterator whose Iterator.remove()
method delegates to this instance's remove() method.
Prefix Mode
Instances support a "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 bytes produced by encode() or consumed by decode().
When not in prefix mode, decode() must consume the entire key to preserve correct semantics.
Key Restrictions
Instances are configured with an (optional) KeyRange; when range restriction is in
effect, this key range corresponds to the bounds.
Instances also support filtering visible values using a KeyFilter; see filterKeys().
To be isVisible(byte[]) in the set, keys must both be in the KeyRange and pass the KeyFilter.
Concurrent Modifications
This implementation never throws ConcurrentModificationException; instead, iterators always
see the most up-to-date state of the associated KVStore.
AbstractKVNavigableMap| Modifier and Type | Field and Description |
|---|---|
protected KeyFilter |
keyFilter
Key filter, or null if all keys in the key range should be visible.
|
protected KeyRange |
keyRange
Key range, or null for the entire range.
|
protected KVStore |
kv
The underlying
KVStore. |
protected boolean |
prefixMode
Whether we are in "prefix" mode.
|
protected boolean |
reversed
Whether the ordering of this instance is reversed.
|
bounds| Modifier | Constructor and Description |
|---|---|
protected |
AbstractKVNavigableSet(KVStore kv,
boolean prefixMode)
Convenience constructor for when there are no range restrictions.
|
protected |
AbstractKVNavigableSet(KVStore kv,
boolean prefixMode,
boolean reversed,
KeyRange keyRange,
KeyFilter keyFilter,
Bounds<E> bounds)
Internal constructor.
|
protected |
AbstractKVNavigableSet(KVStore kv,
boolean prefixMode,
byte[] prefix)
Convenience constructor for when the range of visible
KVStore keys is all keys sharing a given byte[] prefix. |
protected |
AbstractKVNavigableSet(KVStore kv,
boolean prefixMode,
KeyRange keyRange)
Primary constructor.
|
| Modifier and Type | Method and Description |
|---|---|
boolean |
contains(Object obj) |
protected NavigableSet<E> |
createSubSet(boolean reverse,
Bounds<E> newBounds)
Create a (possibly reversed) view of this instance with (possibly) tighter lower and/or upper bounds.
|
protected abstract NavigableSet<E> |
createSubSet(boolean newReversed,
KeyRange newKeyRange,
KeyFilter newKeyFilter,
Bounds<E> newBounds)
Create a (possibly reversed) view of this instance with (possibly) tighter lower and/or upper bounds and
the given
KeyFilter, if any. |
protected abstract E |
decode(ByteReader reader)
Decode an element from a
byte[] key. |
protected abstract void |
encode(ByteWriter writer,
Object obj)
Encode the given object into a
byte[] key. |
protected byte[] |
encodeVisible(Object obj,
boolean fail)
Encode the given object, if possible, and verify corresponding
byte[] key is visible,
otherwise return null or throw an exception. |
NavigableSet<E> |
filterKeys(KeyFilter keyFilter)
Create a view of this instance with additional filtering applied to the underlying
byte[] encoded keys. |
E |
first() |
boolean |
isEmpty()
Overridden in
AbstractIterationSet to minimize the use of AbstractIterationSet.size(). |
protected boolean |
isVisible(byte[] key)
|
protected boolean |
isWithinLowerBound(E elem)
Determine if the given element is within this instance's lower bound (if any).
|
protected boolean |
isWithinUpperBound(E elem)
Determine if the given element is within this instance's upper bound (if any).
|
CloseableIterator<E> |
iterator() |
E |
last() |
E |
pollFirst() |
E |
pollLast() |
ceiling, descendingIterator, descendingSet, floor, getComparator, headSet, headSet, higher, lower, remove, searchAbove, searchBelow, spliterator, subSet, subSet, tailSet, tailSetequals, hashCode, size, toArray, toArrayremoveAlladd, addAll, clear, containsAll, retainAll, toStringclone, finalize, getClass, notify, notifyAll, wait, wait, waitcomparatoradd, addAll, clear, containsAll, equals, hashCode, removeAll, retainAll, size, toArray, toArrayparallelStream, removeIf, streamprotected final boolean prefixMode
protected final boolean reversed
protected final KeyRange keyRange
protected final KeyFilter keyFilter
protected AbstractKVNavigableSet(KVStore kv, boolean prefixMode)
kv - underlying KVStoreprefixMode - whether to allow keys to have trailing garbageIllegalArgumentException - if kv is nullprotected AbstractKVNavigableSet(KVStore kv, boolean prefixMode, byte[] prefix)
KVStore keys is all keys sharing a given byte[] prefix.kv - underlying KVStoreprefixMode - whether to allow keys to have trailing garbageprefix - prefix defining minimum and maximum keysIllegalArgumentException - if kv is nullIllegalArgumentException - if prefix is null or emptyprotected AbstractKVNavigableSet(KVStore kv, boolean prefixMode, KeyRange keyRange)
kv - underlying KVStoreprefixMode - whether to allow keys to have trailing garbagekeyRange - key range restriction, or null for noneIllegalArgumentException - if kv is nullprotected AbstractKVNavigableSet(KVStore kv, boolean prefixMode, boolean reversed, KeyRange keyRange, KeyFilter keyFilter, Bounds<E> bounds)
Note: if bounds are set, then keyRange must exclude all keys outside of those bounds.
kv - underlying KVStoreprefixMode - whether to allow keys to have trailing garbagereversed - whether ordering is reversed (implies bounds are also inverted, but not keyRange)keyRange - key range restriction, or null for nonekeyFilter - key filter, or null for nonebounds - range restrictionIllegalArgumentException - if kv or bounds is nullpublic boolean isEmpty()
AbstractIterationSetAbstractIterationSet to minimize the use of AbstractIterationSet.size().isEmpty in interface Collection<E>isEmpty in interface Set<E>isEmpty in class AbstractIterationSet<E>public E first()
public E last()
public E pollFirst()
pollFirst in interface NavigableSet<E>pollFirst in class AbstractNavigableSet<E>public E pollLast()
pollLast in interface NavigableSet<E>pollLast in class AbstractNavigableSet<E>public boolean contains(Object obj)
contains in interface Collection<E>contains in interface Set<E>contains in class AbstractCollection<E>public CloseableIterator<E> iterator()
iterator in interface Iterable<E>iterator in interface Collection<E>iterator in interface NavigableSet<E>iterator in interface Set<E>iterator in class AbstractCollection<E>public NavigableSet<E> filterKeys(KeyFilter keyFilter)
byte[] encoded keys.
Any set element for which the corresponding key does not pass keyFilter will be effectively hidden from view.
The restrictions of the given KeyFilter will be added to any current KeyFilter restrictions on this instance.
The AbstractNavigableSet.bounds associated with this instance will not change.
keyFilter - additional key filtering to applyIllegalArgumentException - if keyFilter is nullprotected boolean isWithinLowerBound(E elem)
AbstractNavigableSet
The implementation in AbstractNavigableSet returns this.bounds.isWithinLowerBound(this.comparator(), elem).
isWithinLowerBound in class AbstractNavigableSet<E>elem - set elementelem is within this instance's lower bound, or this instance has no lower boundprotected boolean isWithinUpperBound(E elem)
AbstractNavigableSet
The implementation in AbstractNavigableSet returns this.bounds.isWithinUpperBound(this.comparator(), elem).
isWithinUpperBound in class AbstractNavigableSet<E>elem - set elementelem is within this instance's upper bound, or this instance has no upper boundprotected final NavigableSet<E> createSubSet(boolean reverse, Bounds<E> newBounds)
AbstractNavigableSetnewBounds are consistent with the new ordering (i.e., reversed relative to this instance's ordering if
reverse is true) and have already been range-checked against this instance's current bounds.createSubSet in class AbstractNavigableSet<E>reverse - whether the new set's ordering should be reversed relative to this instance's orderingnewBounds - new boundsprotected abstract NavigableSet<E> createSubSet(boolean newReversed, KeyRange newKeyRange, KeyFilter newKeyFilter, Bounds<E> newBounds)
KeyFilter, if any.
The bounds are consistent with the reversed ordering (i.e., reversed if reverse is true)
and have already been range-checked against this instance's bounds.newReversed - whether the new set's ordering should be reversed (implies newBounds are also inverted,
but not keyRange); note: means "absolutely" reversed, not relative to this instancenewKeyRange - new key range, or null for none; will be consistent with bounds, if anynewKeyFilter - new key filter, or null for nonenewBounds - new boundsIllegalArgumentException - if newBounds is nullprotected abstract void encode(ByteWriter writer, Object obj)
byte[] key.
Note that this method must throw IllegalArgumentException, not ClassCastException
or NullPointerException, if obj does not have the correct type or is an illegal null value.writer - output for encoded byte[] key corresponding to objobj - set elementIllegalArgumentException - if obj is not of the required Java type supported by this setIllegalArgumentException - if obj is null and this set does not support null elementsprotected abstract E decode(ByteReader reader)
byte[] key.
If not in prefix mode, all of reader must be consumed; otherwise, the consumed portion
is the prefix and any following keys with the same prefix are ignored.
reader - input for encoded bytesprotected boolean isVisible(byte[] key)
byte[] key is visible in this set according to the configured
KeyRange and/or KeyFilter, if any.key - key to testIllegalArgumentException - if key is nullfilterKeys()protected byte[] encodeVisible(Object obj, boolean fail)
byte[] key is visible,
otherwise return null or throw an exception.
Delegates to encode(ByteWriter, Object) to attempt the actual encoding.obj - object to encode, possibly nullfail - whether, if obj can't be encoded, to throw an exception (true) or return null (false)obj, or null if fail is false and obj has the wrong type or is out of boundsIllegalArgumentException - if fail is true and obj has the wrong typeIllegalArgumentException - if fail is true and the resulting key is not visibleCopyright © 2022. All rights reserved.