com.datastax.oss.driver.api.core.metadata

Class SafeInitNodeStateListener

java.lang.Object

com.datastax.oss.driver.api.core.metadata.SafeInitNodeStateListener

All Implemented Interfaces:

NodeStateListener, AutoCloseable

public class SafeInitNodeStateListener
extends Object
implements NodeStateListener

A node state listener wrapper that delays (or ignores) init events until after the session is ready.

By default, the driver calls node state events, such as onUp(com.datastax.oss.driver.api.core.metadata.Node) and onAdd(com.datastax.oss.driver.api.core.metadata.Node), before the session is ready; see NodeStateListener.onSessionReady(Session) for a detailed explanation. This can make things complicated if your listener implementation needs the session to process those events.

This class wraps another implementation to shield it from those details:

 NodeStateListener delegate = ... // your listener implementation

 SafeInitNodeStateListener wrapper =
     new SafeInitNodeStateListener(delegate, true);

 CqlSession session = CqlSession.builder()
     .withNodeStateListener(wrapper)
     .build();
 

With this setup, delegate.onSessionReady is guaranteed to be invoked first, before any other method. The second constructor argument indicates what to do with the method calls that were ignored before that:

• if true, they are recorded, and replayed to delegate immediately after onSessionReady(com.datastax.oss.driver.api.core.session.Session). They are guaranteed to happen in the original order, and before any post-initialization events.
• if false, they are discarded.

Since:

4.6.0

Constructor Summary

Constructors

Constructor and Description
SafeInitNodeStateListener(NodeStateListener delegate, boolean replayInitEvents) Creates a new instance.

Method Summary

Modifier and Type	Method and Description
void	close()
void	onAdd(Node node) Invoked when a node is first added to the cluster.
void	onDown(Node node) Invoked when a node's state switches to NodeState.DOWN or NodeState.FORCED_DOWN.
void	onRemove(Node node) Invoked when a node leaves the cluster.
void	onSessionReady(Session session) Invoked when the session is ready to process user requests.
void	onUp(Node node) Invoked when a node's state switches to NodeState.UP.

Methods inherited from class java.lang.Object

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

Constructor Detail

SafeInitNodeStateListener

public SafeInitNodeStateListener(@NonNull
                                 NodeStateListener delegate,
                                 boolean replayInitEvents)

Creates a new instance.

Parameters:

delegate - the wrapped listener, to which method invocations will be forwarded.

replayInitEvents - whether to record events during initialization and replay them to the child listener once it's created, or just ignore them.

Method Detail

onSessionReady

public void onSessionReady(@NonNull
                           Session session)

Description copied from interface: NodeStateListener

Invoked when the session is ready to process user requests.

This corresponds to the moment when SessionBuilder.build() returns, or the future returned by SessionBuilder.buildAsync() completes. If the session initialization fails, this method will not get called.

Listener methods are invoked from different threads; if you store the session in a field, make it at least volatile to guarantee proper publication.

Note that this method will not be the first one invoked on the listener; the driver emits node events before that, during the initialization of the session:

• First the driver shuffles the contact points, and tries each one sequentially. For any contact point that can't be reached, NodeStateListener.onDown(Node) is invoked; for the one that eventually succeeds, NodeStateListener.onUp(Node) is invoked and that node becomes the control node (if none succeeds, the session initialization fails and the process stops here).
• The control node's system.peers table is inspected to discover the remaining nodes in the cluster. For any node that wasn't already a contact point, NodeStateListener.onAdd(Node) is invoked; for any contact point that doesn't have a corresponding entry in the table, NodeStateListener.onRemove(Node) is invoked;
• The load balancing policy computes the nodes' distances, and, for each LOCAL or REMOTE node, the driver creates a connection pool. If at least one pooled connection can be established, NodeStateListener.onUp(Node) is invoked; otherwise, NodeStateListener.onDown(Node) is invoked (no additional event is emitted for the control node, it is considered up since we already have a connection to it).
• Once all the pools are created, the session is fully initialized and this method is invoked.

If you're not interested in those init events, or want to delay them until after the session is ready, take a look at SafeInitNodeStateListener.

This method's default implementation is empty.

Specified by:

onSessionReady in interface NodeStateListener

onAdd

public void onAdd(@NonNull
                  Node node)

Description copied from interface: NodeStateListener

Invoked when a node is first added to the cluster.

The node is not up yet at this point. NodeStateListener.onUp(Node) will be notified later if the driver successfully connects to the node (provided that a session is opened and the node is not ignored), or receives a topology event for it.

This method is not invoked for the contact points provided at initialization. It is however for new nodes discovered during the full node list refresh after the first connection.

Specified by:

onAdd in interface NodeStateListener

onUp

public void onUp(@NonNull
                 Node node)

Description copied from interface: NodeStateListener

Invoked when a node's state switches to NodeState.UP.

Specified by:

onUp in interface NodeStateListener

onDown

public void onDown(@NonNull
                   Node node)

Description copied from interface: NodeStateListener

Invoked when a node's state switches to NodeState.DOWN or NodeState.FORCED_DOWN.

Specified by:

onDown in interface NodeStateListener

onRemove

public void onRemove(@NonNull
                     Node node)

Description copied from interface: NodeStateListener

Invoked when a node leaves the cluster.

This can be triggered by a topology event, or during a full node list refresh if the node is absent from the new list.

Specified by:

onRemove in interface NodeStateListener

close

public void close()
           throws Exception

Specified by:

close in interface AutoCloseable

Throws:

Exception