Skip to content

Revise RedisCache and documentation #2051

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 6 commits into from
Closed

Revise RedisCache and documentation #2051

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
40052ef
Prepare issue branch.
mp911de Apr 21, 2021
fc083d0
Add ScanOptions.pattern(…) accepting a byte[] pattern.
mp911de Apr 21, 2021
44f78c2
Add support for configurable batch strategies using RedisCache.
mp911de Apr 21, 2021
f1aa5a6
Documentation.
mp911de Apr 21, 2021
0a27cf3
Mention RedisCache locking behavior details.
mp911de Apr 21, 2021
68cef9a
Transition BatchStrategy to interface.
christophstrobl May 18, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

<modelVersion>4.0.0</modelVersion>

<groupId>org.springframework.data</groupId>
<artifactId>spring-data-redis</artifactId>
<version>2.6.0-SNAPSHOT</version>
<version>2.6.0-GH-1721-SNAPSHOT</version>

<name>Spring Data Redis</name>

Expand Down
132 changes: 132 additions & 0 deletions src/main/asciidoc/reference/redis-cache.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
[[redis:support:cache-abstraction]]
== Redis Cache

NOTE: Changed in 2.0

Spring Redis provides an implementation for the Spring https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/integration.html#cache[cache abstraction] through the `org.springframework.data.redis.cache` package. To use Redis as a backing implementation, add `RedisCacheManager` to your configuration, as follows:

[source,java]
----
@Bean
public RedisCacheManager cacheManager(RedisConnectionFactory connectionFactory) {
return RedisCacheManager.create(connectionFactory);
}
----

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

[source,java]
----
RedisCacheManager cm = RedisCacheManager.builder(connectionFactory)
.cacheDefaults(defaultCacheConfig())
.withInitialCacheConfigurations(singletonMap("predefined", defaultCacheConfig().disableCachingNullValues()))
.transactionAware()
.build();
----

As shown in the preceding example, `RedisCacheManager` allows definition of configurations on a per-cache basis.

The behavior of `RedisCache` created with `RedisCacheManager` is defined with `RedisCacheConfiguration`. The configuration lets you set key expiration times, prefixes, and `RedisSerializer` implementations for converting to and from the binary storage format, as shown in the following example:

[source,java]
----
RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
.entryTtl(Duration.ofSeconds(1))
.disableCachingNullValues();
----

`RedisCacheManager` defaults to a lock-free `RedisCacheWriter` for reading and writing binary values.
Lock-free caching improves throughput.
The lack of entry locking can lead to overlapping, non-atomic commands for the `putIfAbsent` and `clean` methods, as those require multiple commands to be sent to Redis. The locking counterpart prevents command overlap by setting an explicit lock key and checking against presence of this key, which leads to additional requests and potential command wait times.

Locking applies on the *cache level*, not per *cache entry*.

It is possible to opt in to the locking behavior as follows:

[source,java]
----
RedisCacheManager cm = RedisCacheManager.build(RedisCacheWriter.lockingRedisCacheWriter(connectionFactory))
.cacheDefaults(defaultCacheConfig())
...
----

By default, any `key` for a cache entry gets prefixed with the actual cache name followed by two colons.
This behavior can be changed to a static as well as a computed prefix.

The following example shows how to set a static prefix:

[source,java]
----
// static key prefix
RedisCacheConfiguration.defaultCacheConfig().prefixKeysWith("( ͡° ᴥ ͡°)");

The following example shows how to set a computed prefix:

// computed key prefix
RedisCacheConfiguration.defaultCacheConfig().computePrefixWith(cacheName -> "¯\_(ツ)_/¯" + cacheName);
----

The cache implementation defaults to use `KEYS` and `DEL` to clear the cache. `KEYS` can cause performance issues with large keyspaces. Therefore, the default `RedisCacheWriter` can be created with a `BatchStrategy` to switch to a `SCAN`-based batch strategy. The `SCAN` strategy requires a batch size to avoid excessive Redis command roundtrips:

[source,java]
----
RedisCacheManager cm = RedisCacheManager.build(RedisCacheWriter.nonLockingRedisCacheWriter(connectionFactory, BatchStrategies.scan(1000)))
.cacheDefaults(defaultCacheConfig())
...
----

NOTE: The `KEYS` batch strategy is fully supported using any driver and Redis operation mode (Standalone, Clustered). `SCAN` is fully supported when using the Lettuce driver. Jedis supports `SCAN` only in non-clustered modes.

The following table lists the default settings for `RedisCacheManager`:

.`RedisCacheManager` defaults
[width="80%",cols="<1,<2",options="header"]
|====
|Setting
|Value

|Cache Writer
|Non-locking, `KEYS` batch strategy

|Cache Configuration
|`RedisCacheConfiguration#defaultConfiguration`

|Initial Caches
|None

|Transaction Aware
|No
|====

The following table lists the default settings for `RedisCacheConfiguration`:

.RedisCacheConfiguration defaults
[width="80%",cols="<1,<2",options="header"]
|====
|Key Expiration
|None

|Cache `null`
|Yes

|Prefix Keys
|Yes

|Default Prefix
|The actual cache name

|Key Serializer
|`StringRedisSerializer`

|Value Serializer
|`JdkSerializationRedisSerializer`

|Conversion Service
|`DefaultFormattingConversionService` with default cache key converters
|====

[NOTE]
====
By default `RedisCache`, statistics are disabled.
Use `RedisCacheManagerBuilder.enableStatistics()` to collect local _hits_ and _misses_ through `RedisCache#getStatistics()`, returning a snapshot of the collected data.
====
119 changes: 2 additions & 117 deletions src/main/asciidoc/reference/redis.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -652,6 +652,8 @@ include::{referenceDir}/pipelining.adoc[]

include::{referenceDir}/redis-scripting.adoc[]

include::{referenceDir}/redis-cache.adoc[]

:leveloffset: 1
[[redis:support]]
== Support Classes
Expand Down Expand Up @@ -693,120 +695,3 @@ public class AnotherExample {

As shown in the preceding example, the consuming code is decoupled from the actual storage implementation. In fact, there is no indication that Redis is used underneath. This makes moving from development to production environments transparent and highly increases testability (the Redis implementation can be replaced with an in-memory one).

[[redis:support:cache-abstraction]]
=== Support for the Spring Cache Abstraction

NOTE: Changed in 2.0

Spring Redis provides an implementation for the Spring https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/integration.html#cache[cache abstraction] through the `org.springframework.data.redis.cache` package. To use Redis as a backing implementation, add `RedisCacheManager` to your configuration, as follows:

[source,java]
----
@Bean
public RedisCacheManager cacheManager(RedisConnectionFactory connectionFactory) {
return RedisCacheManager.create(connectionFactory);
}
----

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

[source,java]
----
RedisCacheManager cm = RedisCacheManager.builder(connectionFactory)
.cacheDefaults(defaultCacheConfig())
.withInitialCacheConfigurations(singletonMap("predefined", defaultCacheConfig().disableCachingNullValues()))
.transactionAware()
.build();
----

As shown in the preceding example, `RedisCacheManager` allows definition of configurations on a per-cache basis.

The behavior of `RedisCache` created with `RedisCacheManager` is defined with `RedisCacheConfiguration`. The configuration lets you set key expiration times, prefixes, and ``RedisSerializer`` implementations for converting to and from the binary storage format, as shown in the following example:

[source,java]
----
RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
.entryTtl(Duration.ofSeconds(1))
.disableCachingNullValues();
----

`RedisCacheManager` defaults to a lock-free `RedisCacheWriter` for reading and writing binary values. Lock-free caching improves throughput. The lack of entry locking can lead to overlapping, non-atomic commands for the `putIfAbsent` and `clean` methods, as those require multiple commands to be sent to Redis. The locking counterpart prevents command overlap by setting an explicit lock key and checking against presence of this key, which leads to additional requests and potential command wait times.

It is possible to opt in to the locking behavior as follows:

[source,java]
----
RedisCacheManager cm = RedisCacheManager.build(RedisCacheWriter.lockingRedisCacheWriter())
.cacheDefaults(defaultCacheConfig())
...
----

By default, any `key` for a cache entry gets prefixed with the actual cache name followed by two colons.
This behavior can be changed to a static as well as a computed prefix.

The following example shows how to set a static prefix:

[source,java]
----
// static key prefix
RedisCacheConfiguration.defaultCacheConfig().prefixKeysWith("( ͡° ᴥ ͡°)");

The following example shows how to set a computed prefix:

// computed key prefix
RedisCacheConfiguration.defaultCacheConfig().computePrefixWith(cacheName -> "¯\_(ツ)_/¯" + cacheName);
----

The following table lists the default settings for `RedisCacheManager`:

.`RedisCacheManager` defaults
[width="80%",cols="<1,<2",options="header"]
|====
|Setting
|Value

|Cache Writer
|Non-locking

|Cache Configuration
|`RedisCacheConfiguration#defaultConfiguration`

|Initial Caches
|None

|Transaction Aware
|No
|====

The following table lists the default settings for `RedisCacheConfiguration`:

.RedisCacheConfiguration defaults
[width="80%",cols="<1,<2",options="header"]
|====
|Key Expiration
|None

|Cache `null`
|Yes

|Prefix Keys
|Yes

|Default Prefix
|The actual cache name

|Key Serializer
|`StringRedisSerializer`

|Value Serializer
|`JdkSerializationRedisSerializer`

|Conversion Service
|`DefaultFormattingConversionService` with default cache key converters
|====

[NOTE]
====
By default `RedisCache`, statistics are disabled.
Use `RedisCacheManagerBuilder.enableStatistics()` to collect local _hits_ and _misses_ through `RedisCache#getStatistics()`, returning a snapshot of the collected data.
====
Loading