com.ibm.cos.v2.retries.api

Interface RetryStrategy

All Known Subinterfaces:

AdaptiveRetryStrategy, DefaultAwareRetryStrategy, LegacyRetryStrategy, StandardRetryStrategy

All Known Implementing Classes:

BaseRetryStrategy, DefaultAdaptiveRetryStrategy, DefaultLegacyRetryStrategy, DefaultStandardRetryStrategy, RetryPolicyAdapter

@ThreadSafe
public interface RetryStrategy

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 com.ibm.cos.v2: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 and 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 and Description
AcquireInitialTokenResponse	acquireInitialToken(AcquireInitialTokenRequest request) Invoked before the first request attempt.
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) Invoked before each subsequent (non-first) request attempt.
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 Detail

acquireInitialToken

AcquireInitialTokenResponse acquireInitialToken(AcquireInitialTokenRequest request)

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(com.ibm.cos.v2.retries.api.RefreshRetryTokenRequest) before doing so.

If the attempt was successful, callers MUST call recordSuccess(com.ibm.cos.v2.retries.api.RecordSuccessRequest).

Throws:

NullPointerException - if a required parameter is not specified

TokenAcquisitionFailedException - if a token cannot be acquired

refreshRetryToken

RefreshRetryTokenResponse refreshRetryToken(RefreshRetryTokenRequest request)

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(com.ibm.cos.v2.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(com.ibm.cos.v2.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

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.