Tuning policies determine load balancing, retrying queries, and reconnecting to a node.
Load balancing policy
The load balancing policy determines which node to execute a query on.
- HostDistance distance(Host host): determines the distance to the specified host. The values are HostDistance.IGNORED, LOCAL, and REMOTE.
- void init(Cluster cluster, Collection<Host> hosts): initializes the policy. The driver calls this method only once and before any other method calls are made.
- Iterator<Host> newQueryPlan(): returns the hosts to use for a query. Each new query calls this method.
The reconnection policy determines how often a reconnection to a dead node is attempted.
- ReconnectionPolicy.ReconnectionSchedule newSchedule(): creates a new schedule to use in reconnection attempts.
The retry policy determines a default behavior to adopt when a request either times out or if a node is unavailable.
A client may send requests to any node in a cluster whether or not it is a replica of the data being queried. This node is placed into the coordinator role temporarily. Which node is the coordinator is determined by the load balancing policy for the cluster. The coordinator is responsible for routing the request to the appropriate replicas. If a coordinator fails during a request, the driver connects to a different node and retries the request. If the coordinator knows before a request that a replica is down, it can throw an UnavailableException, but if the replica fails after the request is made, it throws a TimeoutException. Of course, this all depends on the consistency level set for the query before executing it.
A retry policy centralizes the handling of query retries, minimizing the need for catching and handling of exceptions in your business code.
- RetryPolicy.RetryDecision onReadTimeout(Query query, ConsistencyLevel cl, int requiredResponses, int receivedResponses, boolean dataRetrieved, int nbRetry)
- RetryPolicy.RetryDecision onUnavailable(Query query, ConsistencyLevel cl, int requiredReplica, int aliveReplica, int nbRetry)
- RetryPolicy.RetryDecision onWriteTimeout(Query query, ConsistencyLevel cl, WriteType writeType, int requiredAcks, int receivedAcks, int nbRetry)