Module lettuce.core
Package io.lettuce.core.cluster

Class RedisClusterClient

java.lang.Object
io.lettuce.core.AbstractRedisClient
io.lettuce.core.cluster.RedisClusterClient
public class RedisClusterClient
extends AbstractRedisClient
A scalable and thread-safe Redis cluster client supporting synchronous, asynchronous and reactive execution models. Multiple threads may share one connection. The cluster client handles command routing based on the first key of the command and maintains a view of the cluster that is available when calling the getPartitions() method.

Connections to the cluster members are opened on the first access to the cluster node and managed by the StatefulRedisClusterConnection. You should not use transactional commands on cluster connections since MULTI, EXEC and DISCARD have no key and cannot be assigned to a particular node. A cluster connection uses a default connection to run non-keyed commands.

The Redis cluster client provides a sync, async and reactive API.

Connections to particular nodes can be obtained by StatefulRedisClusterConnection.getConnection(String) providing the node id or StatefulRedisClusterConnection.getConnection(String, int) by host and port.

Multiple keys operations have to operate on a key that hashes to the same slot. Following commands do not need to follow that rule since they are pipelined according to its hash value to multiple nodes in parallel on the sync, async and, reactive API:

Following commands on the Cluster sync, async and, reactive API are implemented with a Cluster-flavor:

Cluster commands can be issued to multiple hosts in parallel by using the NodeSelectionSupport API. A set of nodes is selected using a Predicate and commands can be issued to the node selection 

 AsyncExecutions<String> ping = commands.upstream().commands().ping();
 Collection<RedisClusterNode> nodes = ping.nodes();
 nodes.stream().forEach(redisClusterNode -> ping.get(redisClusterNode));

RedisClusterClient is an expensive resource. Reuse this instance or share external ClientResources as much as possible.
Since:
3.0
Author:
Mark Paluch
See Also:
RedisURI, StatefulRedisClusterConnection, RedisCodec, ClusterClientOptions, ClientResources

  • Constructor Details

    • RedisClusterClient

      protected RedisClusterClient()
      Non-private constructor to make RedisClusterClient proxyable.

    • RedisClusterClient

      protected RedisClusterClient​(ClientResources clientResources, Iterable<RedisURI> redisURIs)
      Initialize the client with a list of cluster URI's. All uris are tried in sequence for connecting initially to the cluster. If any uri is successful for connection, the others are not tried anymore. The initial uri is needed to discover the cluster structure for distributing the requests.
      Parameters:
      clientResources - the client resources. If null, the client will create a new dedicated instance of client resources and keep track of them.
      redisURIs - iterable of initial cluster URIs. Must not be null and not empty.

  • Method Details

    • create

      public static RedisClusterClient create​(RedisURI redisURI)
      Create a new client that connects to the supplied uri with default ClientResources. You can connect to different Redis servers but you must supply a RedisURI on connecting.
      Parameters:
      redisURI - the Redis URI, must not be null
      Returns:
      a new instance of RedisClusterClient

    • create

      public static RedisClusterClient create​(Iterable<RedisURI> redisURIs)
      Create a new client that connects to the supplied uri with default ClientResources. You can connect to different Redis servers but you must supply a RedisURI on connecting.
      Parameters:
      redisURIs - one or more Redis URI, must not be null and not empty.
      Returns:
      a new instance of RedisClusterClient

    • create

      public static RedisClusterClient create​(String uri)
      Create a new client that connects to the supplied uri with default ClientResources. You can connect to different Redis servers but you must supply a RedisURI on connecting.
      Parameters:
      uri - the Redis URI, must not be empty or null.
      Returns:
      a new instance of RedisClusterClient

    • create

      public static RedisClusterClient create​(ClientResources clientResources, RedisURI redisURI)
      Create a new client that connects to the supplied uri with shared ClientResources. You need to shut down the ClientResources upon shutting down your application.You can connect to different Redis servers but you must supply a RedisURI on connecting.
      Parameters:
      clientResources - the client resources, must not be null
      redisURI - the Redis URI, must not be null
      Returns:
      a new instance of RedisClusterClient

    • create

      public static RedisClusterClient create​(ClientResources clientResources, String uri)
      Create a new client that connects to the supplied uri with shared ClientResources.You need to shut down the ClientResources upon shutting down your application. You can connect to different Redis servers but you must supply a RedisURI on connecting.
      Parameters:
      clientResources - the client resources, must not be null
      uri - the Redis URI, must not be empty or null.
      Returns:
      a new instance of RedisClusterClient

    • create

      public static RedisClusterClient create​(ClientResources clientResources, Iterable<RedisURI> redisURIs)
      Create a new client that connects to the supplied uri with shared ClientResources. You need to shut down the ClientResources upon shutting down your application.You can connect to different Redis servers but you must supply a RedisURI on connecting.
      Parameters:
      clientResources - the client resources, must not be null
      redisURIs - one or more Redis URI, must not be null and not empty
      Returns:
      a new instance of RedisClusterClient

    • setOptions

      public void setOptions​(ClusterClientOptions clientOptions)
      Set the ClusterClientOptions for the client.
      Parameters:
      clientOptions - client options for the client and connections that are created after setting the options

    • getPartitions

      public Partitions getPartitions()
      Retrieve the cluster view. Partitions are shared amongst all connections opened by this client instance.
      Returns:
      the partitions.

    • getTopologyRefreshSource

      protected Iterable<RedisURI> getTopologyRefreshSource()
      Returns the seed RedisURI for the topology refreshing. This method is called before each topology refresh to provide an Iterable of RedisURI that is used to perform the next topology refresh.

      Subclasses of RedisClusterClient may override that method.

      Returns:
      Iterable of RedisURI for the next topology refresh.

    • connect

      public StatefulRedisClusterConnection<String,​String> connect()
      Connect to a Redis Cluster and treat keys and values as UTF-8 strings.

      What to expect from this connection:

      • A default connection is created to the node with the lowest latency
      • Keyless commands are send to the default connection
      • Single-key keyspace commands are routed to the appropriate node
      • Multi-key keyspace commands require the same slot-hash and are routed to the appropriate node
      • Pub/sub commands are sent to the node that handles the slot derived from the pub/sub channel
      Returns:
      A new stateful Redis Cluster connection

    • connect

      public <K,​ V> StatefulRedisClusterConnection<K,​V> connect​(RedisCodec<K,​V> codec)
      Connect to a Redis Cluster. Use the supplied codec to encode/decode keys and values.

      What to expect from this connection:

      • A default connection is created to the node with the lowest latency
      • Keyless commands are send to the default connection
      • Single-key keyspace commands are routed to the appropriate node
      • Multi-key keyspace commands require the same slot-hash and are routed to the appropriate node
      • Pub/sub commands are sent to the node that handles the slot derived from the pub/sub channel
      Type Parameters:
      K - Key type
      V - Value type
      Parameters:
      codec - Use this codec to encode/decode keys and values, must not be null
      Returns:
      A new stateful Redis Cluster connection

    • connectAsync

      public <K,​ V> CompletableFuture<StatefulRedisClusterConnection<K,​V>> connectAsync​(RedisCodec<K,​V> codec)
      Connect asynchronously to a Redis Cluster. Use the supplied codec to encode/decode keys and values. Connecting asynchronously requires an initialized topology. Call getPartitions() first, otherwise the connect will fail with aIllegalStateException.

      What to expect from this connection:

      • A default connection is created to the node with the lowest latency
      • Keyless commands are send to the default connection
      • Single-key keyspace commands are routed to the appropriate node
      • Multi-key keyspace commands require the same slot-hash and are routed to the appropriate node
      • Pub/sub commands are sent to the node that handles the slot derived from the pub/sub channel
      Type Parameters:
      K - Key type
      V - Value type
      Parameters:
      codec - Use this codec to encode/decode keys and values, must not be null
      Returns:
      a CompletableFuture that is notified with the connection progress.
      Since:
      5.1

    • connectPubSub

      public StatefulRedisClusterPubSubConnection<String,​String> connectPubSub()
      Connect to a Redis Cluster using pub/sub connections and treat keys and values as UTF-8 strings.

      What to expect from this connection:

      • A default connection is created to the node with the least number of clients
      • Pub/sub commands are sent to the node with the least number of clients
      • Keyless commands are send to the default connection
      • Single-key keyspace commands are routed to the appropriate node
      • Multi-key keyspace commands require the same slot-hash and are routed to the appropriate node
      Returns:
      A new stateful Redis Cluster connection

    • connectPubSub

      public <K,​ V> StatefulRedisClusterPubSubConnection<K,​V> connectPubSub​(RedisCodec<K,​V> codec)
      Connect to a Redis Cluster using pub/sub connections. Use the supplied codec to encode/decode keys and values.

      What to expect from this connection:

      • A default connection is created to the node with the least number of clients
      • Pub/sub commands are sent to the node with the least number of clients
      • Keyless commands are send to the default connection
      • Single-key keyspace commands are routed to the appropriate node
      • Multi-key keyspace commands require the same slot-hash and are routed to the appropriate node
      Type Parameters:
      K - Key type
      V - Value type
      Parameters:
      codec - Use this codec to encode/decode keys and values, must not be null
      Returns:
      A new stateful Redis Cluster connection

    • connectPubSubAsync

      public <K,​ V> CompletableFuture<StatefulRedisClusterPubSubConnection<K,​V>> connectPubSubAsync​(RedisCodec<K,​V> codec)
      Connect asynchronously to a Redis Cluster using pub/sub connections. Use the supplied codec to encode/decode keys and values. Connecting asynchronously requires an initialized topology. Call getPartitions() first, otherwise the connect will fail with aIllegalStateException.

      What to expect from this connection:

      • A default connection is created to the node with the least number of clients
      • Pub/sub commands are sent to the node with the least number of clients
      • Keyless commands are send to the default connection
      • Single-key keyspace commands are routed to the appropriate node
      • Multi-key keyspace commands require the same slot-hash and are routed to the appropriate node
      Type Parameters:
      K - Key type
      V - Value type
      Parameters:
      codec - Use this codec to encode/decode keys and values, must not be null
      Returns:
      a CompletableFuture that is notified with the connection progress.
      Since:
      5.1

    • newStatefulRedisConnection

      protected <K,​ V> StatefulRedisConnectionImpl<K,​V> newStatefulRedisConnection​(RedisChannelWriter channelWriter, PushHandler pushHandler, RedisCodec<K,​V> codec, Duration timeout)
      Create a new instance of StatefulRedisConnectionImpl or a subclass.

      Subclasses of RedisClusterClient may override that method.

      Type Parameters:
      K - Key-Type
      V - Value Type
      Parameters:
      channelWriter - the channel writer
      pushHandler - the handler for push notifications
      codec - codec
      timeout - default timeout
      Returns:
      new instance of StatefulRedisConnectionImpl

    • newStatefulRedisClusterConnection

      protected <V,​ K> StatefulRedisClusterConnectionImpl<K,​V> newStatefulRedisClusterConnection​(RedisChannelWriter channelWriter, ClusterPushHandler pushHandler, RedisCodec<K,​V> codec, Duration timeout)
      Create a new instance of StatefulRedisClusterConnectionImpl or a subclass.

      Subclasses of RedisClusterClient may override that method.

      Type Parameters:
      K - Key-Type
      V - Value Type
      Parameters:
      channelWriter - the channel writer
      pushHandler - the handler for push notifications
      codec - codec
      timeout - default timeout
      Returns:
      new instance of StatefulRedisClusterConnectionImpl

    • reloadPartitions

      @Deprecated public void reloadPartitions()
      Deprecated.
      since 6.0. Renamed to refreshPartitions().
      Refresh partitions and re-initialize the routing table.

    • refreshPartitions

      public void refreshPartitions()
      Refresh partitions and re-initialize the routing table.
      Since:
      6.0

    • refreshPartitionsAsync

      public CompletionStage<Void> refreshPartitionsAsync()
      Asynchronously reload partitions and re-initialize the distribution table.
      Returns:
      a CompletionStage that signals completion.
      Since:
      6.0

    • updatePartitionsInConnections

      protected void updatePartitionsInConnections()

    • initializePartitions

      protected CompletableFuture<Partitions> initializePartitions()

    • loadPartitions

      protected Partitions loadPartitions()
      Retrieve partitions. Nodes within Partitions are ordered by latency. Lower latency nodes come first.
      Returns:
      Partitions

    • loadPartitionsAsync

      protected CompletableFuture<Partitions> loadPartitionsAsync()
      Retrieve partitions. Nodes within Partitions are ordered by latency. Lower latency nodes come first.
      Returns:
      future that emits Partitions upon a successful topology lookup.
      Since:
      6.0

    • determinePartitions

      protected Partitions determinePartitions​(Partitions current, Map<RedisURI,​Partitions> topologyViews)
      Determines a topology view based on the current and the obtain topology views.
      Parameters:
      current - the current topology view. May be null if RedisClusterClient has no topology view yet.
      topologyViews - the obtain topology views
      Returns:
      the topology view to use.

    • setPartitions

      public void setPartitions​(Partitions partitions)
      Sets the new cluster topology. The partitions are not applied to existing connections.
      Parameters:
      partitions - partitions object

    • shutdownAsync

      public CompletableFuture<Void> shutdownAsync​(long quietPeriod, long timeout, TimeUnit timeUnit)
      Shutdown this client and close all open connections asynchronously. The client should be discarded after calling shutdown.
      Overrides:
      shutdownAsync in class AbstractRedisClient
      Parameters:
      quietPeriod - the quiet period as described in the documentation
      timeout - the maximum amount of time to wait until the executor is shutdown regardless if a task was submitted during the quiet period
      timeUnit - the unit of quietPeriod and timeout
      Since:
      4.4
      See Also:
      EventExecutorGroup.shutdownGracefully(long, long, TimeUnit)

    • getFirstUri

      protected RedisURI getFirstUri()
      Returns the first RedisURI configured with this RedisClusterClient instance.
      Returns:
      the first RedisURI.

    • getSocketAddressSupplier

      protected Mono<SocketAddress> getSocketAddressSupplier​(Supplier<Partitions> partitionsSupplier, Function<Partitions,​Collection<RedisClusterNode>> sortFunction)
      Returns a Supplier for connection points.
      Parameters:
      sortFunction - Sort function to enforce a specific order. The sort function must not change the order or the input parameter but create a new collection with the desired order, must not be null.
      Returns:
      Supplier for connection points.

    • getInitialUris

      protected Iterable<RedisURI> getInitialUris()
      Returns an Iterable of the initial URIs.
      Returns:
      the initial URIs

    • forEachClusterConnection

      protected void forEachClusterConnection​(Consumer<StatefulRedisClusterConnectionImpl<?,​?>> function)
      Apply a Consumer of StatefulRedisClusterConnectionImpl to all active connections.
      Parameters:
      function - the Consumer.

    • forEachClusterPubSubConnection

      protected void forEachClusterPubSubConnection​(Consumer<io.lettuce.core.cluster.StatefulRedisClusterPubSubConnectionImpl<?,​?>> function)
      Apply a Consumer of StatefulRedisClusterPubSubConnectionImpl to all active connections.
      Parameters:
      function - the Consumer.

    • forEachCloseable

      protected <T extends Closeable> void forEachCloseable​(Predicate<? super Closeable> selector, Consumer<T> function)
      Apply a Consumer of Closeable to all active connections.
      Type Parameters:
      T -
      Parameters:
      function - the Consumer.

    • createTopologyRefresh

      protected ClusterTopologyRefresh createTopologyRefresh()
      Template method to create ClusterTopologyRefresh. Can be overriden by subclasses.
      Returns:
      Since:
      6.0.3

    • useDynamicRefreshSources

      protected boolean useDynamicRefreshSources()
      Returns true if dynamic refresh sources are enabled.

      Subclasses of RedisClusterClient may override that method.

      Returns:
      true if dynamic refresh sources are used.
      See Also:
      ClusterTopologyRefreshOptions.useDynamicRefreshSources()

    • newStringStringCodec

      protected RedisCodec<String,​String> newStringStringCodec()
      Returns a String codec.
      Returns:
      a String codec.
      See Also:
      StringCodec.UTF8

    • transformAsyncConnectionException

      protected static <T> CompletableFuture<T> transformAsyncConnectionException​(CompletionStage<T> future, Iterable<RedisURI> target)