public class TokenAwarePolicy extends Object implements ChainableLoadBalancingPolicy
This policy encapsulates another policy. The resulting policy works in the following way:
distance
method is inherited from the child policy.
newQueryPlan
method will first return the LOCAL
replicas for the query if possible (i.e. if the query's
routing key is not
null
and if the set of
replicas for that partition key is not empty). If no local replica can be either found or
successfully contacted, the rest of the query plan will fallback to the child policy's one.
Do note that only replicas for which the child policy's distance method returns LOCAL
will
be considered having priority. For example, if you wrap DCAwareRoundRobinPolicy
with this
token aware policy, replicas from remote data centers may only be returned after all the hosts of
the local data center.
Modifier and Type | Class and Description |
---|---|
static class |
TokenAwarePolicy.ReplicaOrdering
Strategies for replica ordering.
|
Constructor and Description |
---|
TokenAwarePolicy(LoadBalancingPolicy childPolicy)
Creates a new
TokenAware policy with RANDOM replica
ordering. |
TokenAwarePolicy(LoadBalancingPolicy childPolicy,
boolean shuffleReplicas)
Deprecated.
Use
TokenAwarePolicy(LoadBalancingPolicy, ReplicaOrdering) instead. This
constructor will be removed in the next major release. |
TokenAwarePolicy(LoadBalancingPolicy childPolicy,
TokenAwarePolicy.ReplicaOrdering replicaOrdering)
Creates a new
TokenAware policy. |
Modifier and Type | Method and Description |
---|---|
void |
close()
Gets invoked at cluster shutdown.
|
HostDistance |
distance(Host host)
Returns the distance assigned by this policy to the provided host.
|
LoadBalancingPolicy |
getChildPolicy()
Returns the child policy.
|
void |
init(Cluster cluster,
Collection<Host> hosts)
Initialize this load balancing policy.
|
Iterator<Host> |
newQueryPlan(String loggedKeyspace,
Statement statement)
Returns the hosts to use for a new query.
|
void |
onAdd(Host host)
Called when a new node is added to the cluster.
|
void |
onDown(Host host)
Called when a node is determined to be down.
|
void |
onRemove(Host host)
Called when a node is removed from the cluster.
|
void |
onUp(Host host)
Called when a node is determined to be up.
|
public TokenAwarePolicy(LoadBalancingPolicy childPolicy, TokenAwarePolicy.ReplicaOrdering replicaOrdering)
TokenAware
policy.childPolicy
- the load balancing policy to wrap with token awareness.replicaOrdering
- the strategy to use to order replicas.@Deprecated public TokenAwarePolicy(LoadBalancingPolicy childPolicy, boolean shuffleReplicas)
TokenAwarePolicy(LoadBalancingPolicy, ReplicaOrdering)
instead. This
constructor will be removed in the next major release.TokenAware
policy.childPolicy
- the load balancing policy to wrap with token awareness.shuffleReplicas
- whether or not to shuffle the replicas. If true
, then the RANDOM
strategy will be used, otherwise the TOPOLOGICAL
one will be used.public TokenAwarePolicy(LoadBalancingPolicy childPolicy)
TokenAware
policy with RANDOM
replica
ordering.childPolicy
- the load balancing policy to wrap with token awareness.public LoadBalancingPolicy getChildPolicy()
ChainableLoadBalancingPolicy
getChildPolicy
in interface ChainableLoadBalancingPolicy
public void init(Cluster cluster, Collection<Host> hosts)
LoadBalancingPolicy
Note that the driver guarantees that it will call this method exactly once per policy object and will do so before any call to another of the methods of the policy.
init
in interface LoadBalancingPolicy
cluster
- the Cluster
instance for which the policy is created.hosts
- the initial hosts to use.public HostDistance distance(Host host)
The distance of an host influence how much connections are kept to the node (see HostDistance
). A policy should assign a LOCAL
distance to nodes that are susceptible
to be returned first by newQueryPlan
and it is useless for newQueryPlan
to
return hosts to which it assigns an IGNORED
distance.
The host distance is primarily used to prevent keeping too many connections to host in remote datacenters when the policy itself always picks host in the local datacenter first.
This implementation always returns distances as reported by the wrapped policy.
distance
in interface LoadBalancingPolicy
host
- the host of which to return the distance of.host
.public Iterator<Host> newQueryPlan(String loggedKeyspace, Statement statement)
Each new query will call this method. The first host in the result will then be used to
perform the query. In the event of a connection problem (the queried host is down or appear to
be so), the next host will be used. If all hosts of the returned Iterator
are down, the
query will fail.
The returned plan will first return local replicas for the query (i.e. replicas whose
distance according to the child policy is LOCAL
), if it can
determine them (i.e. mainly if the statement's routing key is not null
), and
ordered according to the ordering strategy specified at
instantiation; following what it will return the rest of the child policy's original query
plan.
newQueryPlan
in interface LoadBalancingPolicy
loggedKeyspace
- the currently logged keyspace (the one set through either Cluster.connect(String)
or by manually doing a USE
query) for the session on which
this plan need to be built. This can be null
if the corresponding session has no
keyspace logged in.statement
- the query for which to build a plan.public void onUp(Host host)
LoadBalancingPolicy
onUp
in interface LoadBalancingPolicy
host
- the host that has been detected up.public void onDown(Host host)
LoadBalancingPolicy
onDown
in interface LoadBalancingPolicy
host
- the host that has been detected down.public void onAdd(Host host)
LoadBalancingPolicy
The newly added node should be considered up.
onAdd
in interface LoadBalancingPolicy
host
- the host that has been newly added.public void onRemove(Host host)
LoadBalancingPolicy
onRemove
in interface LoadBalancingPolicy
host
- the removed host.public void close()
LoadBalancingPolicy
This gives the policy the opportunity to perform some cleanup, for instance stop threads that it might have started.
close
in interface LoadBalancingPolicy
Copyright © 2012–2023. All rights reserved.