io.lettuce.core.cluster.pubsub

Interface StatefulRedisClusterPubSubConnection<K,V>

All Superinterfaces:

AsyncCloseable, AutoCloseable, StatefulConnection<K,V>, StatefulRedisConnection<K,V>, StatefulRedisPubSubConnection<K,V>

public interface StatefulRedisClusterPubSubConnection<K,V>
extends StatefulRedisPubSubConnection<K,V>

A stateful Pub/Sub connection for Redis Cluster use. This connection type is intended for Pub/Sub messaging with Redis Cluster. The connection provides transparent command routing based on the first command key.

This connection allows publishing and subscription to Pub/Sub messages within a Redis Cluster. Due to Redis Cluster's nature, messages are broadcasted across the cluster and a client can connect to any arbitrary node to participate with a subscription.

  StatefulRedisClusterPubSubConnection<String, String> connection = clusterClient.connectPubSub();
  connection.addListener(…);

  RedisClusterPubSubCommands<String, String> sync = connection.sync();
  sync.subscribe("channel");
  sync.publish("channel", "message");
 

Keyspace notifications

Redis clients can subscribe to user-space Pub/Sub messages and Redis keyspace notifications. Other than user-space Pub/Sub messages are Keyspace notifications not broadcasted to the whole cluster. They stay node-local. Subscription to keyspace notifications requires subscription to the nodes which publish the keyspace notifications.

StatefulRedisClusterPubSubConnection allows node-specific subscriptions and message propagation. setNodeMessagePropagation(boolean) can notify a RedisPubSubListener that requires a single registration with this connection. Node-subscriptions are supported on connection and NodeSelection levels through asynchronous, synchronous, and reactive APIs.

     
  StatefulRedisClusterPubSubConnection<String, String> connection = clusterClient.connectPubSub();
  connection.addListener(…);

  RedisClusterPubSubCommands<String, String> sync = connection.sync();
  sync.replicas().commands().psubscribe("__key*__:*");
     
 

Since:

4.4

Author:

Mark Paluch

Method Summary

Modifier and Type	Method and Description
void	addListener(RedisClusterPubSubListener<K,V> listener) Add a new listener.
void	addListener(RedisClusterPushListener listener) Add a new listener to consume push messages.
RedisClusterPubSubAsyncCommands<K,V>	async() Returns the RedisClusterPubSubAsyncCommands API for the current connection.
default <T> T	commands(ClusterPubSubCommandsFactory<StatefulRedisClusterPubSubConnection<K,V>,T> factory) Returns the command API created by factory, bound to this connection.
StatefulRedisPubSubConnection<K,V>	getConnection(String nodeId) Retrieve a connection to the specified cluster node using the nodeId.
StatefulRedisPubSubConnection<K,V>	getConnection(String host, int port) Retrieve a connection to the specified cluster node using host and port.
CompletableFuture<StatefulRedisPubSubConnection<K,V>>	getConnectionAsync(String nodeId) Retrieve asynchronously a connection to the specified cluster node using the nodeId.
CompletableFuture<StatefulRedisPubSubConnection<K,V>>	getConnectionAsync(String host, int port) Retrieve a connection to the specified cluster node using host and port.
Partitions	getPartitions()
RedisClusterPubSubReactiveCommands<K,V>	reactive() Deprecated. since 7.8, use commands(ClusterPubSubCommandsFactory) with RedisClusterPubSubReactiveCommands.factory() instead; scheduled for removal in a future major release.
void	removeListener(RedisClusterPubSubListener<K,V> listener) Remove an existing listener.
void	removeListener(RedisClusterPushListener listener) Remove an existing listener.
void	setNodeMessagePropagation(boolean enabled) Enables/disables node message propagation to this connections listeners.
RedisClusterPubSubCommands<K,V>	sync() Returns the RedisClusterPubSubCommands API for the current connection.

Methods inherited from interface io.lettuce.core.pubsub.StatefulRedisPubSubConnection

addListener, commands, removeListener

Methods inherited from interface io.lettuce.core.api.StatefulRedisConnection

addListener, commands, isMulti, removeListener

Methods inherited from interface io.lettuce.core.api.StatefulConnection

addListener, close, closeAsync, dispatch, dispatch, flushCommands, getCodec, getOptions, getResources, getTimeout, isOpen, removeListener, setAutoFlushCommands, setTimeout

Method Detail

sync

RedisClusterPubSubCommands<K,V> sync()

Returns the RedisClusterPubSubCommands API for the current connection. Does not create a new connection.

Note: this accessor is scheduled for removal in a future major release; a commands(...)-based replacement is planned.

Specified by:

sync in interface StatefulRedisConnection<K,V>

Specified by:

sync in interface StatefulRedisPubSubConnection<K,V>

Returns:

the synchronous API for the underlying connection.

async

RedisClusterPubSubAsyncCommands<K,V> async()

Returns the RedisClusterPubSubAsyncCommands API for the current connection. Does not create a new connection.

Note: this accessor is scheduled for removal in a future major release; a commands(...)-based replacement is planned.

Specified by:

async in interface StatefulRedisConnection<K,V>

Specified by:

async in interface StatefulRedisPubSubConnection<K,V>

Returns:

the asynchronous API for the underlying connection.

reactive

@Deprecated
RedisClusterPubSubReactiveCommands<K,V> reactive()

Deprecated. since 7.8, use commands(ClusterPubSubCommandsFactory) with RedisClusterPubSubReactiveCommands.factory() instead; scheduled for removal in a future major release.

Returns the RedisClusterPubSubReactiveCommands API for the current connection. Does not create a new connection.

Specified by:

reactive in interface StatefulRedisConnection<K,V>

Specified by:

reactive in interface StatefulRedisPubSubConnection<K,V>

Returns:

the reactive API for the underlying connection.

getConnection

StatefulRedisPubSubConnection<K,V> getConnection(String nodeId)

Retrieve a connection to the specified cluster node using the nodeId. Host and port are looked up in the node list. This connection is bound to the node id. Once the cluster topology view is updated, the connection will try to reconnect the to the node with the specified nodeId, that behavior can also lead to a closed connection once the node with the specified nodeId is no longer part of the cluster.

Do not close the connections. Otherwise, unpredictable behavior will occur. The nodeId must be part of the cluster and is validated against the current topology view in Partitions.

Parameters:

nodeId - the node Id

Returns:

a connection to the requested cluster node

Throws:

RedisException - if the requested node identified by nodeId is not part of the cluster

getConnectionAsync

CompletableFuture<StatefulRedisPubSubConnection<K,V>> getConnectionAsync(String nodeId)

Retrieve asynchronously a connection to the specified cluster node using the nodeId. Host and port are looked up in the node list. This connection is bound to the node id. Once the cluster topology view is updated, the connection will try to reconnect the to the node with the specified nodeId, that behavior can also lead to a closed connection once the node with the specified nodeId is no longer part of the cluster.

Do not close the connections. Otherwise, unpredictable behavior will occur. The nodeId must be part of the cluster and is validated against the current topology view in Partitions.

Parameters:

nodeId - the node Id

Returns:

CompletableFuture to indicate success or failure to connect to the requested cluster node.

Throws:

RedisException - if the requested node identified by nodeId is not part of the cluster

Since:

5.0

getConnection

StatefulRedisPubSubConnection<K,V> getConnection(String host,
                                                 int port)

Retrieve a connection to the specified cluster node using host and port. This connection is bound to a host and port. Updates to the cluster topology view can close the connection once the host, identified by host and port, are no longer part of the cluster.

Do not close the connections. Otherwise, unpredictable behavior will occur. Host and port connections are verified by default for cluster membership, see ClusterClientOptions.isValidateClusterNodeMembership().

Parameters:

host - the host

port - the port

Returns:

a connection to the requested cluster node

Throws:

RedisException - if the requested node identified by host and port is not part of the cluster

getConnectionAsync

CompletableFuture<StatefulRedisPubSubConnection<K,V>> getConnectionAsync(String host,
                                                                         int port)

Retrieve a connection to the specified cluster node using host and port. This connection is bound to a host and port. Updates to the cluster topology view can close the connection once the host, identified by host and port, are no longer part of the cluster.

Do not close the connections. Otherwise, unpredictable behavior will occur. Host and port connections are verified by default for cluster membership, see ClusterClientOptions.isValidateClusterNodeMembership().

Parameters:

host - the host

port - the port

Returns:

CompletableFuture to indicate success or failure to connect to the requested cluster node.

Throws:

RedisException - if the requested node identified by host and port is not part of the cluster

Since:

5.0

getPartitions

Partitions getPartitions()

Returns:

Known partitions for this connection.

setNodeMessagePropagation

void setNodeMessagePropagation(boolean enabled)

Enables/disables node message propagation to this connections listeners.

If enabled is true, then Pub/Sub messages received on node-specific connections are propagated to this connection facade. Registered RedisPubSubListener will receive messages from individual node subscriptions.

Node event propagation is disabled by default.

Parameters:

enabled - true to enable node message propagation; false (default) to disable message propagation.

addListener

void addListener(RedisClusterPubSubListener<K,V> listener)

Add a new listener.

Parameters:

listener - the listener, must not be null.

removeListener

void removeListener(RedisClusterPubSubListener<K,V> listener)

Remove an existing listener.

Parameters:

listener - the listener, must not be null.

addListener

void addListener(RedisClusterPushListener listener)

Add a new listener to consume push messages.

Parameters:

listener - the listener, must not be null.

Since:

6.0

removeListener

void removeListener(RedisClusterPushListener listener)

Remove an existing listener.

Parameters:

listener - the listener, must not be null.

Since:

6.0

commands

default <T> T commands(ClusterPubSubCommandsFactory<StatefulRedisClusterPubSubConnection<K,V>,T> factory)

Returns the command API created by factory, bound to this connection. Does not create a new connection.

The command API is created once per connection and cached; calling this method again with the same factory returns the same instance.

Type Parameters:

T - the command API type

Parameters:

factory - the command API factory, must not be null

Returns:

the command API bound to this connection

Throws:

UnsupportedOperationException - if the connection implementation does not override this method. The default is provided only for source compatibility in Lettuce 7.x and becomes an abstract method in Lettuce 8.0.

Since:

7.8