Package org.springframework.cache.caffeine

Class CaffeineCacheManager

java.lang.Object
org.springframework.cache.caffeine.CaffeineCacheManager
All Implemented Interfaces:
CacheManager
public class CaffeineCacheManager extends Object implements CacheManager
CacheManager implementation that lazily builds CaffeineCache instances for each getCache(java.lang.String) request. Also supports a 'static' mode where the set of cache names is pre-defined through setCacheNames(java.util.Collection<java.lang.String>), with no dynamic creation of further cache regions at runtime.

The configuration of the underlying cache can be fine-tuned through a Caffeine builder or CaffeineSpec, passed into this CacheManager through setCaffeine(com.github.benmanes.caffeine.cache.Caffeine<java.lang.Object, java.lang.Object>)/setCaffeineSpec(com.github.benmanes.caffeine.cache.CaffeineSpec). A CaffeineSpec-compliant expression value can also be applied via the "cacheSpecification" bean property.

Supports the asynchronous Cache.retrieve(Object) and Cache.retrieve(Object, Supplier) operations through Caffeine's AsyncCache, when configured via setAsyncCacheMode(boolean), with early-determined cache misses.

Requires Caffeine 3.0 or higher, as of Spring Framework 6.1.

Since:
4.3
Author:
Ben Manes, Juergen Hoeller, Stephane Nicoll, Sam Brannen, Brian Clozel
See Also:

  • Constructor Details

    • CaffeineCacheManager

      public CaffeineCacheManager()
      Construct a dynamic CaffeineCacheManager, lazily creating cache instances as they are being requested.

    • CaffeineCacheManager

      public CaffeineCacheManager(String... cacheNames)
      Construct a static CaffeineCacheManager, managing caches for the specified cache names only.

  • Method Details

    • setCacheNames

      public void setCacheNames(@Nullable Collection<String> cacheNames)
      Specify the set of cache names for this CacheManager's 'static' mode.

      The number of caches and their names will be fixed after a call to this method, with no creation of further cache regions at runtime.

      Calling this with a null collection argument resets the mode to 'dynamic', allowing for further creation of caches again.

    • setCaffeine

      public void setCaffeine(com.github.benmanes.caffeine.cache.Caffeine<Object,Object> caffeine)
      Set the Caffeine to use for building each individual CaffeineCache instance.
      See Also:

    • setCaffeineSpec

      public void setCaffeineSpec(com.github.benmanes.caffeine.cache.CaffeineSpec caffeineSpec)
      Set the CaffeineSpec to use for building each individual CaffeineCache instance.
      See Also:

    • setCacheSpecification

      public void setCacheSpecification(String cacheSpecification)
      Set the Caffeine cache specification String to use for building each individual CaffeineCache instance. The given value needs to comply with Caffeine's CaffeineSpec (see its javadoc).
      See Also:

    • setCacheLoader

      public void setCacheLoader(com.github.benmanes.caffeine.cache.CacheLoader<Object,Object> cacheLoader)
      Set the Caffeine CacheLoader to use for building each individual CaffeineCache instance, turning it into a LoadingCache.
      See Also:

    • setAsyncCacheLoader

      public void setAsyncCacheLoader(com.github.benmanes.caffeine.cache.AsyncCacheLoader<Object,Object> cacheLoader)
      Set the Caffeine AsyncCacheLoader to use for building each individual CaffeineCache instance, turning it into a LoadingCache.

      This implicitly switches the "asyncCacheMode" flag to true.

      Since:
      6.1
      See Also:

    • setAsyncCacheMode

      public void setAsyncCacheMode(boolean asyncCacheMode)
      Set the common cache type that this cache manager builds to async. This applies to setCacheNames(java.util.Collection<java.lang.String>) as well as on-demand caches.

      Individual cache registrations (such as registerCustomCache(String, AsyncCache) and registerCustomCache(String, com.github.benmanes.caffeine.cache.Cache)) are not dependent on this setting.

      By default, this cache manager builds regular native Caffeine caches. To switch to async caches which can also be used through the synchronous API but come with support for Cache#retrieve, set this flag to true.

      Note that while null values in the cache are tolerated in async cache mode, the recommendation is to disallow null values through setAllowNullValues(false). This makes the semantics of CompletableFuture-based access simpler and optimizes retrieval performance since a Caffeine-provided CompletableFuture handle does not have to get wrapped.

      If you come here for the adaptation of reactive types such as a Reactor Mono or Flux onto asynchronous caching, we recommend the standard arrangement for caching the produced values asynchronously in 6.1 through enabling this Caffeine mode. If this is not immediately possible/desirable for existing apps, you may set the system property "spring.cache.reactivestreams.ignore=true" to restore 6.0 behavior where reactive handles are treated as regular values.

      Since:
      6.1
      See Also:

    • setAllowNullValues

      public void setAllowNullValues(boolean allowNullValues)
      Specify whether to accept and convert null values for all caches in this cache manager.

      Default is "true", despite Caffeine itself not supporting null values. An internal holder object will be used to store user-level nulls.

    • isAllowNullValues

      public boolean isAllowNullValues()
      Return whether this cache manager accepts and converts null values for all of its caches.

    • getCacheNames

      public Collection<String> getCacheNames()
      Description copied from interface: CacheManager
      Get a collection of the cache names known by this manager.
      Specified by:
      getCacheNames in interface CacheManager
      Returns:
      the names of all caches known by the cache manager

    • getCache

      @Nullable public Cache getCache(String name)
      Description copied from interface: CacheManager
      Get the cache associated with the given name.

      Note that the cache may be lazily created at runtime if the native provider supports it.

      Specified by:
      getCache in interface CacheManager
      Parameters:
      name - the cache identifier (must not be null)
      Returns:
      the associated cache, or null if such a cache does not exist or could be not created

    • registerCustomCache

      public void registerCustomCache(String name, com.github.benmanes.caffeine.cache.Cache<Object,Object> cache)
      Register the given native Caffeine Cache instance with this cache manager, adapting it to Spring's cache API for exposure through getCache(java.lang.String). Any number of such custom caches may be registered side by side.

      This allows for custom settings per cache (as opposed to all caches sharing the common settings in the cache manager's configuration) and is typically used with the Caffeine builder API: registerCustomCache("myCache", Caffeine.newBuilder().maximumSize(10).build())

      Note that any other caches, whether statically specified through setCacheNames(java.util.Collection<java.lang.String>) or dynamically built on demand, still operate with the common settings in the cache manager's configuration.

      Parameters:
      name - the name of the cache
      cache - the custom Caffeine Cache instance to register
      Since:
      5.2.8
      See Also:

    • registerCustomCache

      public void registerCustomCache(String name, com.github.benmanes.caffeine.cache.AsyncCache<Object,Object> cache)
      Register the given Caffeine AsyncCache instance with this cache manager, adapting it to Spring's cache API for exposure through getCache(java.lang.String). Any number of such custom caches may be registered side by side.

      This allows for custom settings per cache (as opposed to all caches sharing the common settings in the cache manager's configuration) and is typically used with the Caffeine builder API: registerCustomCache("myCache", Caffeine.newBuilder().maximumSize(10).buildAsync())

      Note that any other caches, whether statically specified through setCacheNames(java.util.Collection<java.lang.String>) or dynamically built on demand, still operate with the common settings in the cache manager's configuration.

      Parameters:
      name - the name of the cache
      cache - the custom Caffeine AsyncCache instance to register
      Since:
      6.1
      See Also:

    • adaptCaffeineCache

      protected Cache adaptCaffeineCache(String name, com.github.benmanes.caffeine.cache.Cache<Object,Object> cache)
      Adapt the given new native Caffeine Cache instance to Spring's Cache abstraction for the specified cache name.
      Parameters:
      name - the name of the cache
      cache - the native Caffeine Cache instance
      Returns:
      the Spring CaffeineCache adapter (or a decorator thereof)
      Since:
      5.2.8
      See Also:

    • adaptCaffeineCache

      protected Cache adaptCaffeineCache(String name, com.github.benmanes.caffeine.cache.AsyncCache<Object,Object> cache)
      Adapt the given new Caffeine AsyncCache instance to Spring's Cache abstraction for the specified cache name.
      Parameters:
      name - the name of the cache
      cache - the Caffeine AsyncCache instance
      Returns:
      the Spring CaffeineCache adapter (or a decorator thereof)
      Since:
      6.1
      See Also:

    • createCaffeineCache

      protected Cache createCaffeineCache(String name)
      Build a common CaffeineCache instance for the specified cache name, using the common Caffeine configuration specified on this cache manager.

      Delegates to adaptCaffeineCache(java.lang.String, com.github.benmanes.caffeine.cache.Cache<java.lang.Object, java.lang.Object>) as the adaptation method to Spring's cache abstraction (allowing for centralized decoration etc.), passing in a freshly built native Caffeine Cache instance.

      Parameters:
      name - the name of the cache
      Returns:
      the Spring CaffeineCache adapter (or a decorator thereof)
      See Also:

    • createNativeCaffeineCache

      protected com.github.benmanes.caffeine.cache.Cache<Object,Object> createNativeCaffeineCache(String name)
      Build a common Caffeine Cache instance for the specified cache name, using the common Caffeine configuration specified on this cache manager.
      Parameters:
      name - the name of the cache
      Returns:
      the native Caffeine Cache instance
      See Also:

    • createAsyncCaffeineCache

      protected com.github.benmanes.caffeine.cache.AsyncCache<Object,Object> createAsyncCaffeineCache(String name)
      Build a common Caffeine AsyncCache instance for the specified cache name, using the common Caffeine configuration specified on this cache manager.
      Parameters:
      name - the name of the cache
      Returns:
      the Caffeine AsyncCache instance
      Since:
      6.1
      See Also: