diff --git a/src/main/asciidoc/reference/redis-cache.adoc b/src/main/asciidoc/reference/redis-cache.adoc index d0011a04e..d9b91e731 100644 --- a/src/main/asciidoc/reference/redis-cache.adoc +++ b/src/main/asciidoc/reference/redis-cache.adoc @@ -3,13 +3,14 @@ NOTE: Changed in 2.0 -Spring Data Redis provides an implementation of Spring Framework's {spring-framework-reference}/integration.html#cache[Cache Abstraction] in the `org.springframework.data.redis.cache` package. To use Redis as a backing implementation, add `RedisCacheManager` to your configuration, as follows: +Spring Data Redis provides an implementation of Spring Framework's {spring-framework-reference}/integration.html#cache[Cache Abstraction] in 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); + return RedisCacheManager.create(connectionFactory); } ---- @@ -18,27 +19,29 @@ public RedisCacheManager cacheManager(RedisConnectionFactory connectionFactory) [source,java] ---- RedisCacheManager cacheManager = RedisCacheManager.builder(connectionFactory) - .cacheDefaults(RedisCacheConfiguration.defaultCacheConfig()) - .transactionAware() - .withInitialCacheConfigurations(Collections.singletonMap("predefined", + .cacheDefaults(RedisCacheConfiguration.defaultCacheConfig()) + .transactionAware() + .withInitialCacheConfigurations(Collections.singletonMap("predefined", RedisCacheConfiguration.defaultCacheConfig().disableCachingNullValues())) - .build(); + .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`. 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: +The behavior of `RedisCache` created by `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 cacheConfiguration = RedisCacheConfiguration.defaultCacheConfig() .entryTtl(Duration.ofSeconds(1)) - .disableCachingNullValues(); + .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 `Cache` `putIfAbsent` and `clean` operations, 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. +The lack of entry locking can lead to overlapping, non-atomic commands for the `Cache` `putIfAbsent` and `clean` operations, 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*. @@ -48,8 +51,8 @@ It is possible to opt in to the locking behavior as follows: ---- RedisCacheManager cacheMangager = RedisCacheManager .build(RedisCacheWriter.lockingRedisCacheWriter(connectionFactory)) - .cacheDefaults(RedisCacheConfiguration.defaultCacheConfig()) - ... + .cacheDefaults(RedisCacheConfiguration.defaultCacheConfig()) + ... ---- By default, any `key` for a cache entry gets prefixed with the actual cache name followed by two colons (`::`). @@ -69,17 +72,23 @@ 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 round trips: +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 round trips: [source,java] ---- RedisCacheManager cacheManager = RedisCacheManager .build(RedisCacheWriter.nonLockingRedisCacheWriter(connectionFactory, BatchStrategies.scan(1000))) .cacheDefaults(RedisCacheConfiguration.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. +[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`: @@ -138,9 +147,34 @@ Use `RedisCacheManagerBuilder.enableStatistics()` to collect local _hits_ and _m [[redis:support:cache-abstraction:expiration]] == Redis Cache Expiration -Spring Data Redis's `Cache` implementation supports _time-to-live_ (TTL) expiration on cache entries. Users can either configure the TTL expiration timeout with a fixed `Duration` or a dynamically computed `Duration` per cache entry by supplying an implementation of the new `RedisCacheWriter.TtlFunction` interface. +The implementation of time-to-idle (TTI) as well as time-to-live (TTL) varies in definition and behavior even across different data stores. -> TIP: The `RedisCacheWriter.TtlFunction` interface was introduced in Spring Data Redis `3.2.0`. +In general: + +* _time-to-live_ (TTL) _expiration_ - TTL is only set and reset by a create or update data access operation. +As long as the entry is written before the TTL expiration timeout, including on creation, an entry's timeout will reset to the configured duration of the TTL expiration timeout. +For example, if the TTL expiration timeout is set to 5 minutes, then the timeout will be set to 5 minutes on entry creation and reset to 5 minutes anytime the entry is updated thereafter and before the 5-minute interval expires. +If no update occurs within 5 minutes, even if the entry was read several times, or even just read once during the 5-minute interval, the entry will still expire. +The entry must be written to prevent the entry from expiring when declaring a TTL expiration policy. + +* _time-to-idle_ (TTI) _expiration_ - TTI is reset anytime the entry is also read as well as for entry updates, and is effectively and extension to the TTL expiration policy. + +[NOTE] +==== +Some data stores expire an entry when TTL is configured no matter what type of data access operation occurs on the entry (reads, writes, or otherwise). +After the set, configured TTL expiration timeout, the entry is evicted from the data store regardless. Eviction actions (for example: destroy, invalidate, overflow-to-disk (for persistent stores), etc.) are data store specific. +==== + +[[redis:support:cache-abstraction:expiration:tti]] +=== Time-To-Live (TTL) Expiration + +Spring Data Redis's `Cache` implementation supports _time-to-live_ (TTL) expiration on cache entries. +Users can either configure the TTL expiration timeout with a fixed `Duration` or a dynamically computed `Duration` per cache entry by supplying an implementation of the new `RedisCacheWriter.TtlFunction` interface. + +[TIP] +==== +The `RedisCacheWriter.TtlFunction` interface was introduced in Spring Data Redis `3.2.0`. +==== If all cache entries should expire after a set duration of time, then simply configure a TTL expiration timeout with a fixed `Duration`, as follows: @@ -156,15 +190,18 @@ However, if the TTL expiration timeout should vary by cache entry, then you must ---- class MyCustomTtlFunction implements TtlFunction { - static final MyCustomTtlFunction INSTANCE = new MyCustomTtlFunction(); + static final MyCustomTtlFunction INSTANCE = new MyCustomTtlFunction(); - public Duration getTimeToLive(Object key, @Nullable Object value) { - // compute a TTL expiration timeout (Duration) based on the cache entry key and/or value - } + public Duration getTimeToLive(Object key, @Nullable Object value) { + // compute a TTL expiration timeout (Duration) based on the cache entry key and/or value + } } ---- -> NOTE: Under-the-hood, a fixed `Duration` TTL expiration is wrapped in a `TtlFunction` implementation returning the provided `Duration`. +[NOTE] +==== +Under-the-hood, a fixed `Duration` TTL expiration is wrapped in a `TtlFunction` implementation returning the provided `Duration`. +==== Then, you can either configure the fixed `Duration` or the dynamic, per-cache entry `Duration` TTL expiration on a global basis using: @@ -187,7 +224,10 @@ RedisCacheManager cacheManager = RedisCacheManager.builder(redisConnectionFactor .build(); ---- -> WARNING: If you try to set both a fixed `Duration` and dynamic, per-cache entry `Duration` TTL expiration using a custom `TtlFunction`, then last one wins! +[WARNING] +==== +If you try to set both a fixed `Duration` and dynamic, per-cache entry `Duration` TTL expiration using a custom `TtlFunction`, then last one wins! +==== Of course, you can combine both global and per-cache configuration using: @@ -204,19 +244,11 @@ RedisCacheManager cacheManager = RedisCacheManager.builder(redisConnectionFactor [[redis:support:cache-abstraction:expiration:tti]] === Time-To-Idle (TTI) Expiration -Redis itself does not support the concept of true, time-to-idle (TTI) expiration. Even across different data stores, the implementation of time-to-idle (TTI) as well as time-to-live (TTL) varies in definition and behavior. +Redis itself does not support the concept of true, time-to-idle (TTI) expiration. +Still, using Spring Data Redis's Cache implementation, it is possible to achieve time-to-idle (TTI) expiration-like behavior. -In general: - -* _time-to-live_ (TTL) _expiration_ - TTL is only set and reset by a create or update data access operation. As long as the entry is written before the TTL expiration timeout, including on creation, an entry's timeout will reset to the configured duration of the TTL expiration timeout. For example, if the TTL expiration timeout is set to 5 minutes, then the timeout will be set to 5 minutes on entry creation and reset to 5 minutes anytime the entry is updated thereafter and before the 5-minute interval expires. If no update occurs within 5 minutes, even if the entry was read several times, or even just read once during the 5-minute interval, the entry will still expire. The entry must be written to prevent the entry from expiring when declaring a TTL expiration policy. - -* _time-to-idle_ (TTI) _expiration_ - TTI is reset anytime the entry is also read as well as for entry updates, and is effectively and extension to the TTL expiration policy. - -> NOTE: Some data stores expire an entry when TTL is configured no matter what type of data access operation occurs on the entry (reads, writes, or otherwise). After the set, configured TTL expiration timeout, the entry is evicted from the data store regardless. Eviction actions (for example: destroy, invalidate, overflow-to-disk (for persistent stores), etc.) are data store specific. - -Using Spring Data Redis's Cache implementation, it is possible to achieve time-to-idle (TTI) expiration-like behavior. - -The configuration of TTI in Spring Data Redis's Cache implementation must be explicitly enabled, that is, is opt-in. Additionally, you must also provide TTL configuration using either a fixed `Duration` or a custom implementation of the `TtlFunction` interface as described above in <>. +The configuration of TTI in Spring Data Redis's Cache implementation must be explicitly enabled, that is, is opt-in. +Additionally, you must also provide TTL configuration using either a fixed `Duration` or a custom implementation of the `TtlFunction` interface as described above in <>. For example: @@ -226,34 +258,50 @@ For example: @EnableCaching class RedisConfiguration { - @Bean + @Bean RedisConnectionFactory redisConnectionFactory() { - // ... + // ... } - @Bean + @Bean RedisCacheConfiguration redisCacheConfiguration() { - return RedisCacheConfiguration.defaultCacheConfig() + return RedisCacheConfiguration.defaultCacheConfig() .entryTtl(Duration.ofMinutes(5)) .enableTimeToIdle(); } - @Bean + @Bean RedisCacheManager cacheManager(RedisConnectionFactory connectionFactory, RedisCacheConfiguraton cacheConfiguraton) { - return RedisCacheManager.builder(connectionFactory) + return RedisCacheManager.builder(connectionFactory) .cacheDefaults(cacheConfiguration) .build(); } } ---- -Because Redis servers do not implement a proper notion of TTI, then TTI can only be achieved with Redis commands accepting expiration options. In Redis, the "expiration" is technically a time-to-live (TTL) policy. However, TTL expiration can be passed when reading the value of a key thereby effectively resetting the TTL expiration timeout, as is now the case in Spring Data Redis's `Cache.get(key)` operation. +Because Redis servers do not implement a proper notion of TTI, then TTI can only be achieved with Redis commands accepting expiration options. +In Redis, the "expiration" is technically a time-to-live (TTL) policy. +However, TTL expiration can be passed when reading the value of a key thereby effectively resetting the TTL expiration timeout, as is now the case in Spring Data Redis's `Cache.get(key)` operation. `RedisCache.get(key)` is implemented by calling the Redis `GETEX` command. -> WARNING: The Redis https://redis.io/commands/getex[`GETEX`] command is only available in Redis version `6.2.0` and later. Therefore, if you are not using Redis `6.2.0` or later, then it is not possible to use Spring Data Redis's TTI expiration. A command execution exception will be thrown if you enable TTI against an incompatible Redis (server) version. No attempt is made to determine if the Redis server version is correct and supports the `GETEX` command. +[WARNING] +==== +The Redis https://redis.io/commands/getex[`GETEX`] command is only available in Redis version `6.2.0` and later. +Therefore, if you are not using Redis `6.2.0` or later, then it is not possible to use Spring Data Redis's TTI expiration. +A command execution exception will be thrown if you enable TTI against an incompatible Redis (server) version. +No attempt is made to determine if the Redis server version is correct and supports the `GETEX` command. +==== -> WARNING: In order to achieve true time-to-idle (TTI) expiration-like behavior in your Spring Data Redis application, then an entry must be consistently accessed with (TTL) expiration on every read or write operation. There are no exceptions to this rule. If you are mixing and matching different data access patterns across your Spring Data Redis application (for example: caching, invoking operations using `RedisTemplate` and possibly, or especially when using Spring Data Repository CRUD operations), then accessing an entry may not necessarily prevent the entry from expiring if TTL expiration was set. For example, an entry maybe "put" in (written to) the cache during a `@Cacheable` service method invocation with a TTL expiration (i.e. `SET `) and later read using a Spring Data Redis Repository before the expiration timeout (using `GET` without expiration options). A simple `GET` without specifying expiration options will not reset the TTL expiration timeout on an entry. Therefore, the entry may expire before the next data access operation, even though it was just read. Since this cannot be enforced in the Redis server, then it is the responsibility of your application to consistently access an entry when time-to-idle expiration is configured, in and outside of caching, where appropriate. +[WARNING] +==== +In order to achieve true time-to-idle (TTI) expiration-like behavior in your Spring Data Redis application, then an entry must be consistently accessed with (TTL) expiration on every read or write operation. +There are no exceptions to this rule. +If you are mixing and matching different data access patterns across your Spring Data Redis application (for example: caching, invoking operations using `RedisTemplate` and possibly, or especially when using Spring Data Repository CRUD operations), then accessing an entry may not necessarily prevent the entry from expiring if TTL expiration was set. +For example, an entry maybe "put" in (written to) the cache during a `@Cacheable` service method invocation with a TTL expiration (i.e. `SET `) and later read using a Spring Data Redis Repository before the expiration timeout (using `GET` without expiration options). +A simple `GET` without specifying expiration options will not reset the TTL expiration timeout on an entry. +Therefore, the entry may expire before the next data access operation, even though it was just read. Since this cannot be enforced in the Redis server, then it is the responsibility of your application to consistently access an entry when time-to-idle expiration is configured, in and outside of caching, where appropriate. +==== diff --git a/src/main/java/org/springframework/data/redis/cache/RedisCacheConfiguration.java b/src/main/java/org/springframework/data/redis/cache/RedisCacheConfiguration.java index 8870261e1..a46eb63f7 100644 --- a/src/main/java/org/springframework/data/redis/cache/RedisCacheConfiguration.java +++ b/src/main/java/org/springframework/data/redis/cache/RedisCacheConfiguration.java @@ -218,6 +218,8 @@ public class RedisCacheConfiguration { * is applied to all {@link Cache} operations, both read and write alike, and {@link Cache} operations passed with * expiration are used consistently across the application, then in effect, an application can achieve * {@literal TTI} expiration-like behavior. + *

+ * Requires Redis 6.2.0 or newer. * * @return this {@link RedisCacheConfiguration}. * @see GETEX diff --git a/src/test/java/org/springframework/data/redis/cache/RedisCacheTests.java b/src/test/java/org/springframework/data/redis/cache/RedisCacheTests.java index dc8da3695..5d4268966 100644 --- a/src/test/java/org/springframework/data/redis/cache/RedisCacheTests.java +++ b/src/test/java/org/springframework/data/redis/cache/RedisCacheTests.java @@ -15,10 +15,11 @@ */ package org.springframework.data.redis.cache; -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatIllegalStateException; -import static org.assertj.core.api.Assumptions.assumeThat; -import static org.awaitility.Awaitility.await; +import static org.assertj.core.api.Assertions.*; +import static org.assertj.core.api.Assumptions.*; +import static org.awaitility.Awaitility.*; + +import io.netty.util.concurrent.DefaultThreadFactory; import java.io.Serializable; import java.nio.charset.StandardCharsets; @@ -38,7 +39,6 @@ import java.util.function.Function; import java.util.stream.IntStream; import org.junit.jupiter.api.BeforeEach; - import org.springframework.cache.Cache.ValueWrapper; import org.springframework.cache.interceptor.SimpleKey; import org.springframework.cache.interceptor.SimpleKeyGenerator; @@ -53,8 +53,6 @@ import org.springframework.data.redis.test.extension.parametrized.MethodSource; import org.springframework.data.redis.test.extension.parametrized.ParameterizedRedisTest; import org.springframework.lang.Nullable; -import io.netty.util.concurrent.DefaultThreadFactory; - /** * Tests for {@link RedisCache} with {@link DefaultRedisCacheWriter} using different {@link RedisSerializer} and * {@link RedisConnectionFactory} pairs. @@ -100,21 +98,6 @@ public class RedisCacheTests { this.cache = new RedisCache("cache", usingRedisCacheWriter(), usingRedisCacheConfiguration()); } - private RedisCacheWriter usingRedisCacheWriter() { - return RedisCacheWriter.nonLockingRedisCacheWriter(this.connectionFactory); - } - - private RedisCacheConfiguration usingRedisCacheConfiguration() { - return usingRedisCacheConfiguration(Function.identity()); - } - - private RedisCacheConfiguration usingRedisCacheConfiguration( - Function customizer) { - - return customizer.apply(RedisCacheConfiguration.defaultCacheConfig() - .serializeValuesWith(SerializationPair.fromSerializer(this.serializer))); - } - @ParameterizedRedisTest // DATAREDIS-481 void putShouldAddEntry() { @@ -554,7 +537,7 @@ public class RedisCacheTests { @ParameterizedRedisTest // GH-2351 void cacheGetWithTimeToIdleExpirationWhenEntryNotExpiredShouldReturnValue() { - doWithConnection(connection -> connection.set(this.binaryCacheKey, this.binarySample)); + doWithConnection(connection -> connection.stringCommands().set(this.binaryCacheKey, this.binarySample)); RedisCache cache = new RedisCache("cache", usingRedisCacheWriter(), usingRedisCacheConfiguration(withTtiExpiration())); @@ -562,6 +545,7 @@ public class RedisCacheTests { assertThat(unwrap(cache.get(this.key))).isEqualTo(this.sample); for (int count = 0; count < 5; count++) { + await().atMost(Duration.ofMillis(100)); assertThat(unwrap(cache.get(this.key))).isEqualTo(this.sample); } @@ -571,7 +555,7 @@ public class RedisCacheTests { @ParameterizedRedisTest // GH-2351 void cacheGetWithTimeToIdleExpirationAfterEntryExpiresShouldReturnNull() { - doWithConnection(connection -> connection.set(this.binaryCacheKey, this.binarySample)); + doWithConnection(connection -> connection.stringCommands().set(this.binaryCacheKey, this.binarySample)); RedisCache cache = new RedisCache("cache", usingRedisCacheWriter(), usingRedisCacheConfiguration(withTtiExpiration())); @@ -588,6 +572,21 @@ public class RedisCacheTests { return value instanceof ValueWrapper wrapper ? wrapper.get() : value; } + private RedisCacheWriter usingRedisCacheWriter() { + return RedisCacheWriter.nonLockingRedisCacheWriter(this.connectionFactory); + } + + private RedisCacheConfiguration usingRedisCacheConfiguration() { + return usingRedisCacheConfiguration(Function.identity()); + } + + private RedisCacheConfiguration usingRedisCacheConfiguration( + Function customizer) { + + return customizer.apply(RedisCacheConfiguration.defaultCacheConfig() + .serializeValuesWith(SerializationPair.fromSerializer(this.serializer))); + } + private Function withTtiExpiration() { Function entryTtlFunction =