Package org.springframework.cache.caffeine

# Class CaffeineCacheManager

java.lang.Object
org.springframework.cache.caffeine.CaffeineCacheManager

All Implemented Interfaces:
  `org.springframework.cache.CacheManager`

public class CaffeineCacheManager extends Object implements org.springframework.cache.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:
  - `CaffeineCache`
  - `setCaffeineSpec(com.github.benmanes.caffeine.cache.CaffeineSpec)`
  - `setCacheSpecification(java.lang.String)`
  - `setAsyncCacheMode(boolean)`

## Constructor Summary

Constructors
Constructor
Description
`CaffeineCacheManager()`
Construct a dynamic CaffeineCacheManager, lazily creating cache instances as they are being requested.
`CaffeineCacheManager(String... cacheNames)`
Construct a static CaffeineCacheManager, managing caches for the specified cache names only.

## Method Summary

Modifier and Type
Method
Description
`protected org.springframework.cache.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.
`protected org.springframework.cache.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.
`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.
`protected org.springframework.cache.Cache`
`createCaffeineCache(String name)`
Build a common `CaffeineCache` instance for the specified cache name, using the common Caffeine configuration specified on this cache manager.
`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.
`org.springframework.cache.Cache`
`getCache(String name)`
`Collection<String>`
`getCacheNames()`
`boolean`
`isAllowNullValues()`
Return whether this cache manager accepts and converts `null` values for all of its caches.
`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)`.
`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)`.
`void`
`removeCache(String name)`
Remove the specified cache from this cache manager, applying to custom caches as well as dynamically registered caches at runtime.
`void`
`resetCaches()`
Reset this cache manager's caches, removing them completely for on-demand re-creation in 'dynamic' mode, or simply clearing their entries otherwise.
`void`
`setAllowNullValues(boolean allowNullValues)`
Specify whether to accept and convert `null` values for all caches in this cache manager.
`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.
`void`
`setAsyncCacheMode(boolean asyncCacheMode)`
Set the common cache type that this cache manager builds to async.
`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.
`void`
`setCacheNames(Collection<String> cacheNames)`
Specify the set of cache names for this CacheManager's 'static' mode.
`void`
`setCacheSpecification(String cacheSpecification)`
Set the Caffeine cache specification String to use for building each individual `CaffeineCache` instance.
`void`
`setCaffeine(com.github.benmanes.caffeine.cache.Caffeine<Object,Object> caffeine)`
Set the Caffeine to use for building each individual `CaffeineCache` instance.
`void`
`setCaffeineSpec(com.github.benmanes.caffeine.cache.CaffeineSpec caffeineSpec)`
Set the `CaffeineSpec` to use for building each individual `CaffeineCache` instance.

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

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

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

Note that this method replaces existing caches of the given names and prevents the creation of further cache regions from here on - but does not remove unrelated existing caches. For a full reset, consider calling `resetCaches()` before calling this method.

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

See Also:
  - `resetCaches()`

### 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:
  - `createNativeCaffeineCache(java.lang.String)`
  - `Caffeine.build()`

### setCaffeineSpec

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

See Also:
  - `createNativeCaffeineCache(java.lang.String)`
  - `Caffeine.from(CaffeineSpec)`

### 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:
  - `createNativeCaffeineCache(java.lang.String)`
  - `Caffeine.from(String)`

### 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:
  - `createNativeCaffeineCache(java.lang.String)`
  - `Caffeine.build(CacheLoader)`
  - `LoadingCache`

### 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:
  - `createAsyncCaffeineCache(java.lang.String)`
  - `Caffeine.buildAsync(AsyncCacheLoader)`
  - `LoadingCache`

### 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:
  - `Caffeine.buildAsync()`
  - `Cache.retrieve(Object)`
  - `Cache.retrieve(Object, Supplier)`
  - `CacheAspectSupport.IGNORE_REACTIVESTREAMS_PROPERTY_NAME`

### 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 `null`s.

### isAllowNullValues

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

### getCache

@Nullable public org.springframework.cache.Cache getCache(String name)

Specified by:
  `getCache` in interface `org.springframework.cache.CacheManager`

### getCacheNames

public Collection<String> getCacheNames()

Specified by:
  `getCacheNames` in interface `org.springframework.cache.CacheManager`

### resetCaches

public void resetCaches()
Reset this cache manager's caches, removing them completely for on-demand re-creation in 'dynamic' mode, or simply clearing their entries otherwise.

Since:
  6.2.14

### removeCache

public void removeCache(String name)
Remove the specified cache from this cache manager, applying to custom caches as well as dynamically registered caches at runtime.

Parameters:
  `name` - the name of the cache
Since:
  6.1.15

### 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:
  - `adaptCaffeineCache(String, com.github.benmanes.caffeine.cache.Cache)`

### 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(String, AsyncCache)`

### adaptCaffeineCache

protected org.springframework.cache.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:
  - `CaffeineCache(String, com.github.benmanes.caffeine.cache.Cache, boolean)`
  - `isAllowNullValues()`

### adaptCaffeineCache

protected org.springframework.cache.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:
  - `CaffeineCache(String, AsyncCache, boolean)`
  - `isAllowNullValues()`

### createCaffeineCache

protected org.springframework.cache.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:
  - `adaptCaffeineCache(java.lang.String, com.github.benmanes.caffeine.cache.Cache<java.lang.Object, java.lang.Object>)`
  - `createNativeCaffeineCache(java.lang.String)`

### 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:
  - `createCaffeineCache(java.lang.String)`

### 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:
  - `createCaffeineCache(java.lang.String)`