Implement Two-Level Cache With Spring

1. Overview

Caching data means our applications don’t have to access a slower storage layer, thereby improving their performance and responsiveness. We can implement caching using any in-memory implementation library, like Caffeine.

Although doing this improves the performance of data retrieval, if the application is deployed to multiple replica sets, then the cache isn’t shared between instances. To overcome this problem, we can introduce a distributed cache layer that can be accessed by all instances.

In this tutorial, we’ll learn how to implement the two-level caching mechanism in Spring. We’ll demonstrate how to implement both of these layers using Spring’s caching support, and how the distributed cache layer is called if the local cache layer incurs a cache miss.

2. Example Application in Spring Boot

Let’s imagine we need to build a simple application that calls a database to fetch some data.

2.1. Maven Dependency

First, let’s include the spring-boot-starter-web dependency:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.1.5</version>
</dependency>

2.2. Implementing a Spring Service

We’ll implement a Spring service that fetches the data from a repository.

First, let’s model the Customer class:

public class Customer implements Serializable {
    private String id;
    private String name;
    private String email;
    // standard getters and setters
}

Then let’s implement the CustomerService class and a getCustomer method:

@Service
public class CustomerService {
    
    private final CustomerRepository customerRepository;

    public Customer getCustomer(String id) {
        return customerRepository.getCustomerById(id);
    }
}

Finally, let’s define the CustomerRepository interface:

public interface CustomerRepository extends CrudRepository<Customer, String> {
}

Now we’ll implement the two levels of caching.

3. Implement the First Level of Cache

We’ll leverage Spring’s cache support and the Caffeine library to implement the first cache layer.

3.1. Caffeine Dependencies

Let’s include the spring-boot-starter-cache and caffeine dependencies:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-cache</artifactId>
    <version>3.1.5</version/
</dependency>
<dependency>
    <groupId>com.github.ben-manes.caffeine</groupId>
    <artifactId>caffeine</artifactId>
    <version>3.1.8</version>
</dependency>

3.2. Enable Caffeine Cache

To enable the Caffeine cache, we’ll need to add a few cache-related configurations.

First, we’ll add the @EnableCaching annotation in the CacheConfig class and include a few Caffeine cache configs:

@Configuration
@EnableCaching
public class CacheConfig {
    @Bean
    public CaffeineCache caffeineCacheConfig() {
        return new CaffeineCache("customerCache", Caffeine.newBuilder()
          .expireAfterWrite(Duration.ofMinutes(1))
          .initialCapacity(1)
          .maximumSize(2000)
          .build());
    }
}

Next, we’ll add the CaffeineCacheManager bean using the SimpleCacheManager class and set the cache config:

@Bean
public CacheManager caffeineCacheManager(CaffeineCache caffeineCache) {
    SimpleCacheManager manager = new SimpleCacheManager();
    manager.setCaches(Arrays.asList(caffeineCache));
    return manager;
}

3.3. Include the @Cacheable Annotation

To enable the above caching, we’ll need to add the @Cacheable annotation in the getCustomer method:

@Cacheable(cacheNames = "customerCache", cacheManager = "caffeineCacheManager")
public Customer getCustomer(String id) {
}

As discussed earlier, this works well in a single instance deployment environment, but isn’t very effective when the application runs with multiple replicas.

4. Implement the Second Level of Cache

We’ll implement the second level of caching using the Redis server. Of course, we can implement it with any other distributed cache as well, like Memcached. This layer of cache will be accessible to all of our application’s replicas.

4.1. Redis Dependency

Let’s add the spring-boot-starter-redis dependency:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
    <version>3.1.5</version>
</dependency>

4.2. Enable Redis Cache

We’ll need to add the Redis cache-related configuration to enable it in the application.

First, let’s configure the RedisCacheConfiguration bean with a few properties:

@Bean
public RedisCacheConfiguration cacheConfiguration() {
    return RedisCacheConfiguration.defaultCacheConfig()
      .entryTtl(Duration.ofMinutes(5))
      .disableCachingNullValues()
      .serializeValuesWith(RedisSerializationContext.SerializationPair.fromSerializer(new GenericJackson2JsonRedisSerializer()));
}

Then let’s enable the CacheManager using the RedisCacheManager class:

@Bean
public CacheManager redisCacheManager(RedisConnectionFactory connectionFactory, RedisCacheConfiguration cacheConfiguration) {
    return RedisCacheManager.RedisCacheManagerBuilder
      .fromConnectionFactory(connectionFactory)
      .withCacheConfiguration("customerCache", cacheConfiguration)
      .build();
}

4.3. Include the @Caching and @Cacheable Annotations

We’ll include the second cache in the getCustomer method with the @Caching and @Cacheable annotations:

@Caching(cacheable = {
  @Cacheable(cacheNames = "customerCache", cacheManager = "caffeineCacheManager"),
  @Cacheable(cacheNames = "customerCache", cacheManager = "redisCacheManager")
})
public Customer getCustomer(String id) {
}

We should note that Spring will fetch the cache object from the first available cache. If both cache managers miss, it will run the actual method.

5. Implement the Integration Tests

To verify our setup, we’ll implement a few integration tests and validate both caches.

First, we’ll create an integration test to verify both caches using an embedded Redis server:

@Test
void givenCustomerIsPresent_whenGetCustomerCalled_thenReturnCustomerAndCacheIt() {
    String CUSTOMER_ID = "100";
    Customer customer = new Customer(CUSTOMER_ID, "test", "[email protected]");
    given(customerRepository.findById(CUSTOMER_ID))
      .willReturn(customer);
    
    Customer customerCacheMiss = customerService.getCustomer(CUSTOMER_ID);
    
    assertThat(customerCacheMiss).isEqualTo(customer);
    verify(customerRepository, times(1)).findById(CUSTOMER_ID);
    assertThat(caffeineCacheManager.getCache("customerCache").get(CUSTOMER_ID).get()).isEqualTo(customer);
    assertThat(redisCacheManager.getCache("customerCache").get(CUSTOMER_ID).get()).isEqualTo(customer);
}

We’ll run the above test case and find that this works fine.

Next, let’s imagine a scenario where the first level of cache data gets evicted due to expiry, and we’ll try to get the same customer. Then it should be a cache hit to the second cache level, Redis. Any further cache hit for the same customer should be to the first cache.

Let’s implement the above test scenario to check for both caches after the local cache expiry:

@Test
void givenCustomerIsPresent_whenGetCustomerCalledTwiceAndFirstCacheExpired_thenReturnCustomerAndCacheIt() throws InterruptedException {
    String CUSTOMER_ID = "102";
    Customer customer = new Customer(CUSTOMER_ID, "test", "[email protected]");
    given(customerRepository.findById(CUSTOMER_ID))
      .willReturn(customer);

    Customer customerCacheMiss = customerService.getCustomer(CUSTOMER_ID);
    TimeUnit.SECONDS.sleep(3);
    Customer customerCacheHit = customerService.getCustomer(CUSTOMER_ID);

    verify(customerRepository, times(1)).findById(CUSTOMER_ID);
    assertThat(customerCacheMiss).isEqualTo(customer);
    assertThat(customerCacheHit).isEqualTo(customer);
    assertThat(caffeineCacheManager.getCache("customerCache").get(CUSTOMER_ID).get()).isEqualTo(customer);
    assertThat(redisCacheManager.getCache("customerCache").get(CUSTOMER_ID).get()).isEqualTo(customer);
}

When we run the above test, we’ll see an unexpected assertion error with the Caffeine cache object:

org.opentest4j.AssertionFailedError: 
expected: Customer(id=102, name=test, [email protected])
but was: null
...
at com.baeldung.caching.twolevelcaching.CustomerServiceCachingIntegrationTest.
givenCustomerIsPresent_whenGetCustomerCalledTwiceAndFirstCacheExpired_thenReturnCustomerAndCacheIt(CustomerServiceCachingIntegrationTest.java:91)

From the above logs, it’s evident that the customer object isn’t in the Caffeine cache after the eviction, and even if we call the same method again, it’s not restored from the second cache. This isn’t an ideal situation for this use case, as every time the first level cache expires, it never gets updated until the second cache also expires. This puts additional load into the Redis cache.

We should note that Spring doesn’t manage any data between multiple caches, even if they’re declared for the same method.

This tells us that we need to update the first-level cache whenever it’s accessed again.

6. Implement a Custom CacheInterceptor

To update the first cache, we’ll need to implement a custom cache interceptor to intercept whenever the cache is accessed.

We’ll add an interceptor to check if the current cache class is Redis type, and if the local cache doesn’t exist, then we can update the cache value.

Let’s implement a custom CacheInterceptor by overriding the doGet method:

public class CustomerCacheInterceptor extends CacheInterceptor {

    private final CacheManager caffeineCacheManager;

    @Override
    protected Cache.ValueWrapper doGet(Cache cache, Object key) {
        Cache.ValueWrapper existingCacheValue = super.doGet(cache, key);
      
        if (existingCacheValue != null && cache.getClass() == RedisCache.class) {
            Cache caffeineCache = caffeineCacheManager.getCache(cache.getName());
            if (caffeineCache != null) {
                caffeineCache.putIfAbsent(key, existingCacheValue.get());
            }
        }

        return existingCacheValue;
    }
}

We’ll also need to register the CustomerCacheInterceptor bean to enable it:

@Bean
public CacheInterceptor cacheInterceptor(CacheManager caffeineCacheManager, CacheOperationSource cacheOperationSource) {
    CacheInterceptor interceptor = new CustomerCacheInterceptor(caffeineCacheManager);
    interceptor.setCacheOperationSources(cacheOperationSource);
    return interceptor;
}

@Bean
public CacheOperationSource cacheOperationSource() {
    return new AnnotationCacheOperationSource();
}

We should note that the custom interceptor will intercept the call whenever the Spring proxy method calls the get cache method internally.

We’ll re-run the integration tests, and see that the above test cases pass.

7. Conclusion

In this article, we learned how to implement two levels of caching with Caffeine and Redis using Spring’s cache support. We also demonstrated how to update the first-level Caffeine cache with the custom cache interceptor implementation.