com.datastax.driver.core.policies

Class DefaultRetryPolicy

java.lang.Object

com.datastax.driver.core.policies.DefaultRetryPolicy

All Implemented Interfaces:

RetryPolicy

public class DefaultRetryPolicy
extends Object
implements RetryPolicy

The default retry policy.

This policy retries queries in only two cases:

• On a read timeout, retries once on the same host if enough replicas replied but data was not retrieved.
• On a write timeout, retries once on the same host if we timeout while writing the distributed log used by batch statements.
• On an unavailable exception, retries once on the next host.
• On a request error, such as a client timeout, the query is retried on the next host. Do not retry on read or write failures.

This retry policy is conservative in that it will never retry with a different consistency level than the one of the initial operation.

In some cases, it may be convenient to use a more aggressive retry policy like DowngradingConsistencyRetryPolicy.

Nested Class Summary

Nested classes/interfaces inherited from interface com.datastax.driver.core.policies.RetryPolicy

RetryPolicy.RetryDecision

Field Summary

Fields

Modifier and Type	Field and Description
static DefaultRetryPolicy	INSTANCE

Method Summary

Modifier and Type	Method and Description
void	close() Gets invoked at cluster shutdown.
void	init(Cluster cluster) Gets invoked at cluster startup.
RetryPolicy.RetryDecision	onReadTimeout(Statement statement, ConsistencyLevel cl, int requiredResponses, int receivedResponses, boolean dataRetrieved, int nbRetry) Defines whether to retry and at which consistency level on a read timeout.
RetryPolicy.RetryDecision	onRequestError(Statement statement, ConsistencyLevel cl, DriverException e, int nbRetry) Defines whether to retry and at which consistency level on an unexpected error.
RetryPolicy.RetryDecision	onUnavailable(Statement statement, ConsistencyLevel cl, int requiredReplica, int aliveReplica, int nbRetry) Defines whether to retry and at which consistency level on an unavailable exception.
RetryPolicy.RetryDecision	onWriteTimeout(Statement statement, ConsistencyLevel cl, WriteType writeType, int requiredAcks, int receivedAcks, int nbRetry) Defines whether to retry and at which consistency level on a write timeout.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INSTANCE

public static final DefaultRetryPolicy INSTANCE

Method Detail

onReadTimeout

public RetryPolicy.RetryDecision onReadTimeout(Statement statement,
                                               ConsistencyLevel cl,
                                               int requiredResponses,
                                               int receivedResponses,
                                               boolean dataRetrieved,
                                               int nbRetry)

Defines whether to retry and at which consistency level on a read timeout.

Note that this method may be called even if requiredResponses >= receivedResponses if dataPresent is false (see ReadTimeoutException.wasDataRetrieved()).

This implementation triggers a maximum of one retry, and only if enough replicas had responded to the read request but data was not retrieved amongst those. Indeed, that case usually means that enough replica are alive to satisfy the consistency but the coordinator picked a dead one for data retrieval, not having detected that replica as dead yet. The reasoning for retrying then is that by the time we get the timeout the dead replica will likely have been detected as dead and the retry has a high chance of success.

Specified by:

onReadTimeout in interface RetryPolicy

Parameters:

statement - the original query that timed out.

cl - the requested consistency level of the read that timed out. Note that this can never be a serial consistency level.

requiredResponses - the number of responses that were required to achieve the requested consistency level.

receivedResponses - the number of responses that had been received by the time the timeout exception was raised.

dataRetrieved - whether actual data (by opposition to data checksum) was present in the received responses.

nbRetry - the number of retry already performed for this operation.

Returns:

RetryDecision.retry(cl) if no retry attempt has yet been tried and receivedResponses >= requiredResponses && !dataRetrieved, RetryDecision.rethrow() otherwise.

onWriteTimeout

public RetryPolicy.RetryDecision onWriteTimeout(Statement statement,
                                                ConsistencyLevel cl,
                                                WriteType writeType,
                                                int requiredAcks,
                                                int receivedAcks,
                                                int nbRetry)

Defines whether to retry and at which consistency level on a write timeout.

Note that if a statement is not idempotent, the driver will never retry it on a write timeout (this method won't even be called).

This implementation triggers a maximum of one retry, and only in the case of a WriteType.BATCH_LOG write. The reasoning for the retry in that case is that write to the distributed batch log is tried by the coordinator of the write against a small subset of all the nodes alive in the local datacenter. Hence, a timeout usually means that none of the nodes in that subset were alive but the coordinator hasn't detected them as dead. By the time we get the timeout the dead nodes will likely have been detected as dead and the retry has thus a high chance of success.

Specified by:

onWriteTimeout in interface RetryPolicy

Parameters:

statement - the original query that timed out.

cl - the requested consistency level of the write that timed out. If the timeout occurred at the "paxos" phase of a Lightweight transaction, then cl will actually be the requested serial consistency level. Beware that serial consistency levels should never be passed to a RetryDecision as this would invariably trigger an InvalidQueryException. Also, when cl is serial, then writeType is always CAS.

writeType - the type of the write that timed out.

requiredAcks - the number of acknowledgments that were required to achieve the requested consistency level.

receivedAcks - the number of acknowledgments that had been received by the time the timeout exception was raised.

nbRetry - the number of retry already performed for this operation.

Returns:

RetryDecision.retry(cl) if no retry attempt has yet been tried and writeType == WriteType.BATCH_LOG, RetryDecision.rethrow() otherwise.

onUnavailable

public RetryPolicy.RetryDecision onUnavailable(Statement statement,
                                               ConsistencyLevel cl,
                                               int requiredReplica,
                                               int aliveReplica,
                                               int nbRetry)

Defines whether to retry and at which consistency level on an unavailable exception.

This implementation does the following:

• if this is the first retry (nbRetry == 0), it triggers a retry on the next host in the query plan with the same consistency level (RetryDecision#tryNextHost(null). The rationale is that the first coordinator might have been network-isolated from all other nodes (thinking they're down), but still able to communicate with the client; in that case, retrying on the same host has almost no chance of success, but moving to the next host might solve the issue.
• otherwise, the exception is rethrow.

Specified by:

onUnavailable in interface RetryPolicy

Parameters:

statement - the original query for which the consistency level cannot be achieved.

cl - the requested consistency level for the operation. If the operation failed at the "paxos" phase of a Lightweight transaction, then cl will actually be the requested serial consistency level. Beware that serial consistency levels should never be passed to a RetryDecision as this would invariably trigger an InvalidQueryException.

requiredReplica - the number of replica that should have been (known) alive for the operation to be attempted.

aliveReplica - the number of replica that were know to be alive by the coordinator of the operation.

nbRetry - the number of retry already performed for this operation.

Returns:

the retry decision. If RetryDecision.RETHROW is returned, an UnavailableException will be thrown for the operation.

onRequestError

public RetryPolicy.RetryDecision onRequestError(Statement statement,
                                                ConsistencyLevel cl,
                                                DriverException e,
                                                int nbRetry)

Defines whether to retry and at which consistency level on an unexpected error.

This method might be invoked in the following situations:

1. On a client timeout, while waiting for the server response (see SocketOptions.getReadTimeoutMillis());
2. On a connection error (socket closed, etc.);
3. When the contacted host replies with an OVERLOADED error, SERVER_ERROR, READ_FAILURE or WRITE_FAILURE.

Note that when such an error occurs, there is no guarantee that the mutation has been applied server-side or not. Therefore, if a statement is not idempotent, the driver will never retry it (this method won't even be called).

Specified by:

onRequestError in interface RetryPolicy

Parameters:

statement - the original query that failed.

cl - the requested consistency level for the operation. Note that this is not necessarily the achieved consistency level (if any), and it is never a serial one.

e - the exception that caused this request to fail.

nbRetry - the number of retries already performed for this operation.

Returns:

the retry decision. If RetryDecision.RETHROW is returned, the DriverException passed to this method will be thrown for the operation.

init

public void init(Cluster cluster)

Description copied from interface: RetryPolicy

Gets invoked at cluster startup.

Specified by:

init in interface RetryPolicy

Parameters:

cluster - the cluster that this policy is associated with.

close

public void close()

Description copied from interface: RetryPolicy

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 RetryPolicy