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, tailSet
equals, hashCode, size, toArray, toArray
removeAll
add, addAll, clear, containsAll, retainAll, toString
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
comparator
add, addAll, clear, containsAll, equals, hashCode, removeAll, retainAll, size, toArray, toArray
parallelStream, removeIf, stream
protected final boolean prefixMode
protected final boolean reversed
protected final KeyRange keyRange
protected final KeyFilter keyFilter
protected AbstractKVNavigableSet(KVStore kv, boolean prefixMode)
kv
- underlying KVStore
prefixMode
- 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 KVStore
prefixMode
- 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 KVStore
prefixMode
- 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 KVStore
prefixMode
- 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()
AbstractIterationSet
AbstractIterationSet
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)
AbstractNavigableSet
newBounds
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 obj
obj
- 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.