From 63d157bb7c08e43847169a4f5dbee089562e170c Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Tue, 25 Aug 2015 15:07:24 +0200 Subject: [PATCH] Favor JSR-107 provider if present Previously, native cache libraries were favored over a standard JSR-107 implementation. If a user has a working setup using JCache with one provider and switch to another provider, his setup may be broken if we happen to provide a native support for the new provider. We now consistently favor JSR-107 if it is present. Native support can still be enabled via the `spring.cache.type` property. Closes gh-3822 --- .../boot/autoconfigure/cache/CacheType.java | 10 +-- .../main/asciidoc/spring-boot-features.adoc | 66 +++++++++---------- .../spring-boot-sample-cache/README.adoc | 34 ++++++---- .../spring-boot-sample-cache/pom.xml | 9 +++ .../src/main/resources/application.properties | 1 - 5 files changed, 67 insertions(+), 53 deletions(-) diff --git a/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/cache/CacheType.java b/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/cache/CacheType.java index c9e3ae7b42..ceac4541b7 100644 --- a/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/cache/CacheType.java +++ b/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/cache/CacheType.java @@ -31,6 +31,11 @@ public enum CacheType { */ GENERIC, + /** + * JCache (JSR-107) backed caching. + */ + JCACHE, + /** * EhCache backed caching. */ @@ -46,11 +51,6 @@ public enum CacheType { */ INFINISPAN, - /** - * JCache (JSR-107) backed caching. - */ - JCACHE, - /** * Redis backed caching. */ diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index 483ef69c83..b209df5fd3 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -2806,10 +2806,10 @@ implementations are only provided by the `spring-context-support` jar. Spring Boot tries to detect the following providers (in this order): * <> +* <> * <> * <> * <> -* <> * <> * <> * <> @@ -2826,6 +2826,38 @@ Generic caching is used if the context defines _at least_ one +[[boot-features-caching-provider-jcache]] +==== JCache +JCache is bootstrapped via the presence of a `javax.cache.spi.CachingProvider` on the +classpath (i.e. a JSR-107 compliant caching library). It might happen than more that 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. + +[source,properties,indent=0] +---- + # 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 custom +`javax.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 the `CacheManager` 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. + + + [[boot-features-caching-provider-ehcache2]] ==== EhCache 2.x EhCache 2.x is used if a file named `ehcache.xml` can be found at the root of the @@ -2868,38 +2900,6 @@ Caches can be created on startup via the `spring.cache.cache-names` property. If -[[boot-features-caching-provider-jcache]] -==== JCache -JCache is bootstrapped via the presence of a `javax.cache.spi.CachingProvider` on the -classpath (i.e. a JSR-107 compliant caching library). It might happen than more that 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. - -[source,properties,indent=0] ----- - # 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 -it is advised to set the `spring.cache.type` to `jcache` to force that mode if that's -what you want. - -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 custom -`javax.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 the `CacheManager` 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. - - - [[boot-features-caching-provider-redis]] ==== Redis If Redis is available and configured, the `RedisCacheManager` is auto-configured. It is diff --git a/spring-boot-samples/spring-boot-sample-cache/README.adoc b/spring-boot-samples/spring-boot-sample-cache/README.adoc index bc64c7dd80..d0db1e646f 100644 --- a/spring-boot-samples/spring-boot-sample-cache/README.adoc +++ b/spring-boot-samples/spring-boot-sample-cache/README.adoc @@ -10,6 +10,7 @@ abstraction is supported by many caching libraries, including: * `Redis` * `Guava` * Simple provider based on `ConcurrentHashMap` +* Generic provider based on `org.springframework.Cache` bean definition(s) The sample defines a simple `CountryService` that caches countries by ISO code. When the application starts a client invokes the service with a random code every 500ms. You @@ -35,6 +36,25 @@ as explained below. +=== JCache (JSR-107) +If you want to configure your cache infrastructure via the standard, you need a compliant +implementation and the JSR-107 api. You first need to add `javax.cache:cache-api` to your +project. Then you could try the following: + +* `Hazelcast`: add `com.hazelcast:hazelcast` +* `Infinispan`: add `org.infinispan:infinispan-jcache` + +TIP: Certain cache providers do not create a default cache on-the-fly if it does not exist +so you might need to update the sample to create the caches on startup or specify the +location to the provider-specific file via the `spring.cache.jcache.config` property. + +NOTE: Any other JSR-107 compliant provider is also supported but Spring Boot may not +offer a dependency management entry for it. You will have to add it with the version +of the library that you want to use. + + + + === EhCache 2.x Simply add the `net.sf.ehcache:ehcache` dependency to the project. Since there is a default `ehcache.xml` configuration file at the root of the classpath, it is automatically @@ -59,20 +79,6 @@ can set the `spring.cache.infinispan.config` property to use the provided -=== JCache (JSR-107) -If you want to configure your cache infrastructure via the standard, you need a compliant -implementation. You could try the following: - -* `Hazelcast`: add `com.hazelcast:hazelcast` -* `Infinispan`: add `org.infinispan:infinispan-jcache` - - -Since Spring Boot supports the native cache library and the JCache wrapper, you -should set the `spring.cache.type` property to `jcache` to specify that you want the -cache manager to be auto-configured that way. - - - === Redis Add the `spring-boot-starter-redis` and make sure it is configured properly (by default, a redis instance with the default settings is expected on your local box). diff --git a/spring-boot-samples/spring-boot-sample-cache/pom.xml b/spring-boot-samples/spring-boot-sample-cache/pom.xml index 7d16731f3c..876103002b 100644 --- a/spring-boot-samples/spring-boot-sample-cache/pom.xml +++ b/spring-boot-samples/spring-boot-sample-cache/pom.xml @@ -33,6 +33,15 @@ org.springframework.boot spring-boot-starter-actuator + + + +