retry package:cql-io

Use given RetrySettings during execution of some client action.

Retry settings control if and how retries are performed by the client upon encountering errors during query execution. There are three aspects to the retry settings:

1. What to retry. Determined by the retry handlers (setRetryHandlers).
2. How to perform the retries. Determined by the retry policy (setRetryPolicy).
3. Configuration adjustments to be performed before retrying. Determined by adjustConsistency, adjustSendTimeout and adjustResponseTimeout. These adjustments are performed once before the first retry and are scoped to the retries only.

Retry settings can be scoped to a client action by retry, thus locally overriding the "global" retry settings configured by setRetrySettings.

The default retry handlers permit a retry for the following errors:

• A HostError, since it always occurs before a query has been sent to the server.
• A ConnectionError that is a ConnectTimeout, since it always occurs before a query has been sent to the server.
• A ResponseError that is one of the following:
  • Unavailable, since that is an error response from a coordinator before the query is actually executed.
  • A ReadTimeout that indicates that the required consistency level could be achieved but the data was unfortunately chosen by the coordinator to be returned from a replica that turned out to be unavailable. A retry has a good chance of getting the data from one of the other replicas.
  • A WriteTimeout for a write to the batch log failed. The batch log is written prior to execution of the statements of the batch and hence these errors are safe to retry.

The default retry policy permits a single, immediate retry.

Default retry settings, combining defRetryHandlers with defRetryPolicy. Consistency is never reduced on retries and timeout values remain unchanged.

The eager retry handlers permit a superset of the errors of defRetryHandlers, namely:

• Any ResponseError that is a ReadTimeout, WriteTimeout, Overloaded, Unavailable or ServerError.
• Any ConnectionError.
• Any IOException.
• Any HostError.
• Any SomeSSLException (if an SSL context is configured).

Notably, these retry handlers are only safe to use for idempotent queries, or if a duplicate write has no severe consequences in the context of the application's data model.

The eager retry policy permits 5 retries with exponential backoff (base-2) with an initial delay of 100ms, i.e. the retries will be performed with 100ms, 200ms, 400ms, 800ms and 1.6s delay, respectively, for a maximum delay of ~3s.

Eager retry settings, combining eagerRetryHandlers with eagerRetryPolicy. Consistency is never reduced on retries and timeout values remain unchanged.

Never retry.

Set the exception handlers that decide whether a request can be retried by the client, i.e. what errors are permissible to retry. For configuring how the retries are performed, see setRetryPolicy.

Set the RetryPolicy to apply on retryable exceptions, which determines the number and distribution of retries over time, i.e. how retries are performed. Configuring a retry policy does not specify what errors should actually be retried. See setRetryHandlers.

Set the retry settings to use.