DCAwareRoundRobinPolicy (DataStax Java Driver for Apache Cassandra

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

All Implemented Interfaces:

Host.StateListener, CloseableLoadBalancingPolicy, LoadBalancingPolicy
```
public class DCAwareRoundRobinPolicy
extends Object
implements LoadBalancingPolicy, CloseableLoadBalancingPolicy
```
A data-center aware Round-robin load balancing policy.
This policy provides round-robin queries over the node of the local data center. It also includes in the query plans returned a configurable number of hosts in the remote data centers, but those are always tried after the local nodes. In other words, this policy guarantees that no host in a remote data center will be queried unless no host in the local data center can be reached.
If used with a single data center, this policy is equivalent to the LoadBalancingPolicy.RoundRobin policy, but its DC awareness incurs a slight overhead so the LoadBalancingPolicy.RoundRobin policy could be preferred to this policy in that case.

Constructor Summary

Constructors
Constructor and Description
`DCAwareRoundRobinPolicy()` Creates a new datacenter aware round robin policy that auto-discover the local data-center.
`DCAwareRoundRobinPolicy(String localDc)` Creates a new datacenter aware round robin policy given the name of the local datacenter.
`DCAwareRoundRobinPolicy(String localDc, int usedHostsPerRemoteDc)` Creates a new DCAwareRoundRobin policy given the name of the local datacenter and that uses the provided number of host per remote datacenter as failover for the local hosts.
`DCAwareRoundRobinPolicy(String localDc, int usedHostsPerRemoteDc, boolean allowRemoteDCsForLocalConsistencyLevel)` Creates a new DCAwareRoundRobin policy given the name of the local datacenter and that uses the provided number of host per remote datacenter as failover for the local hosts.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`close()` Gets invoked at cluster shutdown.
`HostDistance`	`distance(Host host)` Return the HostDistance for the provided host.
`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

- Constructor Detail
  - DCAwareRoundRobinPolicy
```
public DCAwareRoundRobinPolicy()
```
    Creates a new datacenter aware round robin policy that auto-discover the local data-center.
    If this constructor is used, the data-center used as local will the data-center of the first Cassandra node the driver connects to. This will always be ok if all the contact points use at Cluster creation are in the local data-center. If it's not the case, you should provide the local data-center name yourself by using one of the other constructor of this class.
    This constructor is a shortcut for new DCAwareRoundRobinPolicy(null), and as such will ignore all hosts in remote data-centers.
  - DCAwareRoundRobinPolicy
```
public DCAwareRoundRobinPolicy(String localDc)
```
    Creates a new datacenter aware round robin policy given the name of the local datacenter.
    The name of the local datacenter provided must be the local datacenter name as known by Cassandra.
    The policy created will ignore all remote hosts. In other words, this is equivalent to new DCAwareRoundRobinPolicy(localDc, 0).
    
    Parameters:
    localDc - the name of the local datacenter (as known by Cassandra). If this is null, the policy will default to the data-center of the first node connected to.
  - DCAwareRoundRobinPolicy
```
public DCAwareRoundRobinPolicy(String localDc,
                       int usedHostsPerRemoteDc)
```
    Creates a new DCAwareRoundRobin policy given the name of the local datacenter and that uses the provided number of host per remote datacenter as failover for the local hosts.
    The name of the local datacenter provided must be the local datacenter name as known by Cassandra.
    If usedHostsPerRemoteDc > 0, then if for a query no host in the local datacenter can be reached and if the consistency level of the query is not LOCAL_ONE or LOCAL_QUORUM, then up to usedHostsPerRemoteDc host per remote data-center will be tried by the policy as a fallback. Please note that no remote host will be used for LOCAL_ONE and LOCAL_QUORUM since this would change the meaning of the consistency level (and thus somewhat break the consistency contract).
    
    Parameters:
    localDc - the name of the local datacenter (as known by Cassandra). If this is null, the policy will default to the data-center of the first node connected to.
    usedHostsPerRemoteDc - the number of host per remote datacenter that policies created by the returned factory should consider. Created policies distance method will return a HostDistance.REMOTE distance for only usedHostsPerRemoteDc hosts per remote datacenter. Other hosts of the remote datacenters will be ignored (and thus no connections to them will be maintained).
  - DCAwareRoundRobinPolicy
```
public DCAwareRoundRobinPolicy(String localDc,
                       int usedHostsPerRemoteDc,
                       boolean allowRemoteDCsForLocalConsistencyLevel)
```
    Creates a new DCAwareRoundRobin policy given the name of the local datacenter and that uses the provided number of host per remote datacenter as failover for the local hosts.
    This constructor is equivalent to DCAwareRoundRobinPolicy(String, int) but allows to override the policy of never using remote data-center nodes for LOCAL_ONE and LOCAL_QUORUM queries. It is however inadvisable to do so in almost all cases, as this would potentially break consistency guarantees and if you are fine with that, it's probably better to use a weaker consitency like ONE, TWO or THREE. As such, this constructor should generally be avoided in favor of DCAwareRoundRobinPolicy(String, int). Use it only if you know and understand what you do.
    
    Parameters:
    localDc - the name of the local datacenter (as known by Cassandra). If this is null, the policy will default to the data-center of the first node connected to.
    usedHostsPerRemoteDc - the number of host per remote datacenter that policies created by the returned factory should consider. Created policies distance method will return a HostDistance.REMOTE distance for only usedHostsPerRemoteDc hosts per remote datacenter. Other hosts of the remote datacenters will be ignored (and thus no connections to them will be maintained).
    allowRemoteDCsForLocalConsistencyLevel - whether or not the policy may return remote host when building query plan for query having consitency LOCAL_ONE and LOCAL_QUORUM.
- Method Detail
  - 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)
```
    Return the HostDistance for the provided host.
    This policy consider nodes in the local datacenter as LOCAL. For each remote datacenter, it considers a configurable number of hosts as REMOTE and the rest is IGNORED.
    To configure how many host in each remote datacenter is considered REMOTE, see DCAwareRoundRobinPolicy(String, int).
    
    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.
    The returned plan will always try each known host in the local datacenter first, and then, if none of the local host is reachable, will try up to a configurable number of other host per remote datacenter. The order of the local node in the returned query plan will follow a Round-robin algorithm.
    
    Specified by:
    
    newQueryPlan in interface LoadBalancingPolicy
    
    Parameters:
    loggedKeyspace - the keyspace currently logged in on for this query.
    statement - the query for which to build the plan.
    
    Returns:
    a new query plan, i.e. an iterator indicating which host to try first for querying, which one to use as failover, etc...
  - 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 DCAwareRoundRobinPolicy

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DCAwareRoundRobinPolicy

DCAwareRoundRobinPolicy

DCAwareRoundRobinPolicy

DCAwareRoundRobinPolicy

Method Detail

init

distance

newQueryPlan

onUp

onSuspected

onDown

onAdd

onRemove

close