Package software.amazon.awssdk.retries.api

Interface RetryStrategy

All Superinterfaces:

AutoCloseable, SdkAutoCloseable

@ThreadSafe
@SdkPublicApi
public interface RetryStrategy
extends SdkAutoCloseable

A strategy used by an SDK to determine when something should be retried.

We do not recommend SDK users create their own retry strategies. We recommend refining an existing strategy:

1. If you are using the strategy with a service, you can get the existing strategy from that service via [ServiceName]Client.defaults().retryStrategy().
2. RetryStrategies from the software.amazon.awssdk:retries module.

Terminology:

1. An attempt is a single invocation of an action.
2. The attempt count is which attempt (starting with 1) the SDK is attempting to make.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	RetryStrategy.Builder<B extends RetryStrategy.Builder<B,T>,T extends RetryStrategy>	Builder to create immutable instances of RetryStrategy.

Method Summary

Modifier and Type	Method	Description
AcquireInitialTokenResponse	acquireInitialToken(AcquireInitialTokenRequest request)	Acquire a retry token synchronously.
default CompletableFuture<AcquireInitialTokenResponse>	acquireInitialTokenAsync(AcquireInitialTokenRequest request)	Acquire a retry token asynchronously.
default void	close()
int	maxAttempts()	Returns the maximum numbers attempts that this retry policy will allow.
RecordSuccessResponse	recordSuccess(RecordSuccessRequest request)	Invoked after an attempt succeeds.
RefreshRetryTokenResponse	refreshRetryToken(RefreshRetryTokenRequest request)	Refresh a retry token synchronously.
default CompletableFuture<RefreshRetryTokenResponse>	refreshRetryTokenAsync(RefreshRetryTokenRequest request)	Refresh a retry token asynchronously.
RetryStrategy.Builder<?,?>	toBuilder()	Create a new RetryStrategy.Builder with the current configuration.
default boolean	useClientDefaults()	Returns whether the retry strategy uses default retry predicates.

Method Details

acquireInitialToken

AcquireInitialTokenResponse acquireInitialToken(AcquireInitialTokenRequest request)

Acquire a retry token synchronously. Invoked before the first request attempt.

Callers MUST wait for the delay returned by this call before making the first attempt. Callers that wish to retry a failed attempt MUST call refreshRetryToken(software.amazon.awssdk.retries.api.RefreshRetryTokenRequest) before doing so.

If the attempt was successful, callers MUST call recordSuccess(software.amazon.awssdk.retries.api.RecordSuccessRequest).

Throws:

NullPointerException - if a required parameter is not specified

TokenAcquisitionFailedException - if a token cannot be acquired

acquireInitialTokenAsync

default CompletableFuture<AcquireInitialTokenResponse> acquireInitialTokenAsync(AcquireInitialTokenRequest request)

Acquire a retry token asynchronously. Invoked before the first request attempt.

Callers MUST wait for the delay returned by this call before making the first attempt. Callers that wish to retry a failed attempt MUST call refreshRetryToken(software.amazon.awssdk.retries.api.RefreshRetryTokenRequest) before doing so.

If the attempt was successful, callers MUST call recordSuccess(software.amazon.awssdk.retries.api.RecordSuccessRequest).

The future is completed exceptionally with NullPointerException if a required parameter is null.

The future is completed exceptionally with TokenAcquisitionFailedException if a token cannot be acquired.

refreshRetryToken

RefreshRetryTokenResponse refreshRetryToken(RefreshRetryTokenRequest request)

Refresh a retry token synchronously. Invoked before each subsequent (non-first) request attempt.

Callers MUST wait for the delay returned by this call before making the next attempt. If the next attempt fails, callers MUST re-call refreshRetryToken(software.amazon.awssdk.retries.api.RefreshRetryTokenRequest) before attempting another retry. This call invalidates the provided token, and returns a new one. Callers MUST use the new token.

If the attempt was successful, callers MUST call recordSuccess(software.amazon.awssdk.retries.api.RecordSuccessRequest).

Throws:

NullPointerException - if a required parameter is not specified

IllegalArgumentException - if the provided token was not issued by this strategy or the provided token was already used for a previous refresh or success call.

TokenAcquisitionFailedException - if a token cannot be acquired

refreshRetryTokenAsync

default CompletableFuture<RefreshRetryTokenResponse> refreshRetryTokenAsync(RefreshRetryTokenRequest request)

Refresh a retry token asynchronously. Invoked before each subsequent (non-first) request attempt.

Callers MUST wait for the delay returned by this call before making the next attempt. If the next attempt fails, callers MUST re-call refreshRetryToken(software.amazon.awssdk.retries.api.RefreshRetryTokenRequest) before attempting another retry. This call invalidates the provided token, and returns a new one. Callers MUST use the new token.

If the attempt was successful, callers MUST call recordSuccess(software.amazon.awssdk.retries.api.RecordSuccessRequest).

The future is completed exceptionally with NullPointerException if a required parameter is not specified.

The future is completed exceptionally with IllegalArgumentException if the provided token was not issued by this strategy or the provided token was already used for a previous refresh or success call.

The future is completed exceptionally with TokenAcquisitionFailedException if a token cannot be acquired.

recordSuccess

RecordSuccessResponse recordSuccess(RecordSuccessRequest request)

Invoked after an attempt succeeds.

Throws:

NullPointerException - if a required parameter is not specified

IllegalArgumentException - if the provided token was not issued by this strategy or the provided token was already used for a previous refresh or success call.

maxAttempts

int maxAttempts()

Returns the maximum numbers attempts that this retry policy will allow.

Returns:

the maximum numbers attempts that this retry policy will allow.

useClientDefaults

default boolean useClientDefaults()

Returns whether the retry strategy uses default retry predicates.

Returns:

true if this retry strategy should use the default retry predicates, false otherwise.

toBuilder

RetryStrategy.Builder<?,?> toBuilder()

Create a new RetryStrategy.Builder with the current configuration.

This is useful for modifying the strategy's behavior, like conditions or max retries.

close

default void close()

Specified by:

close in interface AutoCloseable

Specified by:

close in interface SdkAutoCloseable