Redis Cache Java

Redis Cache Java is a cache abstraction for the Java ecosystem that leverages enterprise Redis features like indexing and query. It provides an implementation of Spring Framework’s Cache Abstraction.

Usage

Dependency

Maven

<dependency>
    <groupId>com.redis</groupId>
    <artifactId>redis-cache-core</artifactId>
    <version>0.1.2</version>
</dependency>

Gradle

dependencies {
    implementation 'com.redis:redis-cache-core:0.1.2'
}

Setup

To use Redis Cache Java as a backing implementation, add RedisCacheManager to your configuration as follows:

@Bean
public RedisCacheManager cacheManager(RedisModulesClient client) {
   return RedisCacheManager.create(client);
}

RedisCacheManager behavior can be configured with RedisCacheManagerBuilder, letting you set the default RedisCacheConfiguration and predefined caches.

RedisCacheManager cacheManager = RedisCacheManager.builder(client)
  .defaults(RedisCacheConfiguration.defaultConfig())
  .configuration("hashCache", RedisCacheConfiguration.defaultConfig().hash())
  .configuration("jsonCache", RedisCacheConfiguration.defaultConfig().json())
  .configuration("stringCache", RedisCacheConfiguration.defaultConfig().string())
  .build();

As shown in the preceding example, RedisCacheManager allows custom configuration on a per-cache basis.

The behavior of RedisCache created by RedisCacheManager is defined with RedisCacheConfiguration.

Configuration

The RedisCacheConfiguration object is the entry point to configure a Redis cache and enable its features.

Key Function

Use keyFunction(KeyFunction function) to set the KeyFunction used to compute Redis keys.

Default is KeyFunction.SIMPLE which produces keys in the form <cache>:<key>.

Key Expiration

To enable entry time-to-live (TTL) use entryTtl(Duration duration) or entryTtl(TtlFunction function).

Default is TtlFunction.PERSISTENT which does not expire keys.

Redis Data Type

Use redisType(RedisType type) to change the type of data-structure backing the cache.

Possible values are HASH, STRING, and JSON.

Default is HASH.

Each type has a corresponding value mapper which can be overriden:

• HASH: hashMapper(RedisHashMapper mapper)

• STRING: stringMapper(RedisStringMapper mapper)

• JSON: jsonMapper(RedisStringMapper mapper)

Client-Side Caching

Client-side caching (also known as local or near caching) can be enabled by setting localCache(Map<String, Object> cache).

For example with a simple java.util.Map implementation: localCache(new HashMap<>()).

For more control over the behavior of the local cache it is recommended to use an in-memory cache implementation like Caffeine:

Cache<String, Object> localCache = Caffeine.newBuilder()
            .maximumSize(10000)
            .expireAfterWrite(Duration.ofMinutes(5))
            .build();
return RedisCacheConfiguration.defaultConfig().localCache(localCache.asMap());

See the Caffeine Documentation for more configuration options.

Metrics

Redis Cache Java uses Micrometer to publish metrics. To enable metrics, set a MeterRegistry in your RedisCacheConfiguration:

RedisCacheConfiguration.defaultConfig().meterRegistry(registry);

The following metrics are published:

Name	Tags	Type	Description
cache.gets	result=hit|miss	Counter	The number of times cache lookup methods have returned a cached (hit) or uncached (miss) value.
cache.puts		Counter	The number of entries added to the cache.
cache.evictions		Counter	The number of times the cache was evicted.
cache.gets.latency		Timer	Cache get latency
cache.puts.latency		Timer	Cache put latency
cache.evictions.latency		Timer	Cache eviction latency
cache.local.gets	result=hit|miss	Counter	The number of times local cache lookup methods have returned a cached (hit) or uncached (miss) value.
cache.local.evictions		Counter	The number of times the local cache was evicted.

Note	All metrics expose their corresponding cache name as a tag: name=<cache>.

Quick Start

To understand how Redis Cache Java works, it’s best to try it for yourself.

This example showcases a Spring Boot application using Redis Cache Java.

First, clone this git repository:

git clone https://github.com/redis-field-engineering/redis-cache-java-dist.git
cd redis-cache-java-dist

Next, register and create an API read-access token at themoviedb.org.

Set the following environment variable with the token:

export TMDB_TOKEN=<your API read-access token>

Finally use Docker Compose to launch containers for Redis and the Redis Cache Java demo app instance:

docker compose up

You can then access the demo at localhost:8080.

As you click around on the different pages, notice how the response time improves after the first time you request a page.

Open another browser window and access Grafana at localhost:3000. Use username/password admin/admin to log in. You can skip changing password.

Arrange your browser windows with the demo app on the left and Grafana on the right:

Notice the HTTP response time decreasing with cache hits, and increasing with API requests.

Now click on the Search link to search the cache, for example with keyword corleone.

Notice how quickly search results are returned: the search feature is powered by Redis.

Search response time can be visualized with the panel at the bottom of the Grafana dashboard.

Support

Redis Cache Java is supported by Redis, Inc. for enterprise-tier customers as a 'Developer Tool' under the Redis Software Support Policy. For non enterprise-tier customers we supply support for Redis Cache Java on a good-faith basis. To report bugs, request features, or receive assistance, please file an issue.

License

Redis Cache Java is licensed under the Business Source License 1.1. Copyright © 2024 Redis, Inc. See LICENSE for details.