Retry Policy

1. Attempts
2. Delays
   1. Jitter
3. Duration
4. Aborts
5. Failure Handling
6. Event Listeners

Retry policies express when retries should be performed for an execution.

Attempts

By default, a RetryPolicy will perform a maximum of 3 execution attempts. You can configure a max number of attempts:

retryPolicy.withMaxAttempts(3);

Or a max number of retries

retryPolicy.withMaxRetries(2);

Delays

By default, a RetryPolicy has no delay between attempts. You can configure a fixed delay:

retryPolicy.withDelay(Duration.ofSeconds(1));

Or a delay that backs off exponentially:

retryPolicy.withBackoff(1, 30, ChronoUnit.SECONDS);

A random delay for some range:

retryPolicy.withDelay(1, 10, ChronoUnit.SECONDS);

Or a computed delay based on an execution result or failure.

Jitter

You can also combine a random jitter factor with a delay:

retryPolicy.withJitter(.1);

Or a time based jitter:

retryPolicy.withJitter(Duration.ofMillis(100));

Duration

You can add a max duration for an execution, after which retries will stop:

retryPolicy.withMaxDuration(Duration.ofMinutes(5));

To cancel or interrupt running executions, see the Timeout policy.

Aborts

You can also specify which results, failures or conditions to abort retries on:

retryPolicy
  .abortWhen(true)
  .abortOn(NoRouteToHostException.class)
  .abortIf(result -> result == true)

Failure Handling

Like any FailurePolicy, a RetryPolicy can be configured to handle only certain results or failures, in combination with any of the configuration described above:

retryPolicy
  .handle(ConnectException.class)
  .handleResult(null);

Event Listeners

In addition to the standard policy listeners, a RetryPolicy can notify you when an execution attempt fails or before a retry is to be attempted:

retryPolicy
  .onFailedAttempt(e -> log.error("Connection attempt failed", e.getLastFailure()))
  .onRetry(e -> log.warn("Failure #{}. Retrying.", e.getAttemptCount()));

It can notify you when an execution fails and the max retries are exceeded:

retryPolicy.onRetriesExceeded(e -> log.warn("Failed to connect. Max retries exceeded."));

When an async retry is scheduled to be attempted after the configured delay:

retryPolicy.onRetryScheduled(e -> log.info("Connection retry scheduled {}.", e.getFailure()));

Or when retries have been aborted:

retryPolicy.onAbort(e -> log.warn("Connection aborted due to {}.", e.getFailure()));