spring-boot/spring-boot-samples/spring-boot-sample-cache/README.adoc

= Spring Boot Cache Sample

This sample demonstrates the caching auto-configuration support. Spring's caching
abstraction is supported by many caching libraries, including:

* Any compliant `JSR-107` (JCache) provider
* `EhCache`
* `Hazelcast`
* `Infinispan`
* `Couchbase`
* `Redis`
* `Caffeine`
* `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
can look at the `/metrics` endpoint to review the cache statistics if your chosen
caching provider is supported.



== Using the JSR-107 annotations
The sample uses Spring's cache annotation. If you want to use the JSR-107 annotations
instead, simply add the `javax.cache:cache-api` dependency to the project. No further
configuration is necessary.

NOTE: You can use the JSR-107 annotations with _any_ cache provider; a JSR-107 compliant
cache provider is not necessary.



== Using a different cache provider
Initially, the project does not define any caching library so the abstraction works
on simple `ConcurrentHashMap`-based caches. You can try out your favorite caching library
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:

* `EhCache 3`: add `org.ehcache:ehcache`
* `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
used to configure the underlying `CacheManager`. Note that EhCache 3 uses a different
format and doesn't default to `ehcache.xml` anymore. Check
http://www.ehcache.org/documentation/3.0/xml.html[the documentation] for more details.



=== Hazelcast
Both `com.hazelcast:hazelcast` and `com.hazelcast:hazelcast-spring` should be added to
the project to enable support for Hazelcast.  Since there is a default `hazelcast.xml`
configuration file at the root of the classpath, it is used to automatically configure
the underlying `HazelcastInstance`.



=== Infinispan
Add the org.infinispan:infinispan-spring4-embedded` dependency to enable support for
Infinispan. There is no default location that Infinispan uses to look for a config file
so if you don't specify anything it will bootstrap on a hardcoded default. You can set
the `spring.cache.infinispan.config` property to use the provided `infinispan.xml`
configuration instead.



=== Couchbase
Add the `java-client` and `couchbase-spring-cache` dependencies and make sure that you
have setup at least a `spring.couchbase.bootstrap-hosts` property.



=== Redis
Add the `spring-boot-starter-data-redis` and make sure it is configured properly (by default,
a redis instance with the default settings is expected on your local box).



=== Caffeine
Simply add the `com.github.ben-manes.caffeine:caffeine` dependency to enable support
for Caffeine. You can customize how caches are created in different ways, see
`application.properties` for an example and the documentation for more details.



=== Guava
Spring Boot does not provide any dependency management for _Guava_ so you'll have to add
the `com.google.guava:guava` dependency with a version. You can customize how caches are
created in different ways, see `application.properties` for an example and the
documentation for more details.