org.cache2k.integration

Class CacheLoader<K,V>

java.lang.Object

org.cache2k.integration.CacheLoader<K,V>

All Implemented Interfaces:

FunctionalCacheLoader<K,V>

public abstract class CacheLoader<K,V>
extends Object
implements FunctionalCacheLoader<K,V>

Retrieves or generates a value to load into the cache. Using a loader to automatically populate the cache is called read through caching. If the cache is primarily used the cache data that is expensive to generate or retrieve, using a CacheLoader has several advantages. The usable features with a loader are explained in the following.

Transparent operation: If configured, the loader is invoked implicitly, in case there is no value in the cache or it is expired, by the cache methods get(), getAll() or getEntry() as well as MutableCacheEntry.getValue().

The cache loader can be invoked explicitly via Cache.reloadAll(Iterable, CacheOperationCompletionListener).

Blocking: If the loader is invoked by Cache.get(K) or other methods that allow transparent access (see above) concurrent requests on the same key will block until the loading is completed. For expired values blocking can be avoided by enabling Cache2kBuilder.refreshAhead(boolean). There is no guarantee that the loader is invoked only for one key at a time. For example, after Cache.clear() is called load operations for one key may overlap.

Prefetching: The method Cache.prefetch(Object) can be used to instruct the cache to load multiple values in the background.

Refresh ahead: By enabling Cache2kBuilder.refreshAhead(boolean) the cache will call the loader when an entry is expired, eagerly trying to keep the cache contents fresh.

The alternative loader interface AdvancedCacheLoader provides the loader with the current cache value.

The functional loader interface can be used if only a single method should be provided or with Java 8 lambdas or method references.

Author:

Jens Wilke

See Also:

AdvancedCacheLoader

Constructor Summary

Constructors

Constructor and Description
CacheLoader()

Method Summary

Modifier and Type	Method and Description
abstract V	load(K key) Retrieves or generates data based on the key.
Map<K,V>	loadAll(Iterable<? extends K> keys, Executor executor) Loads multiple values to the cache.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CacheLoader

public CacheLoader()

Method Detail

load

public abstract V load(K key)
                throws Exception

Retrieves or generates data based on the key.

From inside this method it is illegal to call methods on the same cache. This may cause a deadlock.

API rationale: This method declares an exception to allow any unhandled exceptions of the loader implementation to just pass through. Since the cache needs to catch an deal with loader exceptions in any way, this saves otherwise necessary try/catch clauses in the loader.

Specified by:

load in interface FunctionalCacheLoader<K,V>

Parameters:

key - the non-null key to provide the value for.

Returns:

value to be associated with the key. If the cache does not permit null values a NullPointerException is thrown, but the expiry policy is called before it.

Throws:

Exception - Unhandled exception from the loader. Exceptions are suppressed or wrapped and rethrown via a CacheLoaderException

See Also:

load(Object)

loadAll

public Map<K,V> loadAll(Iterable<? extends K> keys,
                        Executor executor)
                 throws Exception

Loads multiple values to the cache.

From inside this method it is illegal to call methods on the same cache. This may cause a deadlock.

The method is provided to complete the API. At the moment cache2k is not using it. Please see the road map.

Parameters:

keys - set of keys for the values to be loaded

executor - an executor for concurrent loading

Returns:

The loaded values. A key may map to null if the cache permits null values.

Throws:

Exception - Unhandled exception from the loader. Exceptions are suppressed or wrapped and rethrown via a CacheLoaderException. If an exception happens the cache may retry the load with the single value load method.