1. Introduction

In today’s blog post we will look at how we can use the caching provider Ehcache in Spring Boot. Ehcache is an open source library implemented in Java for implementing caches in Java programs, especially local and distributed caches in main memory or on the hard disk. Thanks to the implementation of JSR-107, Ehcache is fully compatible with the javax.cache API. Due to this compatibility, integration into Spring or Hibernate is very easy.

Before we start, we will have a quick look at what a cache is and in which scenarios a cache makes sense. Then we’ll take a quick look at how caching works in Spring. For the main part of the post, I brought along a demo project with some code.

2. Caching

Caching is a technique that involves the intermediate storage of data in very fast memory, usually. This means that this data can be made available much more quickly for subsequent requests since it does not have to be retrieved or recalculated from the primary and usually slower memory first.

Caching is particularly useful for the following scenarios:

• • The same data is requested again and again (so-called hot spots), which have to be loaded from the database anew with each request. This data can be cached in the main memory of the server application (RAM) or on the client (browser cache). This reduces access times and the number of data transfers since the server does not have to repeatedly request data from the database and send it to the client.
  • Long-term or resource-intensive operations are often performed with specific parameters. Depending on the parameters, the result of the operation can be stored temporarily so that the server can send the result to the client without executing the operation.

3. Caching in Spring

In Spring or Spring Boot it is very easy to add caching to an application. All you need to do is activate caching support via Annotation @EnableCaching. As we are used to from Spring Boot, the entire caching infrastructure is configured for us.

Springs Caching Service is an abstraction and not an implementation. Therefore it is necessary to use a cache provider or cache implementation for caching. Spring supports a wide range of cache providers:

• • Ehcache 3 (we will have a look at this today)
  • Hazelcast
  • Infinispan
  • Couchbase
  • Redis
  • Caffeine
  • Pivotal GemFire

A change of the cache provider has no effect on the existing code, as the developer only gets in touch with the abstract concepts.

If no cache provider is added, Spring Boot configures a very simple provider that caches in main memory using maps. This is sufficient for testing, but for applications in production, you should choose one of the above cache providers.

4. Ehcache Caching Tiers

Ehcache can be configured in such a way that the caching layer can consist of more than one memory area. When using more than one memory area, the areas are arranged as hierarchical tiers. The lowest tier is called the Authority Tier and the other tiers are called the Near Cache.

The most frequently used data is stored in the fastest caching tier (top layer). The authority tier basically contains all cache entries.

The memory areas supported by Ehcache include:

• • On-Heap Store: Uses the Java heap memory to store cache entries and shares the memory with the application. The cache is also scanned by the garbage collection. This memory is very fast, but also very limited.
  • Off-Heap Store: Uses the RAM to store cache entries. This memory is not subject to garbage collection. Still quite fast memory, but slower than the on-heap memory, because the cache entries have to be moved to the on-heap memory before they can be used.
  • Disk Store: Uses the hard disk to store cache entries. Much slower than RAM. It is recommended to use a dedicated SSD that is only used for caching.

In our demo project, we will use a three-tier cache with a disk store as an authority tier.

5. Ehcache Demo

5.1 Used Dependencies

For the Ehcache demo project we need the following dependencies in our Spring Boot based application:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-cache</artifactId>
</dependency>
<dependency>
    <groupId>javax.cache</groupId>
    <artifactId>cache-api</artifactId>
</dependency>
<dependency>
    <groupId>org.ehcache</groupId>
    <artifactId>ehcache</artifactId>
    <version>3.7.1</version>
</dependency>

The dependency spring-boot-starter-webis a starter for building web applications. In our example, we will build a simple service that performs a calculation for us. The calculation can be triggered by using a REST endpoint.

For caching we need spring-boot-starter-cache and cache-api dependency as well as the dependency ehcache as a cache provider.

5.2 Enable Caching

To enable caching support in Spring Boot, we need a simple configuration class that must be annotated with @EnableCaching. Up to this point, we don’t need to do anything more as the following code shows:

@Configuration
@EnableCaching
public class EhcacheConfig {
}

5.3 Cacheable Operation

We start our example with a simple service that calculates the area of a circle. The formula A = PI * radius² is used to calculate the area. The code is as follows:

@Service
public class CalculationService {

  private final Logger LOG = LoggerFactory.getLogger(CalculationService.class);

  public double areaOfCircle(int radius) {
    LOG.info("calculate the area of a circle with a radius of {}", radius);
    return Math.PI * Math.pow(radius, 2);
  }
}

Caching in Spring is basically applied to methods so that especially the calls of very costly operations can be reduced. We now want to add the result of this calculation to a cache depending on the radius passed by parameter, so that the calculation does not have to be repeated every time. To do this, we annotate the method with the @Cachable annotation:

@Cacheable(value = "areaOfCircleCache", key = "#radius", condition = "#radius > 5")
public double areaOfCircle(int radius) {
  LOG.info("calculate the area of a circle with a radius of {}", radius);
  return Math.PI * Math.pow(radius, 2);
}

Each time this method is called with a radius greater than 5, the caching behavior is applied. This checks whether the method has already been called once for the specified parameter. If so, the result is returned from the cache and the method is not executed. If no, then the method is executed and the result is returned and stored in the cache.

The following parameters, among others, are available for annotation:

5.4 Ehcache Cache Configuration

Now the configuration of the Ehcache cache has to be done. The configuration is XML-based. We create the XML file ehcache.xml in the resource folder of our application.

5.4.1 Cache Template

First, we will define a cache template. This is especially advantageous if the application is to have more than one cache, but the configuration of the caches is largely the same. For our demo application it is conceivable, for example, that we want to cache the results of the circle area calculation and in another cache the results of a power calculation. For the cache template we use the following XML code:

<config
        xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
        xmlns='http://www.ehcache.org/v3'
        xsi:schemaLocation="
            http://www.ehcache.org/v3 
            http://www.ehcache.org/schema/ehcache-core-3.7.xsd">

    <!-- Persistent cache directory -->
    <persistence directory="spring-boot-ehcache/cache" />

    <!-- Default cache template -->
    <cache-template name="default">
        <expiry>
            <ttl unit="seconds">30</ttl>
        </expiry>

        <listeners>
            <listener>
                <class>guru.springframework.ehcache.config.CacheLogger</class>
                <event-firing-mode>ASYNCHRONOUS</event-firing-mode>
                <event-ordering-mode>UNORDERED</event-ordering-mode>
                <events-to-fire-on>CREATED</events-to-fire-on>
                <events-to-fire-on>EXPIRED</events-to-fire-on>
                <events-to-fire-on>EVICTED</events-to-fire-on>
            </listener>
        </listeners>

        <resources>
            <heap>1000</heap>
            <offheap unit="MB">10</offheap>
            <disk persistent="true" unit="MB">20</disk>
        </resources>
    </cache-template>

</config>

persistence Tag

In the persistence tag, we define the directory for a file-based cache on the hard disk (disk store). This is only the definition of the folder. Whether we really want to use a disk store or not will be configured later.

expiry Tag

In the expiry tag, we define a time to live (ttl) of 30 seconds. The time to live specifies how long a cache entry may remain in the cache independently of access. After the specified time has expired, the value is removed from the cache.

It is also possible to define a time to idle (tti). The time to idle specifies how long the cache entry may exist in the cache without access. For example, if a value is not requested for more than 30 seconds, it is removed from the cache.

listeners Tag

In the listeners tag, we configure a CacheEventListener. The listener reacts to the following events:

• • A cache entry is placed in the cache (CREATED).
  • The validity of a cache entry has expired (EXPIRED).
  • A cache entry is evicted from the cache (EVICTED).

The specified CacheLogger class only logs the occurred cache event on the console:

public class CacheLogger implements CacheEventListener<Object, Object> {

  private final Logger LOG = LoggerFactory.getLogger(CacheLogger.class);

  @Override
  public void onEvent(CacheEvent<?, ?> cacheEvent) {
    LOG.info("Key: {} | EventType: {} | Old value: {} | New value: {}",
             cacheEvent.getKey(), cacheEvent.getType(), cacheEvent.getOldValue(), 
             cacheEvent.getNewValue());
  }

}

resources Tag

In the resources tag, we configure the tiers and capacities of our cache. We use a three-tier cache with a disk store as authority tier:

• heap: For the on heap store we configure a capacity of 1,000 cache entries. This is the maximum number of entries before eviction starts.
• offheap: For the off-heap store we configure a capacity of 10 MB.
• disk: As disk cache, we configure 20 MB. Important: The disk cache must always have a higher memory capacity than the heap cache, otherwise the application throws an exception during application startup when parsing the XML file.

Ehcache uses Last Recently Used (LRU) as the default eviction strategy for the memory stores. The eviction strategy determines which cache entry is to be evicted when the cache is full. The cache entries are always evicted to the next lower tier, for example, from the on-heap store to the off-heap store.

If a disk store is used and this is full, another cache entry is removed when a cache entry is added. The disk store uses Last Frequently Used (LFU) as the eviction strategy.

5.4.2 Cache configuration

Using the cache template we just created, we can now configure our cache. Thanks to the template we only have to define a name (alias) as well as the type of the cache key (key-type) and the type of the cached value (value-type):

<config ...>

    <!-- Persistent cache directory -->
    ...
    <!-- Default cache template -->
    ...

    <!-- Cache configuration -->
    <cache alias="areaOfCircleCache" uses-template="default">
        <key-type>java.lang.Integer</key-type>
        <value-type>java.lang.Double</value-type>
    </cache>

</config>

I would like to point out that we could have configured the cache without the cache template. All settings made in the cache-template tag can also be used directly within the cache tag.

Note: If the cache key consists of more than one method parameter, the type java.util.ArrayList must be used as the key-type.

5.4.3 Wiring of ehcache.xml with application.properties

Finally, we tell the application.properties file where our configuration file for Ehcache is located:

spring.cache.jcache.config=classpath:ehcache.xml

5.5 Simple RestController

We now use our CalculationService within the class CalculationRestController and implement a simple REST endpoint, which gives us the result for the calculation of a circular area:

@RestController
@RequestMapping("/rest/calculate")
public class CalculationRestController {

  private final CalculationService calculationService;

  @Autowired
  public CalculationRestController(CalculationService calculationService) {
    this.calculationService = calculationService;
  }

  @GetMapping(path = "/areaOfCircle", produces = MediaType.APPLICATION_JSON_VALUE)
  public ResponseEntity<Double> areaOfCircle(@RequestParam int radius) {
    double result = calculationService.areaOfCircle(radius);

    return ResponseEntity.ok(result);
  }

}

If, for example, we call the URL http://localhost:8080/rest/calculate/areaOfCircle?radius=6 after starting our application, the area of a circle with a radius of 6 is calculated and the result is displayed in the browser or in Postman.

For the first call of the URL, the calculation of the circle area is still carried out. For all further calls, we get the result from the cache. Our built-in log output shows that the method is actually entered only once.

If we calculate the circular area for a radius of 3, then the method is always executed, because the specified radius does not meet the cache condition #radius > 5. A possible log output could be as follows (for a better overview I have omitted the output of the CacheLogger):

2019-06-10 16:13:20.605 INFO (...) : calculate the area of a circle with a radius of 6
2019-06-10 16:13:29.787 INFO (...) : calculate the area of a circle with a radius of 3
2019-06-10 16:13:30.433 INFO (...) : calculate the area of a circle with a radius of 3
2019-06-10 16:13:30.820 INFO (...) : calculate the area of a circle with a radius of 3
2019-06-10 16:13:30.980 INFO (...) : calculate the area of a circle with a radius of 3
2019-06-10 16:13:31.265 INFO (...) : calculate the area of a circle with a radius of 3

6. Further examples

6.1 Key Generator

If the possibilities of the SpEL for the generation of the cache key are not enough, the annotation @Cacheable offers the possibility to use its own KeyGenerator bean. The bean must implement the functional interface KeyGenerator. The name of the bean must be specified as the value for the annotation parameter keyGenerator:

@Cacheable(value = "multiplyCache", keyGenerator = "multiplyKeyGenerator")
public double multiply(int factor1, int factor2) {
  LOG.info("Multiply {} with {}", factor1, factor2);
  return factor1 * factor2;
}

We define the associated bean in the class EhcacheConfig:

@Configuration
@EnableCaching
public class EhcacheConfig {

  @Bean
  public KeyGenerator multiplyKeyGenerator() {
    return (Object target, Method method, Object... params) -> 
           method.getName() + "_" + Arrays.toString(params);
  }

}

6.2 @CacheEvict

A cache can become very large very quickly. The problem with large caches is that they occupy a lot of important main memory and mostly consist of stale data that is no longer needed.

To avoid inflated caches, you should, of course, have configured a meaningful eviction strategy. On the other hand, it is also possible to empty the cache based on requests. The following example shows how to remove all entries from the caches areaOfCircleCache and multiplyCache.

@CacheEvict(cacheNames = {"areaOfCircleCache", "multiplyCache"}, allEntries = true)
public void evictCache() {
  LOG.info("Evict all cache entries...");
}

6.3 @CacheConfig

The @CacheConfig annotation allows us to define certain cache configurations at the class level. This is especially useful if certain cache settings are the same for all methods to be cached:

@Service
@CacheConfig(cacheNames = "studentCache")
public class StudentService {

  // ...

  @Cacheable
  public Optional<Student> find(Long id) {
    // ...   
  }

  @CachePut(key = "#result.id")
  public Student create(String firstName, String lastName, String courseOfStudies) {
    // ...
  }

}

Both the find() and create() methods use the studentCache cache in this example.

6.4 @CachePut

In the previous chapter of this post, we got to know @Cacheable. Methods annotated with @Cacheable are not executed again if a value already exists in the cache for the cache key. If the value does not exist in the cache, then the method is executed and places its value in the cache.

Now there is also the use case that we always want the method to be executed and its result to be placed in the cache. This is done using the @CachePut annotation, which has the same annotation parameters as @Cachable.

A possible scenario for using @CachePut is, for example, creating an entity object, as the following example shows:

@CachePut(cacheNames = "studentCache", key = "#result.id")
public Student create(String firstName, String lastName, String courseOfStudies) {
  LOG.info("Creating student with firstName={}, lastName={} and courseOfStudies={}", 
           firstName, lastName, courseOfStudies);
  
  long newId = ID_CREATOR.incrementAndGet();
  Student newStudent = new Student(newId, firstName, lastName, courseOfStudies);      
  
  // persist in database

  return newStudent;
}

The key #result is a placeholder provided by Spring and refers to the return value of the method. The ID of the student is, therefore, the cache key. The cache entry is the return value of the method, the student in our example.

The method now creates a student object and stores it in the studentCache at the end. The next time this object is requested, it can be retrieved directly from the cache.

7. JSR 107 Annotations vs. Spring Cache Annotations

Since Ehcache is fully JSR 107 compliant, JSR 107 annotations can be used instead of Spring Cache annotations. Spring recommends to choose one side and not to mix the annotations at all. The following table shows a comparison of the available cache annotations:

8. Summary

In this blog post, we looked at how to configure and use the cache provider Ehcache in Spring Boot. We looked at the following:

• • What are caches and what are they good for?
  • How does caching work in Spring?
  • Using Spring Cache Annotations
    • @EnableCaching
    • @Cacheable
    • @CacheEvict
    • @CachePut
    • @CacheConfig
  • Configuration of Ehcache caches
  • Custom cache keys
  • Comparison JSR 107 Annotations and Spring Cache Annotations

Also, like to check out the project repository at GitHub. It contains a fully functional Spring Boot application with Ehcache as the cache provider.