io.permazen.kv

Class AbstractKVStore

java.lang.Object

io.permazen.kv.AbstractKVStore

All Implemented Interfaces:

KVStore

Direct Known Subclasses:

ArrayKVStore, AtomicArrayKVStore, AtomicKVDatabase, BerkeleyKVTransaction, LevelDBKVStore, MutableView, NavigableMapKVStore, ReadOnlySpannerView, RocksDBKVStore, SimpleKVTransaction, XodusKVStore

public abstract class AbstractKVStore
extends Object
implements KVStore

Support superclass for KVStore implementations.

This class provides a partial implementation via the following methods:

• A get() implementation based on getAtLeast()
• getAtLeast() and getAtMost() implementations based on getRange().
• A remove() implementation that delegates to removeRange().
• A removeRange() implementation that delegates to getRange(), iterating through the range of keys and removing them one-by-one via Iterator.remove().
• encodeCounter(), encodeCounter(), and adjustCounter() implementations using normal reads and writes of values in big-endian encoding (does not provide any lock-free behavior).
• A put() implementation throwing UnsupportedOperationException

Therefore, a read-only KVStore implementation is possible simply by implementing KVStore.getRange(byte[], byte[], boolean).

See Also:

KVPairIterator

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractKVStore()

Method Summary

Modifier and Type	Method and Description
void	adjustCounter(byte[] key, long amount) Adjust the counter at the given key by the given amount.
long	decodeCounter(byte[] value) Decode a counter value previously encoded by encodeCounter().
byte[]	encodeCounter(long value) Encode a counter value into a byte[] value suitable for use with decodeCounter() and/or adjustCounter().
byte[]	get(byte[] key) Get the value associated with the given key, if any.
KVPair	getAtLeast(byte[] minKey, byte[] maxKey) Get the key/value pair having the smallest key greater than or equal to the given minimum, if any.
KVPair	getAtMost(byte[] maxKey, byte[] minKey) Get the key/value pair having the largest key strictly less than the given maximum, if any.
void	put(byte[] key, byte[] value) Set the value associated with the given key.
void	remove(byte[] key) Remove the key/value pair with the given key, if it exists.
void	removeRange(byte[] minKey, byte[] maxKey) Remove all key/value pairs whose keys are in a given range.

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, getRange, removeRange

Constructor Detail

AbstractKVStore

protected AbstractKVStore()

Method Detail

get

public byte[] get(byte[] key)

Description copied from interface: KVStore

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

Modifications to the returned byte[] array do not affect this instance.

Specified by:

get in interface KVStore

Parameters:

key - key

Returns:

value associated with key, or null if not found

getAtLeast

public KVPair getAtLeast(byte[] minKey,
                         byte[] 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.

Modifications to the returned byte[] arrays do not affect this instance.

Specified by:

getAtLeast in interface KVStore

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(byte[] maxKey,
                        byte[] 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.

Modifications to the returned byte[] arrays do not affect this instance.

Specified by:

getAtMost in interface KVStore

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

put

public void put(byte[] key,
                byte[] value)

Description copied from interface: KVStore

Set the value associated with the given key.

Specified by:

put in interface KVStore

Parameters:

key - key

value - value

remove

public void remove(byte[] key)

Description copied from interface: KVStore

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

Specified by:

remove in interface KVStore

Parameters:

key - key

removeRange

public void removeRange(byte[] minKey,
                        byte[] 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

Parameters:

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

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

encodeCounter

public byte[] encodeCounter(long value)

Description copied from interface: KVStore

Encode a counter value into a byte[] value suitable for use with decodeCounter() and/or adjustCounter().

Specified by:

encodeCounter in interface KVStore

Parameters:

value - desired counter value

Returns:

encoded counter value

decodeCounter

public long decodeCounter(byte[] value)

Description copied from interface: KVStore

Decode a counter value previously encoded by encodeCounter().

Specified by:

decodeCounter in interface KVStore

Parameters:

value - encoded counter value

Returns:

decoded counter value

adjustCounter

public void adjustCounter(byte[] key,
                          long amount)

Description copied from interface: KVStore

Adjust the counter at the given key by the given amount.

Ideally this operation should behave in a lock-free manner, so that concurrent transactions can invoke it without conflict. However, when lock-free behavior occurs (if at all) depends on the implementation.

If there is no value associated with key, or key's value is not a valid counter encoding as would be acceptable to decodeCounter(), then how this operation affects key's value is undefined.

Specified by:

adjustCounter in interface KVStore

Parameters:

key - key

amount - amount to adjust counter value by