org.springframework.cache

## 接口 Cache

- 所有已知实现类:
    AbstractValueAdaptingCache, ConcurrentMapCache, NoOpCache

      public interface Cache

  Interface that defines common cache operations. Note: Due to the generic use of caching, it is recommended that implementations allow storage of `null` values (for example to cache methods that return `null`).
  从以下版本开始:
    3.1
  作者:
    Costin Leau, Juergen Hoeller, Stephane Nicoll

- - ### 嵌套类概要

    嵌套类
    限定符和类型 | 接口和说明
    --- | ---
    `static class` | `Cache.ValueRetrievalException` Wrapper exception to be thrown from `get(Object, Callable)` in case of the value loader callback failing with an exception.
    `static interface` | `Cache.ValueWrapper` A (wrapper) object representing a cache value.

  - ### 方法概要

    所有方法 实例方法 抽象方法
    限定符和类型 | 方法和说明
    --- | ---
    `void` | `clear()` Remove all mappings from the cache.
    `void` | `evict(Object key)` Evict the mapping for this key from this cache if it is present.
    `Cache.ValueWrapper` | `get(Object key)` Return the value to which this cache maps the specified key.
    `<T> T` | `get(Object key, Callable<T> valueLoader)` Return the value to which this cache maps the specified key, obtaining that value from `valueLoader` if necessary.
    `<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.
    `String` | `getName()` Return the cache name.
    `Object` | `getNativeCache()` Return the underlying native cache provider.
    `void` | `put(Object key, Object value)` Associate the specified value with the specified key in this cache.
    `Cache.ValueWrapper` | `putIfAbsent(Object key, Object value)` Atomically associate the specified value with the specified key in this cache if it is not set already.

- - ### 方法详细资料

    - #### getName

          String getName()

      Return the cache name.

    - #### getNativeCache

          Object getNativeCache()

      Return the underlying native cache provider.

    - #### get

          @Nullable
          Cache.ValueWrapper get(Object key)

      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`.

      参数:
        `key` - the key whose associated value is to be returned
      返回:
        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.
      另请参阅:
        `get(Object, Class)`

    - #### get

          @Nullable
          <T> T get(Object key,
                               @Nullable
                               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.

      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 `get(Object)` variant for that purpose instead.

      参数:
        `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)
      返回:
        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
      抛出:
        `IllegalStateException` - if a cache entry has been found but failed to match the specified type
      从以下版本开始:
        4.0
      另请参阅:
        `get(Object)`

    - #### get

          @Nullable
          <T> T get(Object key,
                               Callable<T> valueLoader)

      Return the value to which this cache maps the specified key, obtaining that value from `valueLoader` if necessary. This method provides a simple substitute for the conventional "if cached, return; otherwise create, cache and return" pattern.

      If possible, implementations should ensure that the loading operation is synchronized so that the specified `valueLoader` is only called once in case of concurrent access on the same key.

      If the `valueLoader` throws an exception, it is wrapped in a `Cache.ValueRetrievalException`

      参数:
        `key` - the key whose associated value is to be returned
      返回:
        the value to which this cache maps the specified key
      抛出:
        `Cache.ValueRetrievalException` - if the `valueLoader` throws an exception
      从以下版本开始:
        4.3

    - #### put

          void put(Object key,
                   @Nullable
                   Object value)

      Associate the specified value with the specified key in this cache.

      If the cache previously contained a mapping for this key, the old value is replaced by the specified value.

      参数:
        `key` - the key with which the specified value is to be associated
        `value` - the value to be associated with the specified key

    - #### putIfAbsent

          @Nullable
          Cache.ValueWrapper putIfAbsent(Object key,
                                                    @Nullable
                                                    Object value)

      Atomically associate the specified value with the specified key in this cache if it is not set already.

      This is equivalent to:

           Object existingValue = cache.get(key);
           if (existingValue == null) {
               cache.put(key, value);
               return null;
           } else {
               return existingValue;
           }

      except that the action is performed atomically. While all out-of-the-box `CacheManager` implementations are able to perform the put atomically, the operation may also be implemented in two steps, e.g. with a check for presence and a subsequent put, in a non-atomic way. Check the documentation of the native cache implementation that you are using for more details.
      参数:
        `key` - the key with which the specified value is to be associated
        `value` - the value to be associated with the specified key
      返回:
        the value to which this cache maps the specified key (which may be `null` itself), or also `null` if the cache did not contain any mapping for that key prior to this call. Returning `null` is therefore an indicator that the given `value` has been associated with the key.
      从以下版本开始:
        4.1

    - #### evict

          void evict(Object key)

      Evict the mapping for this key from this cache if it is present.
      参数:
        `key` - the key whose mapping is to be removed from the cache

    - #### clear

          void clear()

      Remove all mappings from the cache.