31.1 Supported cache providers
The cache abstraction does not provide an actual store and relies on abstraction materialized by the org.springframework.cache.Cache
and org.springframework.cache.CacheManager
interfaces. Spring Boot auto-configures a suitable CacheManager
according to the implementation as long as the caching support is enabled via the @EnableCaching
annotation.
Note | |
---|---|
If you are using the cache infrastructure with beans that are not interface-based, make sure to enable the proxyTargetClass attribute of @EnableCaching . |
Tip | |
---|---|
Use the spring-boot-starter-cache ‘Starter’ to quickly add required caching dependencies. If you are adding dependencies manually you should note that certain implementations are only provided by the spring-context-support jar. |
If you haven’t defined a bean of type CacheManager
or a CacheResolver
named cacheResolver
(see CachingConfigurer
), Spring Boot tries to detect the following providers (in this order):
- Generic
- JCache (JSR-107) (EhCache 3, Hazelcast, Infinispan, etc)
- EhCache 2.x
- Hazelcast
- Infinispan
- Couchbase
- Redis
- Caffeine
- Guava
- Simple
Tip | |
---|---|
It is also possible to force the cache provider to use via the spring.cache.type property. Use this property if you need to disable caching altogether in certain environment (e.g. tests). |
If the CacheManager
is auto-configured by Spring Boot, you can further tune its configuration before it is fully initialized by exposing a bean implementing the CacheManagerCustomizer
interface. The following sets the cache names to use.
_@Bean_ public CacheManagerCustomizer<ConcurrentMapCacheManager> cacheManagerCustomizer() { return new CacheManagerCustomizer<ConcurrentMapCacheManager>() { _@Override_ public void customize(ConcurrentMapCacheManager cacheManager) { cacheManager.setCacheNames(Arrays.asList("one", "two")); } }; }
Note | |
---|---|
In the example above, a ConcurrentMapCacheManager is expected to be configured. If that is not the case, the customizer won’t be invoked at all. You can have as many customizers as you want and you can also order them as usual using @Order or Ordered . |
31.1.1 Generic
Generic caching is used if the context defines at least one org.springframework.cache.Cache
bean, a CacheManager
wrapping them is configured.
31.1.2 JCache (JSR-107)
JCache is bootstrapped via the presence of a javax.cache.spi.CachingProvider
on the classpath (i.e. a JSR-107 compliant caching library). There are various compliant libraries out there and Spring Boot provides dependency management for Ehcache 3, Hazelcast and Infinispan). Any other compliant library can be added as well.
It might happen that more than one provider is present, in which case the provider must be explicitly specified. Even if the JSR-107 standard does not enforce a standardized way to define the location of the configuration file, Spring Boot does its best to accommodate with implementation details.
# Only necessary if more than one provider is present spring.cache.jcache.provider=com.acme.MyCachingProvider spring.cache.jcache.config=classpath:acme.xml
Note | |
---|---|
Since a cache library may offer both a native implementation and JSR-107 support Spring Boot will prefer the JSR-107 support so that the same features are available if you switch to a different JSR-107 implementation. |
There are several ways to customize the underlying javax.cache.cacheManager
:
- Caches can be created on startup via the
spring.cache.cache-names
property. If a customjavax.cache.configuration.Configuration
bean is defined, it is used to customize them. org.springframework.boot.autoconfigure.cache.JCacheManagerCustomizer
beans are invoked with the reference of theCacheManager
for full customization.
Tip | |
---|---|
If a standard javax.cache.CacheManager bean is defined, it is wrapped automatically in a org.springframework.cache.CacheManager implementation that the abstraction expects. No further customization is applied on it. |
31.1.3 EhCache 2.x
EhCache 2.x is used if a file named ehcache.xml
can be found at the root of the classpath. If EhCache 2.x and such file is present it is used to bootstrap the cache manager. An alternate configuration file can be provide a well using:
spring.cache.ehcache.config=classpath:config/another-config.xml
31.1.4 Hazelcast
Spring Boot has a general support for Hazelcast. If a HazelcastInstance
has been auto-configured, it is automatically wrapped in a CacheManager
.
If for some reason you need a different HazelcastInstance
for caching, you can request Spring Boot to create a separate one that will be only used by the CacheManager
:
spring.cache.hazelcast.config=classpath:config/my-cache-hazelcast.xml
Tip | |
---|---|
If a separate HazelcastInstance is created that way, it is not registered in the application context. |
31.1.5 Infinispan
Infinispan has no default configuration file location so it must be specified explicitly (or the default bootstrap is used).
spring.cache.infinispan.config=infinispan.xml
Caches can be created on startup via the spring.cache.cache-names
property. If a custom ConfigurationBuilder
bean is defined, it is used to customize them.
31.1.6 Couchbase
If Couchbase is available and configured, a CouchbaseCacheManager
is auto-configured. It is also possible to create additional caches on startup using the spring.cache.cache-names
property. These will operate on the Bucket
that was auto-configured. You can also create additional caches on another Bucket
using the customizer: assume you need two caches on the "main" Bucket
(foo
and bar
) and one biz
cache with a custom time to live of 2sec on the another
Bucket
. First, you can create the two first caches simply via configuration:
spring.cache.cache-names=foo,bar
Then define this extra @Configuration
to configure the extra Bucket
and the biz
cache:
_@Configuration_ public class CouchbaseCacheConfiguration { private final Cluster cluster; public CouchbaseCacheConfiguration(Cluster cluster) { this.cluster = cluster; } _@Bean_ public Bucket anotherBucket() { return this.cluster.openBucket("another", "secret"); } _@Bean_ public CacheManagerCustomizer<CouchbaseCacheManager> cacheManagerCustomizer() { return c -> { c.prepareCache("biz", CacheBuilder.newInstance(anotherBucket()) .withExpirationInMillis(2000)); }; } }
This sample configuration reuses the Cluster
that was created via auto-configuration.
31.1.7 Redis
If Redis is available and configured, the RedisCacheManager
is auto-configured. It is also possible to create additional caches on startup using the spring.cache.cache-names
property.
Note | |
---|---|
By default, a key prefix is added to prevent that if two separate caches use the same key, Redis would have overlapping keys and be likely to return invalid values. We strongly recommend to keep this setting enabled if you create your own RedisCacheManager . |
31.1.8 Caffeine
Caffeine is a Java 8 rewrite of Guava’s cache and will supersede the Guava support in Spring Boot 2.0. If Caffeine is present, a CaffeineCacheManager
is auto-configured. Caches can be created on startup using the spring.cache.cache-names
property and customized by one of the following (in this order):
- A cache spec defined by
spring.cache.caffeine.spec
- A
com.github.benmanes.caffeine.cache.CaffeineSpec
bean is defined - A
com.github.benmanes.caffeine.cache.Caffeine
bean is defined
For instance, the following configuration creates a foo
and bar
caches with a maximum size of 500 and a time to live of 10 minutes
spring.cache.cache-names=foo,bar spring.cache.caffeine.spec=maximumSize=500,expireAfterAccess=600s
Besides, if a com.github.benmanes.caffeine.cache.CacheLoader
bean is defined, it is automatically associated to the CaffeineCacheManager
. Since the CacheLoader
is going to be associated to all caches managed by the cache manager, it must be defined as CacheLoader<Object, Object>
. Any other generic type will be ignored by the auto-configuration.
31.1.9 Guava
If Guava is present, a GuavaCacheManager
is auto-configured. Caches can be created on startup using the spring.cache.cache-names
property and customized by one of the following (in this order):
- A cache spec defined by
spring.cache.guava.spec
- A
com.google.common.cache.CacheBuilderSpec
bean is defined - A
com.google.common.cache.CacheBuilder
bean is defined
For instance, the following configuration creates a foo
and bar
caches with a maximum size of 500 and a time to live of 10 minutes
spring.cache.cache-names=foo,bar spring.cache.guava.spec=maximumSize=500,expireAfterAccess=600s
Besides, if a com.google.common.cache.CacheLoader
bean is defined, it is automatically associated to the GuavaCacheManager
. Since the CacheLoader
is going to be associated to all caches managed by the cache manager, it must be defined as CacheLoader<Object, Object>
. Any other generic type will be ignored by the auto-configuration.
31.1.10 Simple
If none of these options worked out, a simple implementation using ConcurrentHashMap
as cache store is configured. This is the default if no caching library is present in your application.
31.1.11 None
When @EnableCaching
is present in your configuration, a suitable cache configuration is expected as well. If you need to disable caching altogether in certain environments, force the cache type to none
to use a no-op implementation:
spring.cache.type=none