public interface LoadBalancingPolicy extends AutoCloseable
Modifier and Type | Interface and Description |
---|---|
static interface |
LoadBalancingPolicy.DistanceReporter
An object that the policy uses to signal decisions it makes about node distances.
|
Modifier and Type | Method and 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.
|
@NonNull default Optional<RequestTracker> getRequestTracker()
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.
void init(@NonNull Map<UUID,Node> nodes, @NonNull LoadBalancingPolicy.DistanceReporter distanceReporter)
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)
.
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).@NonNull Queue<Node> newQueryPlan(@Nullable Request request, @Nullable Session session)
Each new query will call this method, and try the returned nodes sequentially.
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.ConcurrentLinkedQueue
is a good choice.void onAdd(@NonNull Node node)
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.
init(Map, DistanceReporter)
void onUp(@NonNull Node node)
void onDown(@NonNull Node node)
void onRemove(@NonNull Node node)
void close()
close
in interface AutoCloseable
Copyright © 2017–2024. All rights reserved.