Introduction To Ehcache

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

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 that will calculate the square values of provided numbers. On each call, the method will call the .calculateSquareOfNumber() method and print an information message to the console.

With this simple example, we want to show that the calculation of squared values is done only once, and every other call with the same input value returns results from the 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 this article.

2. Maven Dependencies

First we need to add the correct Maven dependency to use Ehcache:

<dependency>
    <groupId>org.ehcache</groupId>
    <artifactId>ehcache</artifactId>
    <version>3.10.8</version>
    <classifier>jakarta</classifier>
</dependency>

Make sure to use the latest version of the Ehcache artifact, which 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 and 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, we first need to define the Ehcache CacheManager object. In this example, we are creating a default cache squaredNumber” with the newCacheManagerBuilder() API.

The cache will 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 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 3.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 3. we showed how you can define a simple cache for your purposes. To show that caching actually works, we will create SquaredCalculator class, which will calculate the squared value of the provided input and store the calculated value in a cache.

Of course, if the cache already contains the calculated value, we will return the 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 that can’t be saved into memory.

From the configuration, we can see that the cache will save 10 elements in 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 time so we can avoid big memory usage.

Ehcache controls data freshness through the 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 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 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.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.