From fbfdbce266641f724bfe7059abdf6ce39ab63f54 Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Tue, 2 Jun 2015 09:34:23 +0200 Subject: [PATCH] Add cache documentation See gh-2633 --- .../asciidoc/production-ready-features.adoc | 21 +++ .../main/asciidoc/spring-boot-features.adoc | 172 ++++++++++++++++++ 2 files changed, 193 insertions(+) diff --git a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc b/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc index 93323f01f5..5ad578ce82 100644 --- a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc @@ -832,6 +832,27 @@ for all supported data sources; you can add additional `DataSourcePoolMetadataPr beans if your favorite data source isn't supported out of the box. See `DataSourcePoolMetadataProvidersConfiguration` for examples. +[[production-ready-datasource-cache]] +=== Cache metrics +The following metrics are exposed for each supported cache defined in your application: + +* The current size of the cache (`cache.xxx.size`) +* Hit ratio (`cache.xxx.hit.ratio`) +* Miss ratio (`cache.xxx.miss.ratio`) + +NOTE: Cache providers do not expose the hit/miss ratio in a consistent way. While some +expose an **aggregated** value (i.e. the hit ratio since the last time the stats were +cleared), others expose a **temporal** value (i.e. the hit ratio of the last second). +Check your caching provider documentation for more details. + +If two different cache managers happen to define the same cache, the name of the cache +is prefixed by the name of the `CacheManager` bean. + +It is possible to override part or all of those defaults by registering a bean with a +customized version of `CachePublicMetrics`. By default, Spring Boot provides cache +statistics for EhCache, Hazelcast, Infinispan, JCache and Guava. You can add additional +`CacheStatisticsProvider` beans if your favorite caching library isn't supported out of +the box. See `CacheStatisticsAutoConfiguration` for examples. [[production-ready-session-metrics]] 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 1cf9cabf12..554f8933d9 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -2293,6 +2293,178 @@ TIP: For complete details of Spring Data Elasticsearch, refer to their http://docs.spring.io/spring-data/elasticsearch/docs/[reference documentation]. +[[boot-features-caching]] +== Caching + +The Spring Framework provides support for transparently adding caching into an +application. At its core, the abstraction applies caching to methods, reducing thus the +number of executions based on the information available in the cache. The caching logic +is applied transparently without any interference to the invoker. + +NOTE: Check the {spring-reference}/#cache[relevant section] of the Spring Framework +reference for more details. + +In a nutshell, adding caching to an operation of your service is as easy as adding the +relevant annotation to its method: + +[source,java,indent=0] +---- + import javax.cache.annotation.CacheResult; + + import org.springframework.stereotype.Component; + + @Component + public class MathService { + + @CacheResult + public int computePiDecimal(int i) { ... } + + } +---- + +NOTE: You can either use the standard JSR-107 (JCache) annotations or Spring's own +caching annotations transparently. We strongly advice you however to not mix and match +them. + +TIP: It is also possible to {spring-reference}/#cache-annotations-put[update] or +{spring-reference}/#cache-annotations-evict[evict] data from the cache transparently. + +=== Supported cache providers + +The cache abstraction does not provide an actual store and relies on a 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. + +Spring Boot tries to detect the following providers (in that order): + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +It is also possible to _force_ the cache provider to use via the `spring.cache.type` +property. + +[[boot-features-caching-provider-generic]] +==== Generic + +If the context defines _at least_ one `org.springframework.cache.Cache` bean, a +`CacheManager` wrapping them is configured. + +[[boot-features-caching-provider-ehcache2]] +==== EhCache 2.x + +EhCache 2.x tries to locate a configuration file named `ehcache.xml` 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: + +[source,properties,indent=0] +---- + spring.cache.ehcache.config=classpath:config/another-config.xml +---- + +[[boot-features-caching-provider-hazelcast]] +==== Hazelcast + +Hazelcast tries to locate its configuration file as follows: An `hazelcast.xml` file +stored either in the current working directory or at the root of the classpath, or a +location specified via the `hazelcast.config` system property. Spring Boot detects all +of these and allow for explicit location as well: + +[source,properties,indent=0] +---- + spring.cache.hazelcast.config=classpath:config/my-hazelcast.xml +---- + +[[boot-features-caching-provider-infinispan]] +==== Infinispan + +Infinispan has no default configuration file location so it must be specified explicitly +(or the default bootstrap is used). + +[source,properties,indent=0] +---- + 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. + +[[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 +also possible to create additional caches on startup using the `spring.cache.cache-names` +property. + +[[boot-features-caching-provider-guava]] +==== 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 that order): + +1. A cache spec defined by `spring.cache.guava.spec` +2. A `com.google.common.cache.CacheBuilderSpec` bean is defined +3. 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 + +[source,properties,indent=0] +---- + 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`. + +[[boot-features-caching-provider-simple]] +==== 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. + [[boot-features-messaging]] == Messaging