Package com.linecorp.armeria.client.retry

Interface RetryRule

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface RetryRule

Determines whether a failed request should be retried. If you need to determine by looking into the Response, use RetryRuleWithContent.

Method Summary

Modifier and Type	Method	Description
static RetryRuleBuilder	builder()	Returns a newly created RetryRuleBuilder.
static RetryRuleBuilder	builder(HttpMethod... methods)	Returns a newly created RetryRuleBuilder with the specified HttpMethods.
static RetryRuleBuilder	builder(Iterable<HttpMethod> methods)	Returns a newly created RetryRuleBuilder with the specified HttpMethods.
static RetryRuleBuilder	builder(BiPredicate<? super ClientRequestContext,? super RequestHeaders> requestHeadersFilter)	Returns a newly created RetryRuleBuilder with the specified requestHeadersFilter.
static RetryRule	failsafe()	Returns a newly created RetryRule that will retry with the default backoff if the request HTTP method is idempotent and an Exception is raised or the class of the response status is HttpStatusClass.SERVER_ERROR.
static RetryRule	of(RetryRule... retryRules)	Returns a RetryRule that combines the specified retryRules.
static RetryRule	of(Iterable<? extends RetryRule> retryRules)	Returns a RetryRule that combines all the RetryRule of the retryRules.
static RetryRule	onException()	Returns a newly created RetryRule that retries with default backoff on any Exception.
static RetryRule	onException(Class<? extends Throwable> exception)	Returns a newly created a RetryRule that will retry with the default backoff if an Exception is raised and that is an instance of the specified exception.
static RetryRule	onException(BiPredicate<? super ClientRequestContext,? super Throwable> exceptionFilter)	Returns a newly created RetryRule that will retry with the default backoff if an Exception is raised and the specified exceptionFilter returns true.
static RetryRule	onServerErrorStatus()	Returns a newly created RetryRule that will retry with the default backoff if the class of the response status is HttpStatusClass.SERVER_ERROR.
static RetryRule	onStatus(HttpStatus... statuses)	Returns a newly created RetryRule that will retry with the default backoff if the response status is one of the specified HttpStatuses.
static RetryRule	onStatus(Iterable<HttpStatus> statuses)	Returns a newly created RetryRule that will retry with the default backoff if the response status is one of the specified HttpStatuses.
static RetryRule	onStatus(BiPredicate<? super ClientRequestContext,? super HttpStatus> statusFilter)	Returns a newly created a RetryRule that will retry with the default backoff if the response status matches the specified statusFilter.
static RetryRule	onStatusClass(HttpStatusClass statusClass)	Returns a newly created RetryRule that will retry with the default backoff if the class of the response status is the specified HttpStatusClass.
static RetryRule	onStatusClass(Iterable<HttpStatusClass> statusClasses)	Returns a newly created RetryRule that will retry with the default backoff if the class of the response status is one of the specified HttpStatusClasses.
static RetryRule	onUnprocessed()	Returns a RetryRule that retries with the default backoff on an UnprocessedRequestException which means that the request has not been processed by the server.
default RetryRule	orElse(RetryRule other)	Returns a composed RetryRule that represents a logical OR of this RetryRule and another.
default boolean	requiresResponseTrailers()	Returns whether this rule requires the response trailers to determine if a Response is successful or not.
CompletionStage<RetryDecision>	shouldRetry(ClientRequestContext ctx, @Nullable Throwable cause)	Tells whether the request sent with the specified ClientRequestContext requires a retry or not.

Method Details

failsafe

static RetryRule failsafe()

Returns a newly created RetryRule that will retry with the default backoff if the request HTTP method is idempotent and an Exception is raised or the class of the response status is HttpStatusClass.SERVER_ERROR. Otherwise, an UnprocessedRequestException is raised regardless of the request HTTP method.

Note that a client can safely retry a failed request with this rule if an endpoint service produces the same result (no side effects) on idempotent HTTP methods or UnprocessedRequestException.

This method is a shortcut for:

 RetryRule.of(RetryRule.builder(HttpMethods.idempotentMethods())
                       .onServerErrorStatus()
                       .onUnprocessed()
                       .thenBackoff(),
              RetryRule.onUnprocessed());
 

onStatusClass

static RetryRule onStatusClass(HttpStatusClass statusClass)

Returns a newly created RetryRule that will retry with the default backoff if the class of the response status is the specified HttpStatusClass.

onStatusClass

static RetryRule onStatusClass(Iterable<HttpStatusClass> statusClasses)

Returns a newly created RetryRule that will retry with the default backoff if the class of the response status is one of the specified HttpStatusClasses.

onServerErrorStatus

static RetryRule onServerErrorStatus()

Returns a newly created RetryRule that will retry with the default backoff if the class of the response status is HttpStatusClass.SERVER_ERROR.

onStatus

static RetryRule onStatus(HttpStatus... statuses)

Returns a newly created RetryRule that will retry with the default backoff if the response status is one of the specified HttpStatuses.

onStatus

static RetryRule onStatus(Iterable<HttpStatus> statuses)

Returns a newly created RetryRule that will retry with the default backoff if the response status is one of the specified HttpStatuses.

onStatus

static RetryRule onStatus(BiPredicate<? super ClientRequestContext,? super HttpStatus> statusFilter)

Returns a newly created a RetryRule that will retry with the default backoff if the response status matches the specified statusFilter.

onException

static RetryRule onException(Class<? extends Throwable> exception)

Returns a newly created a RetryRule that will retry with the default backoff if an Exception is raised and that is an instance of the specified exception.

onException

static RetryRule onException(BiPredicate<? super ClientRequestContext,? super Throwable> exceptionFilter)

Returns a newly created RetryRule that will retry with the default backoff if an Exception is raised and the specified exceptionFilter returns true.

onException

static RetryRule onException()

Returns a newly created RetryRule that retries with default backoff on any Exception. Note that this rule should be used carefully because it reties regardless of idempotency.

onUnprocessed

static RetryRule onUnprocessed()

Returns a RetryRule that retries with the default backoff on an UnprocessedRequestException which means that the request has not been processed by the server. Therefore, you can safely retry the request without worrying about the idempotency of the request.

builder

static RetryRuleBuilder builder()

Returns a newly created RetryRuleBuilder.

builder

static RetryRuleBuilder builder(HttpMethod... methods)

Returns a newly created RetryRuleBuilder with the specified HttpMethods.

builder

static RetryRuleBuilder builder(Iterable<HttpMethod> methods)

Returns a newly created RetryRuleBuilder with the specified HttpMethods.

builder

static RetryRuleBuilder builder(BiPredicate<? super ClientRequestContext,? super RequestHeaders> requestHeadersFilter)

Returns a newly created RetryRuleBuilder with the specified requestHeadersFilter.

of

static RetryRule of(RetryRule... retryRules)

Returns a RetryRule that combines the specified retryRules.

of

static RetryRule of(Iterable<? extends RetryRule> retryRules)

Returns a RetryRule that combines all the RetryRule of the retryRules.

orElse

default RetryRule orElse(RetryRule other)

Returns a composed RetryRule that represents a logical OR of this RetryRule and another. If this RetryRule completes with RetryDecision.next(), then other RetryRule is evaluated.

shouldRetry

CompletionStage<RetryDecision> shouldRetry(ClientRequestContext ctx,
 @Nullable
 @Nullable Throwable cause)

Tells whether the request sent with the specified ClientRequestContext requires a retry or not. Implement this method to return a CompletionStage and to complete it with a desired RetryDecision.retry(Backoff). To not retry, complete it with RetryDecision.noRetry(). To skip this RetryRule and find other RetryRule, complete it with RetryDecision.next(). If the return value of the last RetryRule completes with RetryDecision.next(), the request never retries.

To retrieve the ResponseHeaders, you can use the specified ClientRequestContext:

 CompletionStage<RetryDecision> shouldRetry(ClientRequestContext ctx, @Nullable Throwable cause) {
     if (cause != null) {
         return CompletableFuture.completedFuture(RetryDecision.retry(backoff));
     }

     ResponseHeaders responseHeaders = ctx.log().ensureAvailable(RequestLogProperty.RESPONSE_HEADERS)
                                          .responseHeaders();
     if (responseHeaders.status().codeClass() == HttpStatusClass.SERVER_ERROR) {
         return CompletableFuture.completedFuture(RetryDecision.retry(backoff));
     }
     if (responseHeaders.status() == HttpStatus.TOO_MANY_REQUESTS) {
         return CompletableFuture.completedFuture(RetryDecision.noRetry());
     }

     return CompletableFuture.completedFuture(RetryDecision.next());
 }
 

Parameters:

ctx - the ClientRequestContext of this request

cause - the Throwable which is raised while sending a request. null if there's no exception.

requiresResponseTrailers

default boolean requiresResponseTrailers()

Returns whether this rule requires the response trailers to determine if a Response is successful or not.