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:

• DEL
• UNLINK
• MGET
• RedisStringAsyncCommands.mget(KeyValueStreamingChannel, Object[]) ) MGET with streaming}
• MSET
• MSETNX

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

• RedisAdvancedClusterAsyncCommands.clientSetname(Object) Executes CLIENT SET on all connections and initializes new connections with the clientName.
• RedisAdvancedClusterAsyncCommands.flushall() Run FLUSHALL on all master nodes.
• RedisAdvancedClusterAsyncCommands.flushdb() Executes FLUSHDB on all master nodes.
• RedisAdvancedClusterAsyncCommands.keys(Object) Executes KEYS on all.
• RedisAdvancedClusterAsyncCommands.randomkey() Returns a random key from a random master node.
• RedisAdvancedClusterAsyncCommands.scriptFlush() Executes SCRIPT FLUSH on all nodes.
• RedisAdvancedClusterAsyncCommands.scriptKill() Executes SCRIPT KILL on all nodes.
• RedisAdvancedClusterAsyncCommands.shutdown(boolean) Executes SHUTDOWN on all nodes.
• RedisAdvancedClusterAsyncCommands.scan() Executes a SCAN on all nodes according to ReadFrom. The resulting cursor must be reused across the SCAN to scan iteratively across the whole cluster.

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.masters().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

Field Summary

Fields

Modifier and Type	Field and Description
protected AtomicBoolean	clusterTopologyRefreshActivated
protected AtomicReference<ScheduledFuture<?>>	clusterTopologyRefreshFuture

Fields inherited from class io.lettuce.core.AbstractRedisClient

BUF_ALLOCATOR, channels, clientOptions, clientResources, closeableResources, connectionEvents, eventLoopGroups, genericWorkerPool, timeout, timer

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RedisClusterClient() Non-private constructor to make RedisClusterClient proxyable.
protected	RedisClusterClient(ClientResources clientResources, Iterable<RedisURI> redisURIs) Initialize the client with a list of cluster URI's.

Method Summary

Modifier and Type	Method and Description
StatefulRedisClusterConnection<String,String>	connect() Connect to a Redis Cluster and treat keys and values as UTF-8 strings.
<K,V> StatefulRedisClusterConnection<K,V>	connect(RedisCodec<K,V> codec) Connect to a Redis Cluster.
<K,V> CompletableFuture<StatefulRedisClusterConnection<K,V>>	connectAsync(RedisCodec<K,V> codec) Connect asynchronously to a Redis Cluster.
StatefulRedisClusterPubSubConnection<String,String>	connectPubSub() Connect to a Redis Cluster using pub/sub connections and treat keys and values as UTF-8 strings.
<K,V> StatefulRedisClusterPubSubConnection<K,V>	connectPubSub(RedisCodec<K,V> codec) Connect to a Redis Cluster using pub/sub connections.
<K,V> CompletableFuture<StatefulRedisClusterPubSubConnection<K,V>>	connectPubSubAsync(RedisCodec<K,V> codec) Connect asynchronously to a Redis Cluster using pub/sub connections.
static RedisClusterClient	create(ClientResources clientResources, Iterable<RedisURI> redisURIs) Create a new client that connects to the supplied uri with shared ClientResources.
static RedisClusterClient	create(ClientResources clientResources, RedisURI redisURI) Create a new client that connects to the supplied uri with shared ClientResources.
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.
static RedisClusterClient	create(Iterable<RedisURI> redisURIs) Create a new client that connects to the supplied uri with default ClientResources.
static RedisClusterClient	create(RedisURI redisURI) Create a new client that connects to the supplied uri with default ClientResources.
static RedisClusterClient	create(String uri) Create a new client that connects to the supplied uri with default ClientResources.
protected Partitions	determinePartitions(Partitions current, Map<RedisURI,Partitions> topologyViews) Determines a topology view based on the current and the obtain topology views.
protected <T extends Closeable> void	forEachCloseable(Predicate<? super Closeable> selector, Consumer<T> function) Apply a Consumer of Closeable to all active connections.
protected void	forEachClusterConnection(Consumer<StatefulRedisClusterConnectionImpl<?,?>> function) Apply a Consumer of StatefulRedisClusterConnectionImpl to all active connections.
protected void	forEachClusterPubSubConnection(Consumer<io.lettuce.core.cluster.StatefulRedisClusterPubSubConnectionImpl<?,?>> function) Apply a Consumer of StatefulRedisClusterPubSubConnectionImpl to all active connections.
protected RedisURI	getFirstUri() Returns the first RedisURI configured with this RedisClusterClient instance.
protected Iterable<RedisURI>	getInitialUris() Returns an Iterable of the initial URIs.
Partitions	getPartitions() Retrieve the cluster view.
ClientResources	getResources() Returns the ClientResources which are used with that client.
protected Mono<SocketAddress>	getSocketAddressSupplier(Function<Partitions,Collection<RedisClusterNode>> sortFunction) Returns a Supplier for connection points.
protected Iterable<RedisURI>	getTopologyRefreshSource() Returns the seed RedisURI for the topology refreshing.
protected void	initializePartitions()
protected Partitions	loadPartitions() Retrieve partitions.
protected RedisCodec<String,String>	newStringStringCodec() Returns a String codec.
void	reloadPartitions() Reload partitions and re-initialize the distribution table.
void	setOptions(ClusterClientOptions clientOptions) Set the ClusterClientOptions for the client.
void	setPartitions(Partitions partitions) Sets the new cluster topology.
void	shutdown(long quietPeriod, long timeout, TimeUnit timeUnit) Shutdown this client and close all open connections.
protected static <T> CompletableFuture<T>	transformAsyncConnectionException(CompletionStage<T> future, Iterable<RedisURI> target)
protected void	updatePartitionsInConnections()
protected boolean	useDynamicRefreshSources() Returns true if dynamic refresh sources are enabled.

Methods inherited from class io.lettuce.core.AbstractRedisClient

addListener, channelType, connectionBuilder, getChannelCount, getConnection, getConnection, getOptions, getResourceCount, initializeChannelAsync, removeListener, setDefaultTimeout, setDefaultTimeout, setOptions, shutdown, shutdown, shutdownAsync, shutdownAsync

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

clusterTopologyRefreshActivated

protected final AtomicBoolean clusterTopologyRefreshActivated

clusterTopologyRefreshFuture

protected final AtomicReference<ScheduledFuture<?>> clusterTopologyRefreshFuture

Constructor Detail

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 Detail

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

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

reloadPartitions

public void reloadPartitions()

Reload partitions and re-initialize the distribution table.

updatePartitionsInConnections

protected void updatePartitionsInConnections()

initializePartitions

protected void initializePartitions()

getPartitions

public Partitions getPartitions()

Retrieve the cluster view. Partitions are shared amongst all connections opened by this client instance.

Returns:

the partitions.

loadPartitions

protected Partitions loadPartitions()

Retrieve partitions. Nodes within Partitions are ordered by latency. Lower latency nodes come first.

Returns:

Partitions

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

getResources

public ClientResources getResources()

Returns the ClientResources which are used with that client.

Returns:

the ClientResources for this client

shutdown

public void shutdown(long quietPeriod,
                     long timeout,
                     TimeUnit timeUnit)

Shutdown this client and close all open connections. The client should be discarded after calling shutdown.

Overrides:

shutdown 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

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

getFirstUri

protected RedisURI getFirstUri()

Returns the first RedisURI configured with this RedisClusterClient instance.

Returns:

the first RedisURI.

getSocketAddressSupplier

protected Mono<SocketAddress> getSocketAddressSupplier(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.

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.

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)