ForwardingLoadingCache
Date: 2016-05-24

com.google.common.cache

## Class ForwardingLoadingCache<K,V>

- java.lang.Object
- - com.google.common.collect.ForwardingObject
  - - com.google.common.cache.ForwardingCache<K,V>
    - - com.google.common.cache.ForwardingLoadingCache<K,V>

- All Implemented Interfaces:
    Function<K,V>, Cache<K,V>, LoadingCache<K,V>
  Direct Known Subclasses:
    ForwardingLoadingCache.SimpleForwardingLoadingCache

      public abstract class ForwardingLoadingCache<K,V>
      extends ForwardingCache<K,V>
      implements LoadingCache<K,V>

  A cache which forwards all its method calls to another cache. Subclasses should override one or more methods to modify the behavior of the backing cache as desired per the decorator pattern.

  Note that `get(K)`, `getUnchecked(K)`, and `apply(K)` all expose the same underlying functionality, so should probably be overridden as a group.

  Since:
    11.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ForwardingLoadingCache.SimpleForwardingLoadingCache<K,V>` A simplified version of `ForwardingLoadingCache` where subclasses can pass in an already constructed `LoadingCache` as the delegate.

    - ### Nested classes/interfaces inherited from class com.google.common.cache.ForwardingCache

      `ForwardingCache.SimpleForwardingCache<K,V>`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `V` | `apply(K key)` Returns the result of applying this function to `input`.
    `protected abstract LoadingCache<K,V>` | `delegate()` Returns the backing delegate instance that methods are forwarded to.
    `V` | `get(K key)` Returns the value associated with `key` in this cache, first loading that value if necessary.
    `ImmutableMap<K,V>` | `getAll(java.lang.Iterable<? extends K> keys)` Returns a map of the values associated with `keys`, creating or retrieving those values if necessary.
    `V` | `getUnchecked(K key)` Returns the value associated with `key` in this cache, first loading that value if necessary.
    `void` | `refresh(K key)` Loads a new value for key `key`, possibly asynchronously.

    - ### Methods inherited from class com.google.common.cache.ForwardingCache

      `asMap, cleanUp, get, getAllPresent, getIfPresent, invalidate, invalidateAll, invalidateAll, put, putAll, size, stats`

    - ### Methods inherited from class com.google.common.collect.ForwardingObject

      `toString`

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

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

    - ### Methods inherited from interface com.google.common.cache.LoadingCache

      `asMap`

    - ### Methods inherited from interface com.google.common.cache.Cache

      `cleanUp, get, getAllPresent, getIfPresent, invalidate, invalidateAll, invalidateAll, put, putAll, size, stats`

    - ### Methods inherited from interface com.google.common.base.Function

      `equals`

- - ### Constructor Detail

    - #### ForwardingLoadingCache

          protected ForwardingLoadingCache()

      Constructor for use by subclasses.

  - ### Method Detail

    - #### delegate

          protected abstract LoadingCache<K,V> delegate()

      Description copied from class: `ForwardingObject`
      Returns the backing delegate instance that methods are forwarded to. Abstract subclasses generally override this method with an abstract method that has a more specific return type, such as `ForwardingSet.delegate()`. Concrete subclasses override this method to supply the instance being decorated.
      Specified by:
        `delegate` in class `ForwardingCache<K,V>`

    - #### get

          public V get(K key)
                throws java.util.concurrent.ExecutionException

      Description copied from interface: `LoadingCache`
      Returns the value associated with `key` in this cache, first loading that value if necessary. No observable state associated with this cache is modified until loading completes.

      If another call to `LoadingCache.get(K)` or `LoadingCache.getUnchecked(K)` is currently loading the value for `key`, simply waits for that thread to finish and returns its loaded value. Note that multiple threads can concurrently load values for distinct keys.

      Caches loaded by a `CacheLoader` will call `CacheLoader.load(K)` to load new values into the cache. Newly loaded values are added to the cache using `Cache.asMap().putIfAbsent` after loading has completed; if another value was associated with `key` while the new value was loading then a removal notification will be sent for the new value.

      If the cache loader associated with this cache is known not to throw checked exceptions, then prefer `LoadingCache.getUnchecked(K)` over this method.

      Specified by:
        `get` in interface `LoadingCache<K,V>`
      Throws:
        `java.util.concurrent.ExecutionException` - if a checked exception was thrown while loading the value. (`ExecutionException` is thrown even if computation was interrupted by an `InterruptedException`.)

    - #### getUnchecked

          public V getUnchecked(K key)

      Description copied from interface: `LoadingCache`
      Returns the value associated with `key` in this cache, first loading that value if necessary. No observable state associated with this cache is modified until loading completes. Unlike `LoadingCache.get(K)`, this method does not throw a checked exception, and thus should only be used in situations where checked exceptions are not thrown by the cache loader.

      If another call to `LoadingCache.get(K)` or `LoadingCache.getUnchecked(K)` is currently loading the value for `key`, simply waits for that thread to finish and returns its loaded value. Note that multiple threads can concurrently load values for distinct keys.

      Caches loaded by a `CacheLoader` will call `CacheLoader.load(K)` to load new values into the cache. Newly loaded values are added to the cache using `Cache.asMap().putIfAbsent` after loading has completed; if another value was associated with `key` while the new value was loading then a removal notification will be sent for the new value.

      Warning: this method silently converts checked exceptions to unchecked exceptions, and should not be used with cache loaders which throw checked exceptions. In such cases use `LoadingCache.get(K)` instead.

      Specified by:
        `getUnchecked` in interface `LoadingCache<K,V>`

    - #### getAll

          public ImmutableMap<K,V> getAll(java.lang.Iterable<? extends K> keys)
                                   throws java.util.concurrent.ExecutionException

      Description copied from interface: `LoadingCache`
      Returns a map of the values associated with `keys`, creating or retrieving those values if necessary. The returned map contains entries that were already cached, combined with newly loaded entries; it will never contain null keys or values.

      Caches loaded by a `CacheLoader` will issue a single request to `CacheLoader.loadAll(java.lang.Iterable<? extends K>)` for all keys which are not already present in the cache. All entries returned by `CacheLoader.loadAll(java.lang.Iterable<? extends K>)` will be stored in the cache, over-writing any previously cached values. This method will throw an exception if `CacheLoader.loadAll(java.lang.Iterable<? extends K>)` returns `null`, returns a map containing null keys or values, or fails to return an entry for each requested key.

      Note that duplicate elements in `keys`, as determined by `Object.equals(java.lang.Object)`, will be ignored.

      Specified by:
        `getAll` in interface `LoadingCache<K,V>`
      Throws:
        `java.util.concurrent.ExecutionException` - if a checked exception was thrown while loading the value. (`ExecutionException` is thrown even if computation was interrupted by an `InterruptedException`.)

    - #### apply

          public V apply(K key)

      Description copied from interface: `Function`
      Returns the result of applying this function to `input`. This method is generally expected, but not absolutely required, to have the following properties:
      - Its execution does not cause any observable side effects.
      - The computation is consistent with equals; that is, `Objects.equal``(a, b)` implies that `Objects.equal(function.apply(a), function.apply(b))`.
      Specified by:
        `apply` in interface `Function<K,V>`
      Specified by:
        `apply` in interface `LoadingCache<K,V>`

    - #### refresh

          public void refresh(K key)

      Description copied from interface: `LoadingCache`
      Loads a new value for key `key`, possibly asynchronously. While the new value is loading the previous value (if any) will continue to be returned by `get(key)` unless it is evicted. If the new value is loaded successfully it will replace the previous value in the cache; if an exception is thrown while refreshing the previous value will remain, and the exception will be logged (using `Logger`) and swallowed.

      Caches loaded by a `CacheLoader` will call `CacheLoader.reload(K, V)` if the cache currently contains a value for `key`, and `CacheLoader.load(K)` otherwise. Loading is asynchronous only if `CacheLoader.reload(K, V)` was overridden with an asynchronous implementation.

      Returns without doing anything if another thread is currently loading the value for `key`. If the cache loader associated with this cache performs refresh asynchronously then this method may return before refresh completes.

      Specified by:
        `refresh` in interface `LoadingCache<K,V>`