Package com.datastax.driver.core.policies

Class TokenAwarePolicy

  • All Implemented Interfaces:
    ChainableLoadBalancingPolicy, LoadBalancingPolicy
    public class TokenAwarePolicy
extends Object
implements ChainableLoadBalancingPolicy
    A wrapper load balancing policy that adds token awareness to a child policy.

    This policy encapsulates another policy. The resulting policy works in the following way:

    • the distance method is inherited from the child policy.
    • the iterator returned by the 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 fall back to the child policy's one.
    The exact order in which local replicas are returned is dictated by the strategy provided at instantiation.

    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.

    Lightweight Transaction (LWT) Routing

    For lightweight transaction queries, this policy provides specialized routing to optimize LWT performance and avoid contention. When LWT routing is enabled (the default), the query plan prioritizes replicas for the target partition, ordered by datacenter locality, followed by non-replica nodes for failover:

    • Local replicas first: replicas for which the child policy reports LOCAL distance are returned first, in the order provided by cluster metadata (preserving primary replica ordering from the token ring).
    • Remote replicas second: remaining replicas (typically in remote datacenters) are appended, but only if they are up and not ignored by the child policy.
    • Non-replica nodes: remaining nodes from the child policy's query plan are appended after all replicas, ensuring the query plan always includes all available nodes for failover.

    Rack awareness is intentionally not applied to LWT replica ordering. All local replicas are treated equally within the local datacenter to avoid rack-based contention hotspots during Paxos consensus phases.

    Requirements for LWT replica-only routing:

    Fallback behavior: If routing key, keyspace, or replica metadata is unavailable, the driver falls back to the child policy's normal query plan. In this case, the query plan may include non-replica hosts, and LWT may incur additional coordinator forwarding latency. This fallback is a pragmatic safety net to preserve availability when routing information is incomplete.

    LWT routing can be configured via QueryOptions.setLoadBalancingLwtRequestRoutingMethod(QueryOptions.RequestRoutingMethod). The default preserves replica order for optimal LWT performance.

    See Also:
    DCAwareRoundRobinPolicy, QueryOptions.RequestRoutingMethod

    • Constructor Detail

      • TokenAwarePolicy

        public TokenAwarePolicy​(LoadBalancingPolicy childPolicy,
                        TokenAwarePolicy.ReplicaOrdering replicaOrdering)
        Creates a new TokenAware policy.
        Parameters:
        childPolicy - the load balancing policy to wrap with token awareness.
        replicaOrdering - the strategy to use to order replicas.

      • TokenAwarePolicy

        @Deprecated
public TokenAwarePolicy​(LoadBalancingPolicy childPolicy,
                        boolean shuffleReplicas)
        Deprecated.
        Use TokenAwarePolicy(LoadBalancingPolicy, ReplicaOrdering) instead. This constructor will be removed in the next major release.
        Creates a new TokenAware policy.
        Parameters:
        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.

      • TokenAwarePolicy

        public TokenAwarePolicy​(LoadBalancingPolicy childPolicy)
        Creates a new TokenAware policy with RANDOM replica ordering.
        Parameters:
        childPolicy - the load balancing policy to wrap with token awareness.

    • Method Detail

      • getReplicaOrdering

        @Beta
public TokenAwarePolicy.ReplicaOrdering getReplicaOrdering()
        The strategy this policy uses to order the replicas of a query's partition, as specified at instantiation.
        Returns:
        the replica ordering strategy.

      • init

        public void init​(Cluster cluster,
                 Collection<Host> hosts)
        Description copied from interface: LoadBalancingPolicy
        Initialize this load balancing policy.

        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.

        Specified by:
        init in interface LoadBalancingPolicy
        Parameters:
        cluster - the Cluster instance for which the policy is created.
        hosts - the initial hosts to use.

      • distance

        public HostDistance distance​(Host host)
        Returns the distance assigned by this policy to the provided 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.

        Specified by:
        distance in interface LoadBalancingPolicy
        Parameters:
        host - the host of which to return the distance of.
        Returns:
        the HostDistance to host.

      • newQueryPlan

        public Iterator<Host> newQueryPlan​(String loggedKeyspace,
                                   Statement statement)
        Returns the hosts to use for a new query.

        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.

        Specified by:
        newQueryPlan in interface LoadBalancingPolicy
        Parameters:
        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.
        Returns:
        an iterator of Host. The query is tried against the hosts returned by this iterator in order, until the query has been sent successfully to one of the host.

      • onUp

        public void onUp​(Host host)
        Description copied from interface: LoadBalancingPolicy
        Called when a node is determined to be up.
        Specified by:
        onUp in interface LoadBalancingPolicy
        Parameters:
        host - the host that has been detected up.

      • onDown

        public void onDown​(Host host)
        Description copied from interface: LoadBalancingPolicy
        Called when a node is determined to be down.
        Specified by:
        onDown in interface LoadBalancingPolicy
        Parameters:
        host - the host that has been detected down.

      • onAdd

        public void onAdd​(Host host)
        Description copied from interface: LoadBalancingPolicy
        Called when a new node is added to the cluster.

        The newly added node should be considered up.

        Specified by:
        onAdd in interface LoadBalancingPolicy
        Parameters:
        host - the host that has been newly added.

      • close

        public void close()
        Description copied from interface: LoadBalancingPolicy
        Gets invoked at cluster shutdown.

        This gives the policy the opportunity to perform some cleanup, for instance stop threads that it might have started.

        Specified by:
        close in interface LoadBalancingPolicy