org.springframework.cache.support

## Class AbstractValueAdaptingCache

- java.lang.Object
- - org.springframework.cache.support.AbstractValueAdaptingCache

- All Implemented Interfaces:
    Cache
  Direct Known Subclasses:
    CaffeineCache, ConcurrentMapCache, JCacheCache

      public abstract class AbstractValueAdaptingCache
      extends Object
      implements Cache

  Common base class for `Cache` implementations that need to adapt `null` values (and potentially other such special values) before passing them on to the underlying store.

  Transparently replaces given `null` user values with an internal `NullValue.INSTANCE`, if configured to support `null` values (as indicated by `isAllowNullValues()`).

  Since:
    4.2.2
  Author:
    Juergen Hoeller

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.springframework.cache.Cache

      `Cache.ValueRetrievalException, Cache.ValueWrapper`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractValueAdaptingCache(boolean allowNullValues)` Create an `AbstractValueAdaptingCache` with the given setting.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Object` | `fromStoreValue(Object storeValue)` Convert the given value from the internal store to a user value returned from the get method (adapting `null`).
    `Cache.ValueWrapper` | `get(Object key)` Return the value to which this cache maps the specified key.
    `<T> T` | `get(Object key, Class<T> type)` Return the value to which this cache maps the specified key, generically specifying a type that return value will be cast to.
    `boolean` | `isAllowNullValues()` Return whether `null` values are allowed in this cache.
    `protected abstract Object` | `lookup(Object key)` Perform an actual lookup in the underlying store.
    `protected Object` | `toStoreValue(Object userValue)` Convert the given user value, as passed into the put method, to a value in the internal store (adapting `null`).
    `protected Cache.ValueWrapper` | `toValueWrapper(Object storeValue)` Wrap the given store value with a `SimpleValueWrapper`, also going through `fromStoreValue(java.lang.Object)` conversion.

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

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

    - ### Methods inherited from interface org.springframework.cache.Cache

      `clear, evict, evictIfPresent, get, getName, getNativeCache, invalidate, put, putIfAbsent`

- - ### Constructor Detail

    - #### AbstractValueAdaptingCache

          protected AbstractValueAdaptingCache(boolean allowNullValues)

      Create an `AbstractValueAdaptingCache` with the given setting.
      Parameters:
        `allowNullValues` - whether to allow for `null` values

  - ### Method Detail

    - #### isAllowNullValues

          public final boolean isAllowNullValues()

      Return whether `null` values are allowed in this cache.

    - #### get

          @Nullable
          public Cache.ValueWrapper get(Object key)

      Description copied from interface: `Cache`
      Return the value to which this cache maps the specified key.

      Returns `null` if the cache contains no mapping for this key; otherwise, the cached value (which may be `null` itself) will be returned in a `Cache.ValueWrapper`.

      Specified by:
        `get` in interface `Cache`
      Parameters:
        `key` - the key whose associated value is to be returned
      Returns:
        the value to which this cache maps the specified key, contained within a `Cache.ValueWrapper` which may also hold a cached `null` value. A straight `null` being returned means that the cache contains no mapping for this key.
      See Also:
        `Cache.get(Object, Class)`, `Cache.get(Object, Callable)`

    - #### get

          @Nullable
          public <T> T get(Object key,
                                     @Nullable
                                     Class<T> type)

      Description copied from interface: `Cache`
      Return the value to which this cache maps the specified key, generically specifying a type that return value will be cast to.

      Note: This variant of `get` does not allow for differentiating between a cached `null` value and no cache entry found at all. Use the standard `Cache.get(Object)` variant for that purpose instead.

      Specified by:
        `get` in interface `Cache`
      Parameters:
        `key` - the key whose associated value is to be returned
        `type` - the required type of the returned value (may be `null` to bypass a type check; in case of a `null` value found in the cache, the specified type is irrelevant)
      Returns:
        the value to which this cache maps the specified key (which may be `null` itself), or also `null` if the cache contains no mapping for this key
      See Also:
        `Cache.get(Object)`

    - #### lookup

          @Nullable
          protected abstract Object lookup(Object key)

      Perform an actual lookup in the underlying store.
      Parameters:
        `key` - the key whose associated value is to be returned
      Returns:
        the raw store value for the key, or `null` if none

    - #### fromStoreValue

          @Nullable
          protected Object fromStoreValue(@Nullable
                                                    Object storeValue)

      Convert the given value from the internal store to a user value returned from the get method (adapting `null`).
      Parameters:
        `storeValue` - the store value
      Returns:
        the value to return to the user

    - #### toStoreValue

          protected Object toStoreValue(@Nullable
                                        Object userValue)

      Convert the given user value, as passed into the put method, to a value in the internal store (adapting `null`).
      Parameters:
        `userValue` - the given user value
      Returns:
        the value to store

    - #### toValueWrapper

          @Nullable
          protected Cache.ValueWrapper toValueWrapper(@Nullable
                                                                Object storeValue)

      Wrap the given store value with a `SimpleValueWrapper`, also going through `fromStoreValue(java.lang.Object)` conversion. Useful for `get(Object)` and `Cache.putIfAbsent(Object, Object)` implementations.
      Parameters:
        `storeValue` - the original value
      Returns:
        the wrapped value