CacheLoader
Date: 2016-05-24

com.google.common.cache

## Class CacheLoader<K,V>

- java.lang.Object
- - com.google.common.cache.CacheLoader<K,V>

-     @GwtCompatible(emulated=true)
      public abstract class CacheLoader<K,V>
      extends java.lang.Object

  Computes or retrieves values, based on a key, for use in populating a `LoadingCache`.

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

  Usage example:

         CacheLoader<Key, Graph> loader = new CacheLoader<Key, Graph>() {
           public Graph load(Key key) throws AnyException {
             return createExpensiveGraph(key);
           }
         };
         LoadingCache<Key, Graph> cache = CacheBuilder.newBuilder().build(loader);

  Since:
    10.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `CacheLoader.InvalidCacheLoadException` Thrown to indicate that an invalid response was returned from a call to `CacheLoader`.
    `static class` | `CacheLoader.UnsupportedLoadingOperationException` Exception thrown by `loadAll()` to indicate that it is not supported.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `CacheLoader()` Constructor for use by subclasses.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <K,V> CacheLoader<K,V>` | `asyncReloading(CacheLoader<K,V> loader, java.util.concurrent.Executor executor)` Returns a `CacheLoader` which wraps `loader`, executing calls to `reload(K, V)` using `executor`.
    `static <K,V> CacheLoader<K,V>` | `from(Function<K,V> function)` Returns a cache loader based on an existing function instance.
    `static <V> CacheLoader<java.lang.Object,V>` | `from(Supplier<V> supplier)` Returns a cache loader based on an existing supplier instance.
    `abstract V` | `load(K key)` Computes or retrieves the value corresponding to `key`.
    `java.util.Map<K,V>` | `loadAll(java.lang.Iterable<? extends K> keys)` Computes or retrieves the values corresponding to `keys`.
    `ListenableFuture<V>` | `reload(K key, V oldValue)` Computes or retrieves a replacement value corresponding to an already-cached `key`.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### CacheLoader

          protected CacheLoader()

      Constructor for use by subclasses.

  - ### Method Detail

    - #### load

          public abstract V load(K key)
                          throws java.lang.Exception

      Computes or retrieves the value corresponding to `key`.
      Parameters:
        `key` - the non-null key whose value should be loaded
      Returns:
        the value associated with `key`; must not be null
      Throws:
        `java.lang.Exception` - if unable to load the result
        `java.lang.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

    - #### reload

          @GwtIncompatible(value="Futures")
          public ListenableFuture<V> reload(K key,
                                                        V oldValue)
                                     throws java.lang.Exception

      Computes or retrieves a replacement value corresponding to an already-cached `key`. This method is called when an existing cache entry is refreshed by `CacheBuilder.refreshAfterWrite(long, java.util.concurrent.TimeUnit)`, or through a call to `LoadingCache.refresh(K)`.

      This implementation synchronously delegates to `load(K)`. It is recommended that it be overridden with an asynchronous implementation when using `CacheBuilder.refreshAfterWrite(long, java.util.concurrent.TimeUnit)`.

      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 future new value associated with `key`; must not be null, must not return null
      Throws:
        `java.lang.Exception` - if unable to reload the result
        `java.lang.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
      Since:
        11.0

    - #### loadAll

          public java.util.Map<K,V> loadAll(java.lang.Iterable<? extends K> keys)
                                     throws java.lang.Exception

      Computes or retrieves the values corresponding to `keys`. This method is called by `LoadingCache.getAll(java.lang.Iterable<? extends K>)`.

      If the returned map doesn't contain all requested `keys` then the entries it does contain will be cached, but `getAll` will throw an exception. 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 overriden when bulk retrieval is significantly more efficient than many individual lookups. Note that `LoadingCache.getAll(java.lang.Iterable<? extends K>)` will defer to individual calls to `LoadingCache.get(K)` if this method is not overriden.

      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:
        `java.lang.Exception` - if unable to load the result
        `java.lang.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
      Since:
        11.0

    - #### from

          public static <K,V> CacheLoader<K,V> from(Function<K,V> function)

      Returns a cache loader based on an existing function instance. Note that there's no need to create a new function just to pass it in here; just subclass `CacheLoader` and implement `load` instead.
      Parameters:
        `function` - the function to be used for loading values; must never return `null`
      Returns:
        a cache loader that loads values by passing each key to `function`

    - #### from

          public static <V> CacheLoader<java.lang.Object,V> from(Supplier<V> supplier)

      Returns a cache loader based on an existing supplier instance. Note that there's no need to create a new supplier just to pass it in here; just subclass `CacheLoader` and implement `load` instead.
      Parameters:
        `supplier` - the supplier to be used for loading values; must never return `null`
      Returns:
        a cache loader that loads values by calling `Supplier.get()`, irrespective of the key

    - #### asyncReloading

          @GwtIncompatible(value="Executor + Futures")
          public static <K,V> CacheLoader<K,V> asyncReloading(CacheLoader<K,V> loader,
                                                                   java.util.concurrent.Executor executor)

      Returns a `CacheLoader` which wraps `loader`, executing calls to `reload(K, V)` using `executor`.

      This method is useful only when `loader.reload` has a synchronous implementation, such as the default implementation.

      Since:
        17.0