Class TokenBucketRetryCondition

java.lang.Object

software.amazon.awssdk.core.retry.conditions.TokenBucketRetryCondition

All Implemented Interfaces:

RetryCondition

@SdkPublicApi
public class TokenBucketRetryCondition
extends Object
implements RetryCondition

A RetryCondition that limits the number of retries made by the SDK using a token bucket algorithm. "Tokens" are acquired from the bucket whenever shouldRetry(software.amazon.awssdk.core.retry.RetryPolicyContext) returns true, and are released to the bucket whenever requestSucceeded(software.amazon.awssdk.core.retry.RetryPolicyContext) or requestWillNotBeRetried(software.amazon.awssdk.core.retry.RetryPolicyContext) are invoked.

If "tokens" cannot be acquired from the bucket, it means too many requests have failed and the request will not be allowed to retry until we start to see initial non-retried requests succeed via requestSucceeded(RetryPolicyContext).

This prevents the client from holding the calling thread to retry when it's likely that it will fail anyway.

This is currently included in the default RetryPolicy.aggregateRetryCondition(), but can be disabled by setting the RetryPolicy.Builder.retryCapacityCondition(software.amazon.awssdk.core.retry.conditions.RetryCondition) to null.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	TokenBucketRetryCondition.Builder	Configure and create a TokenBucketRetryCondition.
static final class	TokenBucketRetryCondition.Capacity	The number of tokens in the token bucket after a specific token acquisition succeeds.

Method Summary

Modifier and Type	Method	Description
static TokenBucketRetryCondition.Builder	builder()	Create a builder that allows fine-grained control over the token policy of this condition.
static TokenBucketRetryCondition	create()	Create a condition using the RetryMode.defaultRetryMode().
boolean	equals(Object o)
static TokenBucketRetryCondition	forRetryMode(RetryMode retryMode)	Create a condition using the configured RetryMode.
static Optional<TokenBucketRetryCondition.Capacity>	getCapacityForExecution(ExecutionAttributes attributes)	If shouldRetry(RetryPolicyContext) returned true for the provided execution, this method returns the TokenBucketRetryCondition.Capacity consumed by the request.
int	hashCode()
void	requestSucceeded(RetryPolicyContext context)	Called by the SDK to notify this condition that the provided request succeeded.
void	requestWillNotBeRetried(RetryPolicyContext context)	Called by the SDK to notify this condition that the provided request will not be retried, because some retry condition determined that it shouldn't be retried.
boolean	shouldRetry(RetryPolicyContext context)	Determine whether a request should or should not be retried.
int	tokensAvailable()	Retrieve the number of tokens currently available in the token bucket.
String	toString()

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Details

create

public static TokenBucketRetryCondition create()

Create a condition using the RetryMode.defaultRetryMode(). This is equivalent to forRetryMode(RetryMode.defaultRetryMode()).

For more detailed control, see builder().

forRetryMode

public static TokenBucketRetryCondition forRetryMode(RetryMode retryMode)

Create a condition using the configured RetryMode. The RetryMode.LEGACY does not subtract tokens from the token bucket when throttling exceptions are encountered. The RetryMode.STANDARD treats throttling and non- throttling exceptions as the same cost.

For more detailed control, see builder().

builder

public static TokenBucketRetryCondition.Builder builder()

Create a builder that allows fine-grained control over the token policy of this condition.

getCapacityForExecution

public static Optional<TokenBucketRetryCondition.Capacity> getCapacityForExecution(ExecutionAttributes attributes)

If shouldRetry(RetryPolicyContext) returned true for the provided execution, this method returns the TokenBucketRetryCondition.Capacity consumed by the request.

tokensAvailable

public int tokensAvailable()

Retrieve the number of tokens currently available in the token bucket. This is a volatile snapshot of the current value. See getCapacityForExecution(ExecutionAttributes) to see how much capacity was left in the bucket after a specific execution was considered.

shouldRetry

public boolean shouldRetry(RetryPolicyContext context)

Description copied from interface: RetryCondition

Determine whether a request should or should not be retried.

Specified by:

shouldRetry in interface RetryCondition

Parameters:

context - Context about the state of the last request and information about the number of requests made.

Returns:

True if the request should be retried, false if not.

requestWillNotBeRetried

public void requestWillNotBeRetried(RetryPolicyContext context)

Description copied from interface: RetryCondition

Called by the SDK to notify this condition that the provided request will not be retried, because some retry condition determined that it shouldn't be retried.

Specified by:

requestWillNotBeRetried in interface RetryCondition

requestSucceeded

public void requestSucceeded(RetryPolicyContext context)

Description copied from interface: RetryCondition

Called by the SDK to notify this condition that the provided request succeeded. This method is invoked even if the execution never failed before (RetryPolicyContext.retriesAttempted() is zero).

Specified by:

requestSucceeded in interface RetryCondition

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object