Package org.cache2k.io

Interface AsyncBulkCacheLoader<K,V>

All Superinterfaces:

AsyncCacheLoader<K,V>, Customization, DataAware<K,V>, DataAwareCustomization<K,V>

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface AsyncBulkCacheLoader<K,V>
extends AsyncCacheLoader<K,V>

Extension of AsyncCacheLoader with bulk load capabilities. Entries with an ongoing load are blocked for other requests and loads until the load is finished.

Semantics: A bulk load is issued when the cache client uses a bulk method to retrieve data, like Cache.loadAll(java.lang.Iterable<? extends K>) or Cache.getAll(java.lang.Iterable<? extends K>). Not all keys that the client requests end up in the load request. In case of Cache.getAll(java.lang.Iterable<? extends K>) mappings that are already present in the cache, will not load again. The cache also may issue partial bulk loads in case requested entries are currently processing (maybe a concurrent load or another cache operation). The bulk load will be started with as many entries that can be accessed and locked as possible. There is no guarantee about atomicity or order how a bulk request is executed.

Deadlock avoidance: When a load operation is in flight the entry is blocked and no other operations take place on that entry. When operating on multiple entries, deadlocks might occur, when one operation is processing and locking one entry and waiting for another entry. To avoid deadlocks, the cache will only wait for one entry when holding no locks on another entry. Practically speaking: The cache will issue a bulk request to as many entries it can lock at once, when that request is completed, it will try again or wait for concurrent processing if no more operations can be started.

Rationale: Other cache products and JCache/JSR107 defines a loadAll(java.util.Set<K>, org.cache2k.io.AsyncBulkCacheLoader.BulkLoadContext<K, V>, org.cache2k.io.AsyncBulkCacheLoader.BulkCallback<K, V>) on the same interface as the cache loader. The JCache variant does not work as functional interface because both methods have to be implemented. Other caches implement loadAll(java.util.Set<K>, org.cache2k.io.AsyncBulkCacheLoader.BulkLoadContext<K, V>, org.cache2k.io.AsyncBulkCacheLoader.BulkCallback<K, V>) as iteration over CacheLoader.load(Object) by default. With a separate interface the cache "knows" whether bulk operations can be optimized, and it is possible to be implemented as lambda function as well.

Author:

Jens Wilke

See Also:

BulkCacheLoader

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	AsyncBulkCacheLoader.BulkCallback<K,V>
static interface	AsyncBulkCacheLoader.BulkLoadContext<K,V>

Nested classes/interfaces inherited from interface org.cache2k.io.AsyncCacheLoader

AsyncCacheLoader.Callback<V>, AsyncCacheLoader.Context<K,V>

Method Summary

Modifier and Type	Method	Description
default void	load(K key, AsyncCacheLoader.Context<K,V> context, AsyncCacheLoader.Callback<V> callback)	By default loads a single value via loadAll(java.util.Set<K>, org.cache2k.io.AsyncBulkCacheLoader.BulkLoadContext<K, V>, org.cache2k.io.AsyncBulkCacheLoader.BulkCallback<K, V>).
void	loadAll(Set<K> keys, AsyncBulkCacheLoader.BulkLoadContext<K,V> context, AsyncBulkCacheLoader.BulkCallback<K,V> callback)	Load all values referenced by the key set.

Method Detail

loadAll

void loadAll(Set<K> keys,
             AsyncBulkCacheLoader.BulkLoadContext<K,V> context,
             AsyncBulkCacheLoader.BulkCallback<K,V> callback)
      throws Exception

Load all values referenced by the key set. This method is used to load more efficiently in case the cache client uses Cache.loadAll(Iterable) or Cache.getAll(Iterable).

Parameters:

keys - the keys to load

context - context of this request with additional information. Also contains per key context with current entry values, if present.

callback - Callback to post results

Throws:

Exception - An exception, if the load operation cannot be started. The exception will be assigned to every requested key depending on the resilience policy.

load

default void load(K key,
                  AsyncCacheLoader.Context<K,V> context,
                  AsyncCacheLoader.Callback<V> callback)
           throws Exception

By default loads a single value via loadAll(java.util.Set<K>, org.cache2k.io.AsyncBulkCacheLoader.BulkLoadContext<K, V>, org.cache2k.io.AsyncBulkCacheLoader.BulkCallback<K, V>).

Specified by:

load in interface AsyncCacheLoader<K,V>

Parameters:

key - key of the value to load

context - additional context information for the load operation

callback - interface to notify for load completion

Throws:

Exception - an exception, if the load operation cannot be started

See Also:

AsyncCacheLoader.load(K, org.cache2k.io.AsyncCacheLoader.Context<K, V>, org.cache2k.io.AsyncCacheLoader.Callback<V>)