Package io.valkey.springframework.data.valkey.cache

Interface ValkeyCacheWriter

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

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

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

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

  • Method Details

    • create

      static ValkeyCacheWriter create(ValkeyConnectionFactory connectionFactory, Consumer<ValkeyCacheWriter.ValkeyCacheWriterConfigurer> configurerConsumer)
      Create new ValkeyCacheWriter configure it through ValkeyCacheWriter.ValkeyCacheWriterConfigurer. 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 ValkeyCacheWriter.ValkeyCacheWriterConfigurer.
      Returns:
      new instance of DefaultValkeyCacheWriter.
      Since:
      4.0

    • nonLockingValkeyCacheWriter

      static ValkeyCacheWriter nonLockingValkeyCacheWriter(ValkeyConnectionFactory connectionFactory)
      Create new ValkeyCacheWriter without locking behavior using BatchStrategies.keys().
      Parameters:
      connectionFactory - must not be null.
      Returns:
      new instance of DefaultValkeyCacheWriter.

    • nonLockingValkeyCacheWriter

      static ValkeyCacheWriter nonLockingValkeyCacheWriter(ValkeyConnectionFactory connectionFactory, BatchStrategy batchStrategy)
      Create new ValkeyCacheWriter without locking behavior.
      Parameters:
      connectionFactory - must not be null.
      batchStrategy - must not be null.
      Returns:
      new instance of DefaultValkeyCacheWriter.
      Since:
      2.6

    • lockingValkeyCacheWriter

      static ValkeyCacheWriter lockingValkeyCacheWriter(ValkeyConnectionFactory connectionFactory)
      Create new ValkeyCacheWriter with locking behavior using BatchStrategies.keys().
      Parameters:
      connectionFactory - must not be null.
      Returns:
      new instance of DefaultValkeyCacheWriter.

    • lockingValkeyCacheWriter

      static ValkeyCacheWriter lockingValkeyCacheWriter(ValkeyConnectionFactory connectionFactory, BatchStrategy batchStrategy)
      Create new ValkeyCacheWriter with locking behavior.
      Parameters:
      connectionFactory - must not be null.
      batchStrategy - must not be null.
      Returns:
      new instance of DefaultValkeyCacheWriter.
      Since:
      2.6

    • lockingValkeyCacheWriter

      static ValkeyCacheWriter lockingValkeyCacheWriter(ValkeyConnectionFactory connectionFactory, Duration sleepTime, ValkeyCacheWriter.TtlFunction lockTtlFunction, BatchStrategy batchStrategy)
      Create new ValkeyCacheWriter 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 DefaultValkeyCacheWriter.
      Since:
      3.2

    • get

      byte @Nullable [] get(String name, byte[] key)
      Get the binary value representation from Valkey 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 Valkey 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 Valkey 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 Valkey driver in use at runtime.

      Returns false by default. This will have an effect of ValkeyCache.retrieve(Object) and ValkeyCache.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 ValkeyCache maps the given byte[] key.

      This operation is non-blocking.

      Parameters:
      name - String with the name of the ValkeyCache.
      key - byte[] key mapped to the value in the ValkeyCache.
      Returns:
      the value to which the ValkeyCache 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 ValkeyCache 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 ValkeyCache.
      key - byte[] key mapped to the value in the ValkeyCache.
      ttl - Duration specifying the expiration timeout for the cache entry.
      Returns:
      the value to which the ValkeyCache 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 Valkey 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 Valkey 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 Valkey 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 Valkey.

      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 Valkey.

      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 Valkey 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

    • execute

      default <T extends @Nullable Object> T execute(Function<ValkeyConnection,T> callback)
      Executes the given Function with a ValkeyConnection.
      Type Parameters:
      T -
      Parameters:
      callback - the callback action to invoke with a connection.
      Returns:
      return value of the callback.
      Throws:
      UnsupportedOperationException - if the cache writer does not support direct access to ValkeyConnection.
      Since:
      4.1

    • withStatisticsCollector

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