Package org.opennms.features.distributed.kvstore.api

Interface KeyValueStore<T>

Type Parameters:

T - the type this store puts/gets

All Known Subinterfaces:

BlobStore, JsonStore

All Known Implementing Classes:

AbstractAsyncKeyValueStore, AbstractKeyValueStore, AbstractPostgresKeyValueStore, CassandraBlobStore, InMemoryMapBlobStore, NoOpBlobStore, NoOpJsonStore, PostgresBlobStore, PostgresJsonStore

public interface KeyValueStore<T>

Abstract representation of a simple key-value store.

Any synchronous calls to this API that fail exceptionally will throw a RuntimeException wrapping the original exception.

Asynchronous calls to this API that fail exceptionally will return their future completed exceptionally with the original exception.

It is up to the client to handle failures (in the form of unchecked exceptions) resulting from calls to this interface. This is particularly important in the case of asynchronous calls as the backing implementation may be overwhelmed depending on the rate in which case the user must implement their own retry logic to handle the futures that have completed exceptionally (in any case where it is not safe to ignore them).

Method Summary

Modifier and Type	Method	Description
void	delete(String key, String context)
CompletableFuture<Void>	deleteAsync(String key, String context)
Map<String,T>	enumerateContext(String context)
CompletableFuture<Map<String,T>>	enumerateContextAsync(String context)
Optional<T>	get(String key, String context)
CompletableFuture<Optional<T>>	getAsync(String key, String context)
Optional<Optional<T>>	getIfStale(String key, String context, long timestamp)
CompletableFuture<Optional<Optional<T>>>	getIfStaleAsync(String key, String context, long timestamp)
OptionalLong	getLastUpdated(String key, String context)
CompletableFuture<OptionalLong>	getLastUpdatedAsync(String key, String context)
String	getName()
long	put(String key, T value, String context)
long	put(String key, T value, String context, Integer ttlInSeconds)	Put a value with a suggested time-to-live after which the value should be expired and removed from the store.
CompletableFuture<Long>	putAsync(String key, T value, String context)
CompletableFuture<Long>	putAsync(String key, T value, String context, Integer ttlInSeconds)	Put a value with a suggested time-to-live after which the value should be expired and removed from the store.
void	truncateContext(String context)	Remove all records for a given context.
CompletableFuture<Void>	truncateContextAsync(String context)	Remove all records for a given context.

Method Detail

put

long put(String key,
         T value,
         String context)

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

Returns:

the timestamp the value was persisted with

put

long put(String key,
         T value,
         String context,
         Integer ttlInSeconds)

Put a value with a suggested time-to-live after which the value should be expired and removed from the store.

Records are expired on a best effort basis and depending on the implementation it is possible to get an expired record.

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

ttlInSeconds - the time to live in seconds for this key or no ttl if null

Returns:

the timestamp the value was persisted with

get

Optional<T> get(String key,
                String context)

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

Returns:

an optional containing the value if present or empty if the key did not exist

getIfStale

Optional<Optional<T>> getIfStale(String key,
                                 String context,
                                 long timestamp)

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

timestamp - the timestamp of the last known state such that if an record with a more recent timestamp is found the provided timestamp will be considered stale and the new record will be returned

Returns:

an optional that will be empty if the key was not found or will contain another optional that will be empty if not stale or contain the value if stale

getLastUpdated

OptionalLong getLastUpdated(String key,
                            String context)

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

Returns:

an optional containing the timestamp the key's value was last updated or empty if the key did not exist

enumerateContext

Map<String,T> enumerateContext(String context)

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

Returns:

a map of all the records matching the given context where the map's key is the record's key and the map's value is the records value

delete

void delete(String key,
            String context)

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

truncateContext

void truncateContext(String context)

Remove all records for a given context.

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

putAsync

CompletableFuture<Long> putAsync(String key,
                                 T value,
                                 String context)

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

Returns:

a future containing the timestamp the value was persisted with

putAsync

CompletableFuture<Long> putAsync(String key,
                                 T value,
                                 String context,
                                 Integer ttlInSeconds)

Put a value with a suggested time-to-live after which the value should be expired and removed from the store.

Records are expired on a best effort basis and depending on the implementation it is possible to get an expired record.

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

ttlInSeconds - the time to live in seconds for this key or no ttl if null

Returns:

a future containing the timestamp the value was persisted with

getAsync

CompletableFuture<Optional<T>> getAsync(String key,
                                        String context)

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

Returns:

a future containing an optional of the value if present or empty if the key did not exist

getIfStaleAsync

CompletableFuture<Optional<Optional<T>>> getIfStaleAsync(String key,
                                                         String context,
                                                         long timestamp)

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

timestamp - the timestamp of the last known state such that if an record with a more recent timestamp is found the provided timestamp will be considered stale and the new record will be returned

Returns:

a future containing an optional that will be empty if the key was not found or will contain another optional that will be empty if not stale or contain the value if stale

getLastUpdatedAsync

CompletableFuture<OptionalLong> getLastUpdatedAsync(String key,
                                                    String context)

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

Returns:

a future containing an optional of the the timestamp the key's value was last updated or empty if the key did not exist

getName

String getName()

Returns:

the name of the backing implementation

enumerateContextAsync

CompletableFuture<Map<String,T>> enumerateContextAsync(String context)

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

Returns:

a future containing a map of all the records matching the given context where the map's key is the record's key and the map's value is the records value

deleteAsync

CompletableFuture<Void> deleteAsync(String key,
                                    String context)

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)

Returns:

a future that is completed when the delete has finished

truncateContextAsync

CompletableFuture<Void> truncateContextAsync(String context)

Remove all records for a given context.

Parameters:

context - a context used to differentiate between keys with the same name (forms a compound key)