I just announced the new Spring Boot 2 material, coming in REST With Spring:

>> CHECK OUT THE COURSE

1. Overview

In this article, we will introduce Ehcache, a widely used, open-source Java-based cache. It features memory and disk stores, listeners, cache loaders, RESTful and SOAP APIs and other very useful features.

To show how caching can optimize our application, we will create a simple method which will calculate square values of provided numbers. On each call, the method will call calculateSquareOfNumber(int number) method and print information message to the console.

With this simple example, we want to show that calculation of squared values is done only once, and every other call with same input value is returning result from cache.

It’s important to notice that we’re focused entirely on Ehcache itself (without Spring); if you want to see how Ehcache works with Spring, have a look at read this article.

2. Maven Dependencies

In order to use Ehcache we need to add this Maven dependency:

<dependency>
    <groupId>org.ehcache</groupId>
    <artifactId>ehcache</artifactId>
    <version>3.1.3</version>
</dependency>

The latest version of the Ehcache artifact can be found here.

3. Cache Configuration

Ehcache can be configured in two ways:

  • The first way is through Java POJO where all configuration parameters are configured through Ehcache API
  • The second way is configuration through XML file where we can configure Ehcache according to provided schema definition

In this article, we’ll show both approaches – Java as well as XML configuration.

3.1. Java Configuration

This subsection will show how easy it is to configure Ehcache with POJOs. Also, we will create a helper class for easier cache configuration and availability:

public class CacheHelper {

    private CacheManager cacheManager;
    private Cache<Integer, Integer> squareNumberCache;

    public CacheHelper() {
        cacheManager = CacheManagerBuilder
          .newCacheManagerBuilder().build();
        cacheManager.init();

        squareNumberCache = cacheManager
          .createCache("squaredNumber", CacheConfigurationBuilder
            .newCacheConfigurationBuilder(
              Integer.class, Integer.class,
              ResourcePoolsBuilder.heap(10)));
    }

    public Cache<Integer, Integer> getSquareNumberCacheFromCacheManager() {
        return cacheManager.getCache("squaredNumber", Integer.class, Integer.class);
    }
    
    // standard getters and setters
}

To initialize our cache, first, we need to define Ehcache CacheManager object. In this example, we are creating a default cache squaredNumber” with the newCacheManagerBuilder() API.

The cache will simply map Integer keys to Integer values.

Notice how, before we start using the defined cache, we need to initialize the CacheManager object with the init() method.

Finally, to obtain our cache, we can just use the getCache() API with the provided name, key and value types of our cache.

With those few lines, we created our first cache which is now available to our application.

3.2. XML Configuration

The configuration object from subsection 4.1. is equal to using this XML configuration:

<cache-template name="squaredNumber">
    <key-type>java.lang.Integer</key-type>
    <value-type>java.lang.Integer</value-type>
    <heap unit="entries">10</heap>
</cache-template>

And to include this cache in our Java application, we need to read XML configuration file in Java:

URL myUrl = getClass().getResource(xmlFile); 
XmlConfiguration xmlConfig = new XmlConfiguration(myUrl); 
CacheManager myCacheManager = CacheManagerBuilder
  .newCacheManager(xmlConfig);

4. Ehcache Test

In section 4. we showed how you can define simple cache for your purposes. To show that caching actually works, we will create SquaredCalculator class which will calculate squared value of the provided input, and store calculated value in a cache.

Of course, if cache already contains calculated value, we will return cached value and avoid unnecessary calculations:

public class SquaredCalculator {
    private CacheHelper cache;

    public int getSquareValueOfNumber(int input) {
        if (cache.getSquareNumberCache().containsKey(input)) {
            return cache.getSquareNumberCache().get(input);
        }

        System.out.println("Calculating square value of " + input + 
          " and caching result.");

        int squaredValue = (int) Math.pow(input, 2);
        cache.getSquareNumberCache().put(input, squaredValue);

        return squaredValue;
    }

    //standard getters and setters;
}

To complete our test scenario, we will also need the code which will calculate square values:

@Test
public void whenCalculatingSquareValueAgain_thenCacheHasAllValues() {
    for (int i = 10; i < 15; i++) {
        assertFalse(cacheHelper.getSquareNumberCache().containsKey(i));
        System.out.println("Square value of " + i + " is: "
          + squaredCalculator.getSquareValueOfNumber(i) + "\n");
    }      
    
    for (int i = 10; i < 15; i++) {
        assertTrue(cacheHelper.getSquareNumberCache().containsKey(i));
        System.out.println("Square value of " + i + " is: "
          + squaredCalculator.getSquareValueOfNumber(i) + "\n");
    }
}

If we run our test, we will get this result in our console:

Calculating square value of 10 and caching result.
Square value of 10 is: 100

Calculating square value of 11 and caching result.
Square value of 11 is: 121

Calculating square value of 12 and caching result.
Square value of 12 is: 144

Calculating square value of 13 and caching result.
Square value of 13 is: 169

Calculating square value of 14 and caching result.
Square value of 14 is: 196

Square value of 10 is: 100
Square value of 11 is: 121
Square value of 12 is: 144
Square value of 13 is: 169
Square value of 14 is: 196

As you can notice, calculate() method was doing calculations only on first call. On the second call, all values were found in the cache and returned from it.

5. Other Ehcache Configuration Options

When we created our cache in the previous example, it was a simple cache without any special options. This section will show other options which are useful in cache creation.

5.1. Disk Persistence

If there are too many values to store into the cache, we can store some of those values on the hard drive.

PersistentCacheManager persistentCacheManager = 
  CacheManagerBuilder.newCacheManagerBuilder()
    .with(CacheManagerBuilder.persistence(getStoragePath()
      + File.separator 
      + "squaredValue")) 
    .withCache("persistent-cache", CacheConfigurationBuilder
      .newCacheConfigurationBuilder(Integer.class, Integer.class,
        ResourcePoolsBuilder.newResourcePoolsBuilder()
          .heap(10, EntryUnit.ENTRIES)
          .disk(10, MemoryUnit.MB, true)) 
      )
  .build(true);

persistentCacheManager.close();

Instead of default CacheManager, we now use PersistentCacheManager which will persist all values which can’t be saved into memory.

From configuration, we can see that cache will save 10 elements into memory and it will allocate 10MB on the hard drive for persistence.

5.2. Data Expiry

If we cache a lot of data, it’s natural that we save cached data for some period of time so we can avoid big memory usage.

Ehcache controls data freshness trough Expiry interface:

CacheConfiguration<Integer, Integer> cacheConfiguration 
  = CacheConfigurationBuilder
    .newCacheConfigurationBuilder(Integer.class, Integer.class, 
      ResourcePoolsBuilder.heap(100)) 
    .withExpiry(Expirations.timeToLiveExpiration(Duration.of(60, 
      TimeUnit.SECONDS))).build();

In this cache, all data will live for 60 seconds and after that period of time, it will be deleted from memory.

6. Conclusion

In this article, we showed how to use simple Ehcache caching in a Java application.

In our example, we saw that even a simply configured cache can save a lot of unnecessary operations. Also, we showed that we can configure caches through POJOs and XML and that Ehcache has quite some nice features – such as persistence and data expiry.

As always, the code from this article can be found on GitHub.

I just announced the new Spring Boot 2 material, coming in REST With Spring:

>> CHECK OUT THE LESSONS