org.dataloader

Interface ValueCache<K,V>

Type Parameters:

K - the type of cache keys

V - the type of cache values

All Known Implementing Classes:

NoOpValueCache

@PublicSpi
public interface ValueCache<K,V>

The ValueCache is used by data loaders that use caching and want a long-lived or external cache of values. The ValueCache is used as a place to cache values when they come back from

It differs from CacheMap which is in fact a cache of promises to values aka CompletableFuture<V> and it rather suited to be a wrapper of a long lived or external value cache. CompletableFutures cant be easily placed in an external cache outside the JVM say, hence the need for the ValueCache.

DataLoaders use a two stage cache strategy if caching is enabled. If the CacheMap already has the promise to a value that is used. If not then the ValueCache is asked for a value, if it has one then that is returned (and cached as a promise in the CacheMap. If there is no value then the key is queued and loaded via the BatchLoader calls. The returned values will then be stored in the ValueCache and the promises to those values are also stored in the CacheMap.

The default implementation is a no-op store which replies with the key always missing and doesn't store any actual results. This is to avoid duplicating the stored data between the CacheMap out of the box.

The API signature uses completable futures because the backing implementation MAY be a remote external cache and hence exceptions may happen in retrieving values.

Method Summary

Modifier and Type	Method and Description
java.util.concurrent.CompletableFuture<java.lang.Void>	clear() Clears all entries from the store.
static <K,V> ValueCache<K,V>	defaultValueCache() Creates a new value cache, using the default no-op implementation.
java.util.concurrent.CompletableFuture<java.lang.Void>	delete(K key) Deletes the entry with the specified key from the store, if it exists.
java.util.concurrent.CompletableFuture<V>	get(K key) Gets the specified key from the store.
java.util.concurrent.CompletableFuture<V>	set(K key, V value) Stores the value with the specified key, or updates it if the key already exists.

Method Detail

defaultValueCache

static <K,V> ValueCache<K,V> defaultValueCache()

Creates a new value cache, using the default no-op implementation.

Type Parameters:

K - the type of cache keys

V - the type of cache values

Returns:

the cache store

get

java.util.concurrent.CompletableFuture<V> get(K key)

Gets the specified key from the store. if the key si not present, then the implementation MUST return an exceptionally completed future and not null because null is a valid cacheable value. Any exception is will cause DataLoader to load the key via batch loading instead.

Parameters:

key - the key to retrieve

Returns:

a future containing the cached value (which maybe null) or exceptionally completed future if the key does not exist in the cache.

set

java.util.concurrent.CompletableFuture<V> set(K key,
                                              V value)

Stores the value with the specified key, or updates it if the key already exists.

Parameters:

key - the key to store

value - the value to store

Returns:

a future containing the stored value for fluent composition

delete

java.util.concurrent.CompletableFuture<java.lang.Void> delete(K key)

Deletes the entry with the specified key from the store, if it exists.

Parameters:

key - the key to delete

Returns:

a void future for error handling and fluent composition

clear

java.util.concurrent.CompletableFuture<java.lang.Void> clear()

Clears all entries from the store.

Returns:

a void future for error handling and fluent composition