com.datastax.driver.core.policies

Class DowngradingConsistencyRetryPolicy

java.lang.Object

com.datastax.driver.core.policies.DowngradingConsistencyRetryPolicy

All Implemented Interfaces:

RetryPolicy

public class DowngradingConsistencyRetryPolicy
extends Object
implements RetryPolicy

A retry policy that sometimes retries with a lower consistency level than the one initially requested.

BEWARE: this policy may retry queries using a lower consistency level than the one initially requested. By doing so, it may break consistency guarantees. In other words, if you use this retry policy, there are cases (documented below) where a read at QUORUM may not see a preceding write at QUORUM. Do not use this policy unless you have understood the cases where this can happen and are ok with that. It is also highly recommended to always wrap this policy into LoggingRetryPolicy to log the occurrences of such consistency breaks.

This policy implements the same retries than the DefaultRetryPolicy policy. But on top of that, it also retries in the following cases:

• On a read timeout: if the number of replicas that responded is greater than one, but lower than is required by the requested consistency level, the operation is retried at a lower consistency level.
• On a write timeout: if the operation is a WriteType.UNLOGGED_BATCH and at least one replica acknowledged the write, the operation is retried at a lower consistency level. Furthermore, for other operations, if at least one replica acknowledged the write, the timeout is ignored.
• On an unavailable exception: if at least one replica is alive, the operation is retried at a lower consistency level.

The lower consistency level to use for retries is determined by the following rules:

• if more than 3 replicas responded, use THREE.
• if 1, 2 or 3 replicas responded, use the corresponding level ONE, TWO or THREE.

Note that if the initial consistency level was EACH_QUORUM, Cassandra returns the number of live replicas in the datacenter that failed to reach consistency, not the overall number in the cluster. Therefore if this number is 0, we still retry at ONE, on the assumption that a host may still be up in another datacenter.

The reasoning being this retry policy is the following one. If, based on the information the Cassandra coordinator node returns, retrying the operation with the initially requested consistency has a chance to succeed, do it. Otherwise, if based on this information we know the initially requested consistency level cannot be achieve currently, then:

• For writes, ignore the exception (thus silently failing the consistency requirement) if we know the write has been persisted on at least one replica.
• For reads, try reading at a lower consistency level (thus silently failing the consistency requirement).

In other words, this policy implements the idea that if the requested consistency level cannot be achieved, the next best thing for writes is to make sure the data is persisted, and that reading something is better than reading nothing, even if there is a risk of reading stale data.

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 DowngradingConsistencyRetryPolicy	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 DowngradingConsistencyRetryPolicy 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. If less replica responded than required by the consistency level (but at least one replica did respond), the operation is retried at a lower consistency level. If enough replica responded but data was not retrieve, the operation is retried with the initial consistency level. Otherwise, an exception is thrown.

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:

the retry decision. If RetryDecision.RETHROW is returned, a ReadTimeoutException will be thrown for the operation.

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. If writeType == WriteType.BATCH_LOG, the write is retried with the initial consistency level. If writeType == WriteType.UNLOGGED_BATCH and at least one replica acknowledged, the write is retried with a lower consistency level (with unlogged batch, a write timeout can always mean that part of the batch haven't been persisted at all, even if receivedAcks > 0). For other write types (WriteType.SIMPLE and WriteType.BATCH), if we know the write has been persisted on at least one replica, we ignore the exception. Otherwise, an exception is thrown.

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:

the retry decision. If RetryDecision.RETHROW is returned, a WriteTimeoutException will be thrown for the operation.

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 triggers a maximum of one retry. If at least one replica is know to be alive, the operation is retried at a lower consistency level.

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 or a SERVER_ERROR.

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

For historical reasons, this implementation triggers a retry on the next host in the query plan with the same consistency level, regardless of the statement's idempotence. Note that this breaks the general rule stated in RetryPolicy.onRequestError(Statement, ConsistencyLevel, DriverException, int): "a retry should only be attempted if the request is known to be idempotent".`

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