Package com.datastax.oss.driver.api.core.loadbalancing

Interface LoadBalancingPolicy

All Superinterfaces:

AutoCloseable

public interface LoadBalancingPolicy
extends AutoCloseable

Decides which Cassandra nodes to contact for each query.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	LoadBalancingPolicy.DistanceReporter	An object that the policy uses to signal decisions it makes about node distances.

Method Summary

Modifier and Type	Method	Description
void	close()	Called when the cluster that this policy is associated with closes.
default Optional<RequestTracker>	getRequestTracker()	Returns an optional RequestTracker to be registered with the session.
void	init(Map<UUID,Node> nodes, LoadBalancingPolicy.DistanceReporter distanceReporter)	Initializes this policy with the nodes discovered during driver initialization.
Queue<Node>	newQueryPlan(Request request, Session session)	Returns the coordinators to use for a new query.
void	onAdd(Node node)	Called when a node is added to the cluster.
void	onDown(Node node)	Called when a node is determined to be down.
void	onRemove(Node node)	Called when a node is removed from the cluster.
void	onUp(Node node)	Called when a node is determined to be up.

Method Detail

getRequestTracker

@NonNull
default Optional<RequestTracker> getRequestTracker()

Returns an optional RequestTracker to be registered with the session. Registering a request tracker allows load-balancing policies to track node latencies in order to pick the fastest ones.

This method is invoked only once during session configuration, and before any other methods in this interface. Note that at this point, the driver hasn't connected to any node yet.

Since:

4.13.0

init

void init(@NonNull
          Map<UUID,Node> nodes,
          @NonNull
          LoadBalancingPolicy.DistanceReporter distanceReporter)

Initializes this policy with the nodes discovered during driver initialization.

This method is guaranteed to be called exactly once per instance, and before any other method in this interface except getRequestTracker(). At this point, the driver has successfully connected to one of the contact points, and performed a first refresh of topology information (by default, the contents of system.peers), to discover other nodes in the cluster.

This method must call distanceReporter.setDistance for each provided node (otherwise that node will stay at distance IGNORED, and the driver won't open connections to it). Note that the node's state can be either UP (for the successful contact point), DOWN (for contact points that were tried unsuccessfully), or UNKNOWN (for contact points that weren't tried, or any other node discovered from the topology refresh). Node states may be updated concurrently while this method executes, but if so this policy will get notified after this method has returned, through other methods such as onUp(Node) or onDown(Node).

Parameters:

nodes - all the nodes that are known to exist in the cluster (regardless of their state) at the time of invocation.

distanceReporter - an object that will be used by the policy to signal distance changes. Implementations will typically store this in a field, since new nodes may get added later and will need to have their distance set (or the policy might change distances dynamically over time).

newQueryPlan

@NonNull
Queue<Node> newQueryPlan(@Nullable
                         Request request,
                         @Nullable
                         Session session)

Returns the coordinators to use for a new query.

Each new query will call this method, and try the returned nodes sequentially.

Parameters:

request - the request that is being routed. Note that this can be null for some internal uses.

session - the session that is executing the request. Note that this can be null for some internal uses.

Returns:

the list of coordinators to try. This must be a concurrent queue; ConcurrentLinkedQueue is a good choice.

onAdd

void onAdd(@NonNull
           Node node)

Called when a node is added to the cluster.

The new node will be at distance IGNORED, and have the state UNKNOWN.

If this method assigns an active distance to the node, the driver will try to create a connection pool to it (resulting in a state change to UP or DOWN depending on the outcome).

If it leaves it at distance IGNORED, the driver won't attempt any connection. The node state will remain unknown, but might be updated later if a topology event is received from the cluster.

See Also:

init(Map, DistanceReporter)

onUp

void onUp(@NonNull
          Node node)

Called when a node is determined to be up.

onDown

void onDown(@NonNull
            Node node)

Called when a node is determined to be down.

onRemove

void onRemove(@NonNull
              Node node)

Called when a node is removed from the cluster.

close

void close()

Called when the cluster that this policy is associated with closes.

Specified by:

close in interface AutoCloseable