com.datastax.oss.driver.api.core.retry

Interface RetryPolicy

All Superinterfaces:

AutoCloseable

public interface RetryPolicy
extends AutoCloseable

Defines the behavior to adopt when a request fails.

For each request, the driver gets a "query plan" (a list of coordinators to try) from the LoadBalancingPolicy, and tries each node in sequence. This policy is invoked if the request to that node fails.

The methods of this interface are invoked on I/O threads, therefore implementations should never block. In particular, don't call Thread.sleep(long) to retry after a delay: this would prevent asynchronous processing of other requests, and very negatively impact throughput. If the application needs to back off and retry later, this should be implemented in client code, not in this policy.

Method Summary

Modifier and Type	Method and Description
void	close() Called when the cluster that this policy is associated with closes.
RetryDecision	onErrorResponse(Request request, CoordinatorException error, int retryCount) Deprecated. As of version 4.10, use onErrorResponseVerdict(Request, CoordinatorException, int) instead.
default RetryVerdict	onErrorResponseVerdict(Request request, CoordinatorException error, int retryCount) Whether to retry when the server replied with a recoverable error (other than READ_TIMEOUT, WRITE_TIMEOUT or UNAVAILABLE).
RetryDecision	onReadTimeout(Request request, ConsistencyLevel cl, int blockFor, int received, boolean dataPresent, int retryCount) Deprecated. As of version 4.10, use onReadTimeoutVerdict(Request, ConsistencyLevel, int, int, boolean, int) instead.
default RetryVerdict	onReadTimeoutVerdict(Request request, ConsistencyLevel cl, int blockFor, int received, boolean dataPresent, int retryCount) Whether to retry when the server replied with a READ_TIMEOUT error; this indicates a server-side timeout during a read query, i.e.
RetryDecision	onRequestAborted(Request request, Throwable error, int retryCount) Deprecated. As of version 4.10, use onRequestAbortedVerdict(Request, Throwable, int) instead.
default RetryVerdict	onRequestAbortedVerdict(Request request, Throwable error, int retryCount) Whether to retry when a request was aborted before we could get a response from the server.
RetryDecision	onUnavailable(Request request, ConsistencyLevel cl, int required, int alive, int retryCount) Deprecated. As of version 4.10, use onUnavailableVerdict(Request, ConsistencyLevel, int, int, int) instead.
default RetryVerdict	onUnavailableVerdict(Request request, ConsistencyLevel cl, int required, int alive, int retryCount) Whether to retry when the server replied with an UNAVAILABLE error; this indicates that the coordinator determined that there were not enough replicas alive to perform a query with the requested consistency level.
RetryDecision	onWriteTimeout(Request request, ConsistencyLevel cl, WriteType writeType, int blockFor, int received, int retryCount) Deprecated. As of version 4.10, use onWriteTimeoutVerdict(Request, ConsistencyLevel, WriteType, int, int, int) instead.
default RetryVerdict	onWriteTimeoutVerdict(Request request, ConsistencyLevel cl, WriteType writeType, int blockFor, int received, int retryCount) Whether to retry when the server replied with a WRITE_TIMEOUT error; this indicates a server-side timeout during a write query, i.e.

Method Detail

onReadTimeout

@Deprecated
RetryDecision onReadTimeout(@NonNull
                                        Request request,
                                        @NonNull
                                        ConsistencyLevel cl,
                                        int blockFor,
                                        int received,
                                        boolean dataPresent,
                                        int retryCount)

Deprecated. As of version 4.10, use onReadTimeoutVerdict(Request, ConsistencyLevel, int, int, boolean, int) instead.

Whether to retry when the server replied with a READ_TIMEOUT error; this indicates a server-side timeout during a read query, i.e. some replicas did not reply to the coordinator in time.

Parameters:

request - the request that timed out.

cl - the requested consistency level.

blockFor - the minimum number of replica acknowledgements/responses that were required to fulfill the operation.

received - the number of replica that had acknowledged/responded to the operation before it failed.

dataPresent - whether the actual data was amongst the received replica responses. See ReadTimeoutException.wasDataPresent().

retryCount - how many times the retry policy has been invoked already for this request (not counting the current invocation).

onReadTimeoutVerdict

default RetryVerdict onReadTimeoutVerdict(@NonNull
                                          Request request,
                                          @NonNull
                                          ConsistencyLevel cl,
                                          int blockFor,
                                          int received,
                                          boolean dataPresent,
                                          int retryCount)

Whether to retry when the server replied with a READ_TIMEOUT error; this indicates a server-side timeout during a read query, i.e. some replicas did not reply to the coordinator in time.

Parameters:

request - the request that timed out.

cl - the requested consistency level.

blockFor - the minimum number of replica acknowledgements/responses that were required to fulfill the operation.

received - the number of replica that had acknowledged/responded to the operation before it failed.

dataPresent - whether the actual data was amongst the received replica responses. See ReadTimeoutException.wasDataPresent().

retryCount - how many times the retry policy has been invoked already for this request (not counting the current invocation).

onWriteTimeout

@Deprecated
RetryDecision onWriteTimeout(@NonNull
                                         Request request,
                                         @NonNull
                                         ConsistencyLevel cl,
                                         @NonNull
                                         WriteType writeType,
                                         int blockFor,
                                         int received,
                                         int retryCount)

Deprecated. As of version 4.10, use onWriteTimeoutVerdict(Request, ConsistencyLevel, WriteType, int, int, int) instead.

Whether to retry when the server replied with a WRITE_TIMEOUT error; this indicates a server-side timeout during a write query, i.e. some replicas did not reply to the coordinator in time.

Note that this method will only be invoked for Request.isIdempotent() idempotent} requests: when a write times out, it is impossible to determine with 100% certainty whether the mutation was applied or not, so the write is never safe to retry; the driver will rethrow the error directly, without invoking the retry policy.

Parameters:

request - the request that timed out.

cl - the requested consistency level.

writeType - the type of the write for which the timeout was raised.

blockFor - the minimum number of replica acknowledgements/responses that were required to fulfill the operation.

received - the number of replica that had acknowledged/responded to the operation before it failed.

retryCount - how many times the retry policy has been invoked already for this request (not counting the current invocation).

onWriteTimeoutVerdict

default RetryVerdict onWriteTimeoutVerdict(@NonNull
                                           Request request,
                                           @NonNull
                                           ConsistencyLevel cl,
                                           @NonNull
                                           WriteType writeType,
                                           int blockFor,
                                           int received,
                                           int retryCount)

Whether to retry when the server replied with a WRITE_TIMEOUT error; this indicates a server-side timeout during a write query, i.e. some replicas did not reply to the coordinator in time.

Note that this method will only be invoked for Request.isIdempotent() idempotent} requests: when a write times out, it is impossible to determine with 100% certainty whether the mutation was applied or not, so the write is never safe to retry; the driver will rethrow the error directly, without invoking the retry policy.

Parameters:

request - the request that timed out.

cl - the requested consistency level.

writeType - the type of the write for which the timeout was raised.

blockFor - the minimum number of replica acknowledgements/responses that were required to fulfill the operation.

received - the number of replica that had acknowledged/responded to the operation before it failed.

retryCount - how many times the retry policy has been invoked already for this request (not counting the current invocation).

onUnavailable

@Deprecated
RetryDecision onUnavailable(@NonNull
                                        Request request,
                                        @NonNull
                                        ConsistencyLevel cl,
                                        int required,
                                        int alive,
                                        int retryCount)

Deprecated. As of version 4.10, use onUnavailableVerdict(Request, ConsistencyLevel, int, int, int) instead.

Whether to retry when the server replied with an UNAVAILABLE error; this indicates that the coordinator determined that there were not enough replicas alive to perform a query with the requested consistency level.

Parameters:

request - the request that timed out.

cl - the requested consistency level.

required - the number of replica acknowledgements/responses required to perform the operation (with its required consistency level).

alive - the number of replicas that were known to be alive by the coordinator node when it tried to execute the operation.

retryCount - how many times the retry policy has been invoked already for this request (not counting the current invocation).

onUnavailableVerdict

default RetryVerdict onUnavailableVerdict(@NonNull
                                          Request request,
                                          @NonNull
                                          ConsistencyLevel cl,
                                          int required,
                                          int alive,
                                          int retryCount)

Whether to retry when the server replied with an UNAVAILABLE error; this indicates that the coordinator determined that there were not enough replicas alive to perform a query with the requested consistency level.

Parameters:

request - the request that timed out.

cl - the requested consistency level.

required - the number of replica acknowledgements/responses required to perform the operation (with its required consistency level).

alive - the number of replicas that were known to be alive by the coordinator node when it tried to execute the operation.

retryCount - how many times the retry policy has been invoked already for this request (not counting the current invocation).

onRequestAborted

@Deprecated
RetryDecision onRequestAborted(@NonNull
                                           Request request,
                                           @NonNull
                                           Throwable error,
                                           int retryCount)

Deprecated. As of version 4.10, use onRequestAbortedVerdict(Request, Throwable, int) instead.

Whether to retry when a request was aborted before we could get a response from the server.

This can happen in two cases: if the connection was closed due to an external event (this will manifest as a ClosedConnectionException, or HeartbeatException for a heartbeat failure); or if there was an unexpected error while decoding the response (this can only be a driver bug).

Note that this method will only be invoked for idempotent requests: when execution was aborted before getting a response, it is impossible to determine with 100% certainty whether a mutation was applied or not, so a write is never safe to retry; the driver will rethrow the error directly, without invoking the retry policy.

Parameters:

request - the request that was aborted.

error - the error.

retryCount - how many times the retry policy has been invoked already for this request (not counting the current invocation).

onRequestAbortedVerdict

default RetryVerdict onRequestAbortedVerdict(@NonNull
                                             Request request,
                                             @NonNull
                                             Throwable error,
                                             int retryCount)

Whether to retry when a request was aborted before we could get a response from the server.

This can happen in two cases: if the connection was closed due to an external event (this will manifest as a ClosedConnectionException, or HeartbeatException for a heartbeat failure); or if there was an unexpected error while decoding the response (this can only be a driver bug).

Note that this method will only be invoked for idempotent requests: when execution was aborted before getting a response, it is impossible to determine with 100% certainty whether a mutation was applied or not, so a write is never safe to retry; the driver will rethrow the error directly, without invoking the retry policy.

Parameters:

request - the request that was aborted.

error - the error.

retryCount - how many times the retry policy has been invoked already for this request (not counting the current invocation).

onErrorResponse

@Deprecated
RetryDecision onErrorResponse(@NonNull
                                          Request request,
                                          @NonNull
                                          CoordinatorException error,
                                          int retryCount)

Deprecated. As of version 4.10, use onErrorResponseVerdict(Request, CoordinatorException, int) instead.

Whether to retry when the server replied with a recoverable error (other than READ_TIMEOUT, WRITE_TIMEOUT or UNAVAILABLE).

This can happen for the following errors: OverloadedException, ServerError, TruncateException, ReadFailureException, WriteFailureException.

The following errors are handled internally by the driver, and therefore will never be encountered in this method:

• BootstrappingException: always retried on the next node;
• QueryValidationException (and its subclasses), FunctionFailureException and ProtocolError: always rethrown.

Note that this method will only be invoked for Request.isIdempotent() idempotent} requests: when execution was aborted before getting a response, it is impossible to determine with 100% certainty whether a mutation was applied or not, so a write is never safe to retry; the driver will rethrow the error directly, without invoking the retry policy.

Parameters:

request - the request that failed.

error - the error.

retryCount - how many times the retry policy has been invoked already for this request (not counting the current invocation).

onErrorResponseVerdict

default RetryVerdict onErrorResponseVerdict(@NonNull
                                            Request request,
                                            @NonNull
                                            CoordinatorException error,
                                            int retryCount)

Whether to retry when the server replied with a recoverable error (other than READ_TIMEOUT, WRITE_TIMEOUT or UNAVAILABLE).

This can happen for the following errors: OverloadedException, ServerError, TruncateException, ReadFailureException, WriteFailureException.

The following errors are handled internally by the driver, and therefore will never be encountered in this method:

• BootstrappingException: always retried on the next node;
• QueryValidationException (and its subclasses), FunctionFailureException and ProtocolError: always rethrown.

Note that this method will only be invoked for Request.isIdempotent() idempotent} requests: when execution was aborted before getting a response, it is impossible to determine with 100% certainty whether a mutation was applied or not, so a write is never safe to retry; the driver will rethrow the error directly, without invoking the retry policy.

Parameters:

request - the request that failed.

error - the error.

retryCount - how many times the retry policy has been invoked already for this request (not counting the current invocation).

close

void close()

Called when the cluster that this policy is associated with closes.

Specified by:

close in interface AutoCloseable