Package io.permazen.kv.array

Class ArrayKVStore

java.lang.Object

io.permazen.kv.AbstractKVStore

io.permazen.kv.array.ArrayKVStore

All Implemented Interfaces:

KVStore

public class ArrayKVStore
extends AbstractKVStore

A simple read-only KVStore based on a sorted array of key/value pairs.

Instances query three ByteBuffers, one for the array index, one for the key data, and one for the value data. Data for these ByteBuffers is created using ArrayKVWriter.

Instances are optimized for minimal memory overhead and queries using keys sharing a prefix with the previously queried key. Key data is prefix-compressed.

Key and value data must not exceed 2GB (each separately).

Constructor Summary

Constructors

Constructor	Description
ArrayKVStore(ByteBuffer indx, ByteBuffer keys, ByteBuffer vals)	Constructor.

Method Summary

Modifier and Type	Method	Description
ByteData	get(ByteData key)	Get the value associated with the given key, if any.
KVPair	getAtLeast(ByteData minKey, ByteData maxKey)	Get the key/value pair having the smallest key greater than or equal to the given minimum, if any.
KVPair	getAtMost(ByteData maxKey, ByteData minKey)	Get the key/value pair having the largest key strictly less than the given maximum, if any.
CloseableIterator<KVPair>	getRange(ByteData minKey, ByteData maxKey, boolean reverse)	Iterate the key/value pairs in the specified range.
void	put(ByteData key, ByteData value)	Set the value associated with the given key.
void	remove(ByteData key)	Remove the key/value pair with the given key, if it exists.
void	removeRange(ByteData minKey, ByteData maxKey)	Remove all key/value pairs whose keys are in a given range.

Methods inherited from class io.permazen.kv.AbstractKVStore

adjustCounter, decodeCounter, encodeCounter

Methods inherited from class java.lang.Object

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

Methods inherited from interface io.permazen.kv.KVStore

apply, getRange, getRange, removeRange

Constructor Details

ArrayKVStore

public ArrayKVStore(ByteBuffer indx,
 ByteBuffer keys,
 ByteBuffer vals)

Constructor.

Parameters:

indx - buffer containing index data written by a ArrayKVWriter

keys - buffer containing key data written by a ArrayKVWriter

vals - buffer containing value data written by a ArrayKVWriter

Throws:

IllegalArgumentException - if any parameter is null

IllegalArgumentException - if indx size is not a correct multiple

Method Details

get

public ByteData get(ByteData key)

Description copied from interface: KVStore

Get the value associated with the given key, if any.

Specified by:

get in interface KVStore

Overrides:

get in class AbstractKVStore

Parameters:

key - key

Returns:

value associated with key, or null if not found

getAtLeast

public KVPair getAtLeast(ByteData minKey,
 ByteData maxKey)

Description copied from interface: KVStore

Get the key/value pair having the smallest key greater than or equal to the given minimum, if any.

An optional (exclusive) maximum key may also be specified; if maxKey is null, there is no upper bound; if maxKey <= minKey, null is always returned.

If keys starting with 0xff are not supported by this instance, and minKey starts with 0xff, then this method returns null.

Specified by:

getAtLeast in interface KVStore

Overrides:

getAtLeast in class AbstractKVStore

Parameters:

minKey - minimum key (inclusive), or null for no minimum (get the smallest key)

maxKey - maximum key (exclusive), or null for no maximum (no upper bound)

Returns:

smallest key/value pair with key >= minKey and key < maxKey, or null if none exists

getAtMost

public KVPair getAtMost(ByteData maxKey,
 ByteData minKey)

Description copied from interface: KVStore

Get the key/value pair having the largest key strictly less than the given maximum, if any.

An optional (inclusive) minimum key may also be specified; if minKey is null, there is no lower bound (equivalent to a lower bound of the empty byte array); if minKey >= maxKey, null is always returned.

If keys starting with 0xff are not supported by this instance, and maxKey starts with 0xff, then this method behaves as if maxKey were null.

Specified by:

getAtMost in interface KVStore

Overrides:

getAtMost in class AbstractKVStore

Parameters:

maxKey - maximum key (exclusive), or null for no maximum (get the largest key)

minKey - minimum key (inclusive), or null for no minimum (no lower bound)

Returns:

largest key/value pair with key < maxKey and key >= minKey, or null if none exists

getRange

public CloseableIterator<KVPair> getRange(ByteData minKey,
 ByteData maxKey,
 boolean reverse)

Description copied from interface: KVStore

Iterate the key/value pairs in the specified range. The returned CloseableIterator's remove() method must be supported and should have the same effect as invoking remove() on the corresponding key.

If keys starting with 0xff are not supported by this instance, and minKey starts with 0xff, then this method returns an empty iteration.

If keys starting with 0xff are not supported by this instance, and maxKey starts with 0xff, then this method behaves as if maxKey were null.

The returned CloseableIterator is weakly consistent (see java.util.concurrent). In short, the returned CloseableIterator must not throw ConcurrentModificationException; however, whether or not a "live" CloseableIterator reflects any modifications made after its creation is implementation dependent. Implementations that do make post-creation updates visible in the CloseableIterator, even if the update occurs after some delay, must preserve the order in which the modifications actually occurred.

The returned CloseableIterator itself is not guaranteed to be thread safe; is should only be used in the thread that created it.

Invokers of this method are encouraged to close() the returned iterators, though this is not required for correct behavior.

Parameters:

minKey - minimum key (inclusive), or null for no minimum (start at the smallest key)

maxKey - maximum key (exclusive), or null for no maximum (end at the largest key)

reverse - true to return key/value pairs in reverse order (i.e., keys descending)

Returns:

iteration of key/value pairs in the range minKey (inclusive) to maxKey (exclusive)

put

public void put(ByteData key,
 ByteData value)

Description copied from interface: KVStore

Set the value associated with the given key.

Specified by:

put in interface KVStore

Overrides:

put in class AbstractKVStore

Parameters:

key - key

value - value

remove

public void remove(ByteData key)

Description copied from interface: KVStore

Remove the key/value pair with the given key, if it exists.

Specified by:

remove in interface KVStore

Overrides:

remove in class AbstractKVStore

Parameters:

key - key

removeRange

public void removeRange(ByteData minKey,
 ByteData maxKey)

Description copied from interface: KVStore

Remove all key/value pairs whose keys are in a given range.

The minKey must be less than or equal to maxKey; if they equal (and not null) then nothing happens; if they are both null then all entries are deleted.

If keys starting with 0xff are not supported by this instance, then:

• If minKey starts with 0xff, then no change occurs
• If maxKey starts with 0xff, then this method behaves as if maxKey were null

Specified by:

removeRange in interface KVStore

Overrides:

removeRange in class AbstractKVStore

Parameters:

minKey - minimum key (inclusive), or null for no minimum

maxKey - maximum key (exclusive), or null for no maximum