org.apache.samza.storage.kv

Interface KeyValueStore<K,V>

Type Parameters:

K - the type of keys maintained by this key-value store.

V - the type of values maintained by this key-value store.

public interface KeyValueStore<K,V>

A key-value store that supports put, get, delete, and range queries.

Field Summary

Fields

Modifier and Type	Field and Description
static org.slf4j.Logger	LOG

Method Summary

Modifier and Type	Method and Description
KeyValueIterator<K,V>	all() Returns an iterator for all entries in this key-value store.
java.util.Optional<java.nio.file.Path>	checkpoint(CheckpointId id) Create a persistent checkpoint / snapshot of the current store state and return it's path.
void	close() Closes this key-value store, if applicable, relinquishing any underlying resources.
void	delete(K key) Deletes the mapping for the specified key from this key-value store (if such mapping exists).
default void	deleteAll(java.util.List<K> keys) Deletes the mappings for the specified keys from this key-value store (if such mappings exist).
void	flush() Flushes this key-value store, if applicable.
V	get(K key) Gets the value associated with the specified key.
default java.util.Map<K,V>	getAll(java.util.List<K> keys) Gets the values with which the specified keys are associated.
default void	init(Context context) Optional lifecycle management method for each KV store, storage engine invokes this initialization during org.apache.samza.storage.StorageEngine#init
void	put(K key, V value) Updates the mapping of the specified key-value pair; Associates the specified key with the specified value.
void	putAll(java.util.List<Entry<K,V>> entries) Updates the mappings of the specified key-value entries.
KeyValueIterator<K,V>	range(K from, K to) Returns an iterator for a sorted range of entries specified by [from, to).
default KeyValueSnapshot<K,V>	snapshot(K from, K to) Returns a snapshot of this store for a sorted range of entries specified by [from, to).

Field Detail

LOG

static final org.slf4j.Logger LOG

Method Detail

init

default void init(Context context)

Optional lifecycle management method for each KV store, storage engine invokes this initialization during org.apache.samza.storage.StorageEngine#init

Parameters:

context - holder for application and samza framework objects

get

V get(K key)

Gets the value associated with the specified key.

Parameters:

key - the key with which the associated value is to be fetched.

Returns:

if found, the value associated with the specified key; otherwise, null.

Throws:

java.lang.NullPointerException - if the specified key is null.

getAll

default java.util.Map<K,V> getAll(java.util.List<K> keys)

Gets the values with which the specified keys are associated.

Parameters:

keys - the keys with which the associated values are to be fetched.

Returns:

a map of the keys that were found and their respective values.

Throws:

java.lang.NullPointerException - if the specified keys list, or any of the keys, is null.

put

void put(K key,
         V value)

Updates the mapping of the specified key-value pair; Associates the specified key with the specified value.

Parameters:

key - the key with which the specified value is to be associated.

value - the value with which the specified key is to be associated.

Throws:

java.lang.NullPointerException - if the specified key or value is null.

putAll

void putAll(java.util.List<Entry<K,V>> entries)

Updates the mappings of the specified key-value entries.

Parameters:

entries - the updated mappings to put into this key-value store.

Throws:

java.lang.NullPointerException - if any of the specified entries has null as key or value.

delete

void delete(K key)

Deletes the mapping for the specified key from this key-value store (if such mapping exists).

Parameters:

key - the key for which the mapping is to be deleted.

Throws:

java.lang.NullPointerException - if the specified key is null.

deleteAll

default void deleteAll(java.util.List<K> keys)

Deletes the mappings for the specified keys from this key-value store (if such mappings exist).

Parameters:

keys - the keys for which the mappings are to be deleted.

Throws:

java.lang.NullPointerException - if the specified keys list, or any of the keys, is null.

range

KeyValueIterator<K,V> range(K from,
                            K to)

Returns an iterator for a sorted range of entries specified by [from, to).

API Note: The returned iterator MUST be closed after use. The comparator used for finding entries that belong to the specified range compares the underlying serialized big-endian byte array representation of keys, lexicographically.

Parameters:

from - the key specifying the low endpoint (inclusive) of the keys in the returned range.

to - the key specifying the high endpoint (exclusive) of the keys in the returned range.

Returns:

an iterator for the specified key range.

Throws:

java.lang.NullPointerException - if null is used for from or to.

See Also:

Lexicographical order article at Wikipedia

snapshot

default KeyValueSnapshot<K,V> snapshot(K from,
                                       K to)

Returns a snapshot of this store for a sorted range of entries specified by [from, to). The snapshot is immutable - ie., any mutations to the store are not reflected in the snapshot after it is created.

API Note: The returned snapshot MUST be closed after use.

Parameters:

from - the key specifying the low endpoint (inclusive) of the keys in the returned range.

to - the key specifying the high endpoint (exclusive) of the keys in the returned range.

Returns:

a snapshot for the specified key range.

Throws:

java.lang.NullPointerException - if null is used for from or to.

all

KeyValueIterator<K,V> all()

Returns an iterator for all entries in this key-value store.

API Note: The returned iterator MUST be closed after use.

Returns:

an iterator for all entries in this key-value store.

close

void close()

Closes this key-value store, if applicable, relinquishing any underlying resources.

flush

void flush()

Flushes this key-value store, if applicable.

checkpoint

@InterfaceStability.Unstable
java.util.Optional<java.nio.file.Path> checkpoint(CheckpointId id)

Create a persistent checkpoint / snapshot of the current store state and return it's path.

Returns:

the path of the persistent store checkpoint, or an empty optional if checkpoints are not supported.