LatencyAwarePolicy (DataStax Java Driver for Apache Cassandra

java.lang.Object
- com.datastax.driver.core.policies.LatencyAwarePolicy

All Implemented Interfaces:

Host.StateListener, ChainableLoadBalancingPolicy, CloseableLoadBalancingPolicy, LoadBalancingPolicy
```
public class LatencyAwarePolicy
extends Object
implements ChainableLoadBalancingPolicy, CloseableLoadBalancingPolicy
```
A wrapper load balancing policy that adds latency awareness to a child policy.
When used, this policy will collect the latencies of the queries to each Cassandra node and maintain a per-node latency score (an average). Based on these scores, the policy will penalize (technically, it will ignore them unless no other nodes are up) the nodes that are slower than the best performing node by more than some configurable amount (the exclusion threshold).
The latency score for a given node is a based on a form of exponential moving average. In other words, the latency score of a node is the average of its previously measured latencies, but where older measurements gets an exponentially decreasing weight. The exact weight applied to a newly received latency is based on the time elapsed since the previous measure (to account for the fact that latencies are not necessarily reported with equal regularity, neither over time nor between different nodes).
Once a node is excluded from query plans (because its averaged latency grew over the exclusion threshold), its latency score will not be updated anymore (since it is not queried). To give a chance to this node to recover, the policy has a configurable retry period. The policy will not penalize a host for which no measurement has been collected for more than this retry period.
Please see the LatencyAwarePolicy.Builder class and methods for more details on the possible parameters of this policy.

Since:

1.0.4

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`LatencyAwarePolicy.Builder` Helper builder object to create a latency aware policy.
`static class`	`LatencyAwarePolicy.Snapshot` An immutable snapshot of the per-host scores (and stats in general) maintained by `LatencyAwarePolicy` to base its decision upon.

Method Summary

Methods
Modifier and Type	Method and Description
`static LatencyAwarePolicy.Builder`	`builder(LoadBalancingPolicy childPolicy)` Creates a new latency aware policy builder given the child policy that the resulting policy should wrap.
`void`	`close()` Gets invoked at cluster shutdown.
`HostDistance`	`distance(Host host)` Returns the HostDistance for the provided host.
`LoadBalancingPolicy`	`getChildPolicy()` Returns the child policy.
`LatencyAwarePolicy.Snapshot`	`getScoresSnapshot()` Returns a snapshot of the scores (latency averages) maintained by this 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`	`onSuspected(Host host)` Called when a node is suspected to be dead.
`void`	`onUp(Host host)` Called when a node is determined to be up.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getChildPolicy
```
public LoadBalancingPolicy getChildPolicy()
```
    Description copied from interface: ChainableLoadBalancingPolicy
    
    Returns the child policy.
    
    Specified by:
    
    getChildPolicy in interface ChainableLoadBalancingPolicy
    
    Returns:
    the child policy.
  - builder
```
public static LatencyAwarePolicy.Builder builder(LoadBalancingPolicy childPolicy)
```
    Creates a new latency aware policy builder given the child policy that the resulting policy should wrap.
    
    Parameters:
    childPolicy - the load balancing policy to wrap with latency awareness.
    
    Returns:
    the created builder.
  - 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 HostDistance for the provided host.
    
    Specified by:
    
    distance in interface LoadBalancingPolicy
    
    Parameters:
    host - the host of which to return the distance of.
    
    Returns:
    the HostDistance to host as returned by the wrapped policy.
  - newQueryPlan
```
public Iterator<Host> newQueryPlan(String loggedKeyspace,
                          Statement statement)
```
    Returns the hosts to use for a new query.
    The returned plan will be the same as the plan generated by the child policy, but with the (initial) exclusion of hosts whose recent (averaged) latency is more than exclusionThreshold * minLatency (where minLatency is the (averaged) latency of the fastest host).
    The hosts that are initially excluded due to their latency will be returned by this iterator, but only only after all non-excluded hosts of the child policy have been returned.
    
    Specified by:
    
    newQueryPlan in interface LoadBalancingPolicy
    
    Parameters:
    loggedKeyspace - the currently logged keyspace.
    statement - the statement for which to build the plan.
    
    Returns:
    the new query plan.
  - getScoresSnapshot
```
public LatencyAwarePolicy.Snapshot getScoresSnapshot()
```
    Returns a snapshot of the scores (latency averages) maintained by this policy.
    
    Returns:
    a new (immutable) LatencyAwarePolicy.Snapshot object containing the current latency scores maintained by this policy.
  - onUp
```
public void onUp(Host host)
```
    Description copied from interface: Host.StateListener
    
    Called when a node is determined to be up.
    
    Specified by:
    
    onUp in interface Host.StateListener
    
    Parameters:
    host - the host that has been detected up.
  - onSuspected
```
public void onSuspected(Host host)
```
    Description copied from interface: Host.StateListener
    
    Called when a node is suspected to be dead.
    A node is suspected to be dead when an error occurs on one of it's opened connection. As soon as an host is suspected, a connection attempt to that host is immediately tried. If this succeed, then it means that the connection was disfunctional but that the node was not really down. If this fails however, this means the node is truly dead, onDown() is called and further reconnection attempts are scheduled according to the ReconnectionPolicy in place.
    When this event is triggered, it is possible to call the host getInitialReconnectionAttemptFuture method to wait until the initial and immediate reconnection attempt succeed or fail.
    Note that some StateListener may ignore that event. If a node that that is suspected down turns out to be truly down (that is, the driver cannot successfully connect to it right away), then onDown will be called.
    
    Specified by:
    
    onSuspected in interface Host.StateListener
  - onDown
```
public void onDown(Host host)
```
    Description copied from interface: Host.StateListener
    
    Called when a node is determined to be down.
    
    Specified by:
    
    onDown in interface Host.StateListener
    
    Parameters:
    host - the host that has been detected down.
  - onAdd
```
public void onAdd(Host host)
```
    Description copied from interface: Host.StateListener
    
    Called when a new node is added to the cluster.
    The newly added node should be considered up.
    
    Specified by:
    
    onAdd in interface Host.StateListener
    
    Parameters:
    host - the host that has been newly added.
  - onRemove
```
public void onRemove(Host host)
```
    Description copied from interface: Host.StateListener
    
    Called when a node is removed from the cluster.
    
    Specified by:
    
    onRemove in interface Host.StateListener
    
    Parameters:
    host - the removed host.
  - close
```
public void close()
```
    Description copied from interface: CloseableLoadBalancingPolicy
    
    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 CloseableLoadBalancingPolicy

Class LatencyAwarePolicy

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getChildPolicy

builder

init

distance

newQueryPlan

getScoresSnapshot

onUp

onSuspected

onDown

onAdd

onRemove

close