Interface CacheLoader<K,V>

All Superinterfaces:
AsyncCacheLoader<K,V>
All Known Implementing Classes:
BoundedLocalCache.BoundedLocalAsyncLoadingCache.AsyncLoader, CaffeinatedGuavaLoadingCache.BulkLoader, CaffeinatedGuavaLoadingCache.SingleLoader, JCacheLoaderAdapter
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 CacheLoader<K,V> extends AsyncCacheLoader<K,V>
Computes or retrieves values, based on a key, for use in populating a LoadingCache or AsyncLoadingCache.

Most implementations will only need to implement load(K). Other methods may be overridden as desired.

Usage example: 

  CacheLoader<Key, Graph> loader = key -> createExpensiveGraph(key);
  LoadingCache<Key, Graph> cache = Caffeine.newBuilder().build(loader);

  • Method Summary

    Modifier and Type
    Method
    Description
    default @NonNull CompletableFuture<V>
    asyncLoad(@NonNull K key, @NonNull Executor executor)
    Asynchronously computes or retrieves the value corresponding to key.
    default @NonNull CompletableFuture<Map<@NonNull K, @NonNull V>>
    asyncLoadAll(@NonNull Iterable<? extends K> keys, @NonNull Executor executor)
    Asynchronously computes or retrieves the values corresponding to keys.
    default @NonNull CompletableFuture<V>
    asyncReload(@NonNull K key, @NonNull V oldValue, @NonNull Executor executor)
    Asynchronously computes or retrieves a replacement value corresponding to an already-cached key.
    @Nullable V
    load(@NonNull K key)
    Computes or retrieves the value corresponding to key.
    default @NonNull Map<@NonNull K, @NonNull V>
    loadAll(@NonNull Iterable<? extends @NonNull K> keys)
    Computes or retrieves the values corresponding to keys.
    default @Nullable V
    reload(@NonNull K key, @NonNull V oldValue)
    Computes or retrieves a replacement value corresponding to an already-cached key.

  • Method Details

    • load

      @Nullable V load(@NonNull K key) throws Exception
      Computes or retrieves the value corresponding to key.

      Warning: loading must not attempt to update any mappings of this cache directly.

      Parameters:
      key - the non-null key whose value should be loaded
      Returns:
      the value associated with key or null if not found
      Throws:
      Exception - or Error, in which case the mapping is unchanged
      InterruptedException - if this method is interrupted. InterruptedException is treated like any other Exception in all respects except that, when it is caught, the thread's interrupt status is set

    • loadAll

      default @NonNull Map<@NonNull K, @NonNull V> loadAll(@NonNull Iterable<? extends @NonNull K> keys) throws Exception
      Computes or retrieves the values corresponding to keys. This method is called by LoadingCache.getAll(Iterable).

      If the returned map doesn't contain all requested keys then the entries it does contain will be cached and getAll will return the partial results. If the returned map contains extra keys not present in keys then all returned entries will be cached, but only the entries for keys will be returned from getAll.

      This method should be overridden when bulk retrieval is significantly more efficient than many individual lookups. Note that LoadingCache.getAll(Iterable) will defer to individual calls to LoadingCache.get(K) if this method is not overridden.

      Warning: loading must not attempt to update any mappings of this cache directly.

      Parameters:
      keys - the unique, non-null keys whose values should be loaded
      Returns:
      a map from each key in keys to the value associated with that key; may not contain null values
      Throws:
      Exception - or Error, in which case the mappings are unchanged
      InterruptedException - if this method is interrupted. InterruptedException is treated like any other Exception in all respects except that, when it is caught, the thread's interrupt status is set

    • asyncLoad

      default @NonNull CompletableFuture<V> asyncLoad(@NonNull K key, @NonNull Executor executor)
      Asynchronously computes or retrieves the value corresponding to key.
      Specified by:
      asyncLoad in interface AsyncCacheLoader<K,V>
      Parameters:
      key - the non-null key whose value should be loaded
      executor - the executor that asynchronously loads the entry
      Returns:
      the future value associated with key

    • asyncLoadAll

      default @NonNull CompletableFuture<Map<@NonNull K, @NonNull V>> asyncLoadAll(@NonNull Iterable<? extends K> keys, @NonNull Executor executor)
      Asynchronously computes or retrieves the values corresponding to keys. This method is called by AsyncLoadingCache.getAll(Iterable).

      If the returned map doesn't contain all requested keys then the entries it does contain will be cached and getAll will return the partial results. If the returned map contains extra keys not present in keys then all returned entries will be cached, but only the entries for keys will be returned from getAll.

      This method should be overridden when bulk retrieval is significantly more efficient than many individual lookups. Note that AsyncLoadingCache.getAll(Iterable) will defer to individual calls to AsyncLoadingCache.get(K) if this method is not overridden.

      Specified by:
      asyncLoadAll in interface AsyncCacheLoader<K,V>
      Parameters:
      keys - the unique, non-null keys whose values should be loaded
      executor - the executor that with asynchronously loads the entries
      Returns:
      a future containing the map from each key in keys to the value associated with that key; may not contain null values

    • reload

      default @Nullable V reload(@NonNull K key, @NonNull V oldValue) throws Exception
      Computes or retrieves a replacement value corresponding to an already-cached key. If the replacement value is not found then the mapping will be removed if null is returned. This method is called when an existing cache entry is refreshed by Caffeine.refreshAfterWrite(Duration), or through a call to LoadingCache.refresh(K).

      Note: all exceptions thrown by this method will be logged and then swallowed.

      Parameters:
      key - the non-null key whose value should be loaded
      oldValue - the non-null old value corresponding to key
      Returns:
      the new value associated with key, or null if the mapping is to be removed
      Throws:
      Exception - or Error, in which case the mapping is unchanged
      InterruptedException - if this method is interrupted. InterruptedException is treated like any other Exception in all respects except that, when it is caught, the thread's interrupt status is set

    • asyncReload

      default @NonNull CompletableFuture<V> asyncReload(@NonNull K key, @NonNull V oldValue, @NonNull Executor executor)
      Asynchronously computes or retrieves a replacement value corresponding to an already-cached key. If the replacement value is not found then the mapping will be removed if null is computed. This method is called when an existing cache entry is refreshed by Caffeine.refreshAfterWrite(Duration), or through a call to LoadingCache.refresh(K).

      Note: all exceptions thrown by this method will be logged and then swallowed.

      Specified by:
      asyncReload in interface AsyncCacheLoader<K,V>
      Parameters:
      key - the non-null key whose value should be loaded
      oldValue - the non-null old value corresponding to key
      executor - the executor with which the entry is asynchronously loaded
      Returns:
      a future containing the new value associated with key, or containing null if the mapping is to be removed