Package org.springframework.data.redis.cache

Interface RedisCacheWriter

All Superinterfaces:
CacheStatisticsProvider
public interface RedisCacheWriter extends CacheStatisticsProvider
RedisCacheWriter provides low-level access to Redis commands (SET, SETNX, GET, EXPIRE,...) used for caching.

The RedisCacheWriter may be shared by multiple cache implementations and is responsible for reading/writing binary data from/to Redis. The implementation honors potential cache lock flags that might be set.

The default RedisCacheWriter implementation can be customized with BatchStrategy to tune performance behavior.

Since:
2.0
Author:
Christoph Strobl, Mark Paluch, John Blum

  • Method Details

    • create

      static RedisCacheWriter create(RedisConnectionFactory connectionFactory, Consumer<RedisCacheWriter.RedisCacheWriterConfigurer> configurerConsumer)
      Create new RedisCacheWriter configure it through RedisCacheWriter.RedisCacheWriterConfigurer. The cache writer defaults does not lock the cache by default using BatchStrategies.keys().
      Parameters:
      connectionFactory - the connection factory to use.
      configurerConsumer - a configuration function that configures RedisCacheWriter.RedisCacheWriterConfigurer.
      Returns:
      new instance of DefaultRedisCacheWriter.
      Since:
      4.0

    • nonLockingRedisCacheWriter

      static RedisCacheWriter nonLockingRedisCacheWriter(RedisConnectionFactory connectionFactory)
      Create new RedisCacheWriter without locking behavior using BatchStrategies.keys().
      Parameters:
      connectionFactory - must not be null.
      Returns:
      new instance of DefaultRedisCacheWriter.

    • nonLockingRedisCacheWriter

      static RedisCacheWriter nonLockingRedisCacheWriter(RedisConnectionFactory connectionFactory, BatchStrategy batchStrategy)
      Create new RedisCacheWriter without locking behavior.
      Parameters:
      connectionFactory - must not be null.
      batchStrategy - must not be null.
      Returns:
      new instance of DefaultRedisCacheWriter.
      Since:
      2.6

    • lockingRedisCacheWriter

      static RedisCacheWriter lockingRedisCacheWriter(RedisConnectionFactory connectionFactory)
      Create new RedisCacheWriter with locking behavior using BatchStrategies.keys().
      Parameters:
      connectionFactory - must not be null.
      Returns:
      new instance of DefaultRedisCacheWriter.

    • lockingRedisCacheWriter

      static RedisCacheWriter lockingRedisCacheWriter(RedisConnectionFactory connectionFactory, BatchStrategy batchStrategy)
      Create new RedisCacheWriter with locking behavior.
      Parameters:
      connectionFactory - must not be null.
      batchStrategy - must not be null.
      Returns:
      new instance of DefaultRedisCacheWriter.
      Since:
      2.6

    • lockingRedisCacheWriter

      static RedisCacheWriter lockingRedisCacheWriter(RedisConnectionFactory connectionFactory, Duration sleepTime, RedisCacheWriter.TtlFunction lockTtlFunction, BatchStrategy batchStrategy)
      Create new RedisCacheWriter with locking behavior.
      Parameters:
      connectionFactory - must not be null.
      sleepTime - sleep time between lock access attempts, must not be null.
      lockTtlFunction - TTL function to compute the Lock TTL. The function is called with contextual keys and values (such as the cache name on cleanup or the actual key/value on put requests); must not be null.
      batchStrategy - must not be null.
      Returns:
      new instance of DefaultRedisCacheWriter.
      Since:
      3.2

    • get

      byte @Nullable [] get(String name, byte[] key)
      Get the binary value representation from Redis stored for the given key.
      Parameters:
      name - must not be null.
      key - must not be null.
      Returns:
      null if key does not exist.
      See Also:

    • get

      default byte @Nullable [] get(String name, byte[] key, @Nullable Duration ttl)
      Get the binary value representation from Redis stored for the given key and set the given TTL expiration for the cache entry.
      Parameters:
      name - must not be null.
      key - must not be null.
      ttl - Duration specifying the expiration timeout for the cache entry.
      Returns:
      null if key does not exist or has expired.

    • get

      default byte[] get(String name, byte[] key, Supplier<byte[]> valueLoader, @Nullable Duration ttl, boolean timeToIdleEnabled)
      Get the binary value representation from Redis stored for the given key and set the given TTL expiration for the cache entry, obtaining the value from valueLoader if necessary.

      If possible (and configured for locking), implementations should ensure that the loading operation is synchronized so that the specified valueLoader is only called once in case of concurrent access on the same key.

      Parameters:
      name - must not be null.
      key - must not be null.
      valueLoader - value loader that creates the value if the cache lookup has been not successful.
      ttl - Duration specifying the expiration timeout for the cache entry.
      timeToIdleEnabled - true to enable Time to Idle when retrieving the value.
      Since:
      3.4

    • supportsAsyncRetrieve

      default boolean supportsAsyncRetrieve()
      Determines whether the asynchronous retrieve(String, byte[]) and retrieve(String, byte[], Duration) cache operations are supported by the implementation.

      The main factor for whether the retrieve operation can be supported will primarily be determined by the Redis driver in use at runtime.

      Returns false by default. This will have an effect of RedisCache.retrieve(Object) and RedisCache.retrieve(Object, Supplier) throwing an UnsupportedOperationException.

      Returns:
      true if asynchronous retrieve operations are supported by the implementation.
      Since:
      3.2

    • retrieve

      default CompletableFuture<byte[]> retrieve(String name, byte[] key)
      Asynchronously retrieves the value to which the RedisCache maps the given byte[] key.

      This operation is non-blocking.

      Parameters:
      name - String with the name of the RedisCache.
      key - byte[] key mapped to the value in the RedisCache.
      Returns:
      the value to which the RedisCache maps the given byte[] key.
      Since:
      3.2
      See Also:

    • retrieve

      CompletableFuture<byte[]> retrieve(String name, byte[] key, @Nullable Duration ttl)
      Asynchronously retrieves the value to which the RedisCache maps the given byte[] key setting the TTL expiration for the cache entry.

      This operation is non-blocking.

      Parameters:
      name - String with the name of the RedisCache.
      key - byte[] key mapped to the value in the RedisCache.
      ttl - Duration specifying the expiration timeout for the cache entry.
      Returns:
      the value to which the RedisCache maps the given byte[] key.
      Since:
      3.2

    • put

      void put(String name, byte[] key, byte[] value, @Nullable Duration ttl)
      Write the given key/value pair to Redis and set the expiration time if defined.
      Parameters:
      name - cache name must not be null.
      key - key for the cache entry. Must not be null.
      value - value stored for the key. Must not be null.
      ttl - optional expiration time. Can be null.

    • store

      CompletableFuture<Void> store(String name, byte[] key, byte[] value, @Nullable Duration ttl)
      Store the given key/value pair asynchronously to Redis and set the expiration time if defined.

      This operation is non-blocking.

      Parameters:
      name - cache name must not be null.
      key - key for the cache entry. Must not be null.
      value - value stored for the key. Must not be null.
      ttl - optional expiration time. Can be null.
      Since:
      3.2

    • putIfAbsent

      byte @Nullable [] putIfAbsent(String name, byte[] key, byte[] value, @Nullable Duration ttl)
      Write the given value to Redis if the key does not already exist.
      Parameters:
      name - cache name must not be null.
      key - key for the cache entry. Must not be null.
      value - value stored for the key. Must not be null.
      ttl - optional expiration time. Can be null.
      Returns:
      null if the value has been written, the value stored for the key if it already exists.

    • remove

      @Deprecated(since="4.0", forRemoval=true) default void remove(String name, byte[] key)
      Deprecated, for removal: This API element is subject to removal in a future version.
      since 4.0 in favor of evict(String, byte[])
      Remove the given key from Redis.

      Actual eviction may be performed in an asynchronous or deferred fashion, with subsequent lookups possibly still seeing the entry.

      Parameters:
      name - cache name must not be null.
      key - key for the cache entry. Must not be null.

    • evict

      void evict(String name, byte[] key)
      Remove the given key from Redis.

      Actual eviction may be performed in an asynchronous or deferred fashion, with subsequent lookups possibly still seeing the entry.

      Parameters:
      name - cache name must not be null.
      key - key for the cache entry. Must not be null.
      Since:
      4.0

    • evictIfPresent

      default boolean evictIfPresent(String name, byte[] key)
      Remove the given key from Redis if it is present, expecting the key to be immediately invisible for subsequent lookups.
      Parameters:
      name - cache name must not be null.
      key - key for the cache entry. Must not be null.
      Returns:
      true if the cache was known to have a mapping for this key before, false if it did not (or if prior presence could not be determined).
      Since:
      4.0

    • clean

      @Deprecated(since="4.0", forRemoval=true) default void clean(String name, byte[] pattern)
      Deprecated, for removal: This API element is subject to removal in a future version.
      since 4.0 in favor of clear(String, byte[])
      Remove all keys following the given pattern.

      Actual clearing may be performed in an asynchronous or deferred fashion, with subsequent lookups possibly still seeing the entries.

      Parameters:
      name - cache name must not be null.
      pattern - pattern for the keys to remove. Must not be null.

    • clear

      void clear(String name, byte[] pattern)
      Remove all keys following the given pattern.

      Actual clearing may be performed in an asynchronous or deferred fashion, with subsequent lookups possibly still seeing the entries.

      Parameters:
      name - cache name must not be null.
      pattern - pattern for the keys to remove. Must not be null.
      Since:
      4.0

    • invalidate

      default boolean invalidate(String name, byte[] pattern)
      Remove all keys following the given pattern expecting all entries to be immediately invisible for subsequent lookups.
      Parameters:
      name - cache name must not be null.
      pattern - pattern for the keys to remove. Must not be null.
      Returns:
      true if the cache was known to have mappings before, false if it did not (or if prior presence of entries could not be determined).

    • clearStatistics

      void clearStatistics(String name)
      Reset all statistics counters and gauges for this cache.
      Since:
      2.4

    • withStatisticsCollector

      RedisCacheWriter withStatisticsCollector(CacheStatisticsCollector cacheStatisticsCollector)
      Obtain a RedisCacheWriter using the given CacheStatisticsCollector to collect metrics.
      Parameters:
      cacheStatisticsCollector - must not be null.
      Returns:
      new instance of RedisCacheWriter.