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.

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.
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).

Method Detail

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.