Module lettuce.core
Package 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 Details

    • sync

      RedisClusterPubSubCommands<K,​V> sync()
      Returns the RedisClusterPubSubCommands API for the current connection. Does not create a new connection.
      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.
      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

      RedisClusterPubSubReactiveCommands<K,​V> reactive()
      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