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 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

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

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.

newQueryPlan

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.

onSuspected

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.