dev.failsafe

Class RetryPolicyBuilder<R>

java.lang.Object

dev.failsafe.PolicyBuilder<S,C,R>

dev.failsafe.FailurePolicyBuilder<S,C,R>

dev.failsafe.DelayablePolicyBuilder<RetryPolicyBuilder<R>,RetryPolicyConfig<R>,R>

dev.failsafe.RetryPolicyBuilder<R>

Type Parameters:

R - result type

All Implemented Interfaces:

PolicyListeners<RetryPolicyBuilder<R>,R>

public class RetryPolicyBuilder<R>
extends DelayablePolicyBuilder<RetryPolicyBuilder<R>,RetryPolicyConfig<R>,R>
implements PolicyListeners<RetryPolicyBuilder<R>,R>

Builds RetryPolicy instances.

• By default, a RetryPolicy will retry up to 2 times when any Exception is thrown, with no delay between retry attempts.
• You can change the default number of retry attempts and delay between retries by using the with configuration methods.
• By default, any exception is considered a failure and will be handled by the policy. You can override this by specifying your own handle conditions. The default exception handling condition will only be overridden by another condition that handles exceptions such as FailurePolicyBuilder.handle(Class) or FailurePolicyBuilder.handleIf(CheckedBiPredicate). Specifying a condition that only handles results, such as FailurePolicyBuilder.handleResult(Object) or FailurePolicyBuilder.handleResultIf(CheckedPredicate) will not replace the default exception handling condition.
• If multiple handle conditions are specified, any condition that matches an execution result or exception will trigger policy handling.
• The abortOn, abortWhen and abortIf methods describe when retries should be aborted.

Note:

• This class extends DelayablePolicyBuilder and FailurePolicyBuilder which offer additional configuration.
• This class is not threadsafe.

See Also:

RetryPolicyConfig

Field Summary

Fields inherited from class dev.failsafe.PolicyBuilder

config

Method Summary

Modifier and Type	Method and Description
RetryPolicyBuilder<R>	abortIf(CheckedBiPredicate<R,? extends Throwable> completionPredicate) Specifies that retries should be aborted if the completionPredicate matches the completion result.
RetryPolicyBuilder<R>	abortIf(CheckedPredicate<R> resultPredicate) Specifies that retries should be aborted if the resultPredicate matches the result.
RetryPolicyBuilder<R>	abortOn(CheckedPredicate<? extends Throwable> abortPredicate) Specifies that retries should be aborted if the abortPredicate matches the exception.
RetryPolicyBuilder<R>	abortOn(Class<? extends Throwable>... exceptions) Specifies when retries should be aborted.
RetryPolicyBuilder<R>	abortOn(Class<? extends Throwable> exception) Specifies when retries should be aborted.
RetryPolicyBuilder<R>	abortOn(List<Class<? extends Throwable>> exceptions) Specifies when retries should be aborted.
RetryPolicyBuilder<R>	abortWhen(R result) Specifies that retries should be aborted if the execution result matches the result.
RetryPolicy<R>	build() Builds a new RetryPolicy using the builder's configuration.
RetryPolicyBuilder<R>	onAbort(EventListener<ExecutionCompletedEvent<R>> listener) Registers the listener to be called when an execution is aborted.
RetryPolicyBuilder<R>	onFailedAttempt(EventListener<ExecutionAttemptedEvent<R>> listener) Registers the listener to be called when an execution attempt fails.
RetryPolicyBuilder<R>	onRetriesExceeded(EventListener<ExecutionCompletedEvent<R>> listener) Registers the listener to be called when an execution fails and the max retry attempts or max duration are exceeded.
RetryPolicyBuilder<R>	onRetry(EventListener<ExecutionAttemptedEvent<R>> listener) Registers the listener to be called when a retry is about to be attempted.
RetryPolicyBuilder<R>	onRetryScheduled(EventListener<ExecutionScheduledEvent<R>> listener) Registers the listener to be called when a retry for an async call is about to be scheduled.
RetryPolicyBuilder<R>	withBackoff(Duration delay, Duration maxDelay) Sets the delay between retries, exponentially backing off to the maxDelay and multiplying consecutive delays by a factor of 2.
RetryPolicyBuilder<R>	withBackoff(Duration delay, Duration maxDelay, double delayFactor) Sets the delay between retries, exponentially backing off to the maxDelay and multiplying consecutive delays by the delayFactor.
RetryPolicyBuilder<R>	withBackoff(long delay, long maxDelay, ChronoUnit chronoUnit) Sets the delay between retries, exponentially backing off to the maxDelay and multiplying consecutive delays by a factor of 2.
RetryPolicyBuilder<R>	withBackoff(long delay, long maxDelay, ChronoUnit chronoUnit, double delayFactor) Sets the delay between retries, exponentially backing off to the maxDelay and multiplying consecutive delays by the delayFactor.
RetryPolicyBuilder<R>	withDelay(Duration delay) Sets the fixed delay to occur between retries.
RetryPolicyBuilder<R>	withDelay(Duration delayMin, Duration delayMax) Sets a random delay between the delayMin and delayMax (inclusive) to occur between retries.
RetryPolicyBuilder<R>	withDelay(long delayMin, long delayMax, ChronoUnit chronoUnit) Sets a random delay between the delayMin and delayMax (inclusive) to occur between retries.
RetryPolicyBuilder<R>	withJitter(double jitterFactor) Sets the jitterFactor to randomly vary retry delays by.
RetryPolicyBuilder<R>	withJitter(Duration jitter) Sets the jitter to randomly vary retry delays by.
RetryPolicyBuilder<R>	withMaxAttempts(int maxAttempts) Sets the max number of execution attempts to perform.
RetryPolicyBuilder<R>	withMaxDuration(Duration maxDuration) Sets the max duration to perform retries for, else the execution will be failed.
RetryPolicyBuilder<R>	withMaxRetries(int maxRetries) Sets the max number of retries to perform when an execution attempt fails.

Methods inherited from class dev.failsafe.DelayablePolicyBuilder

withDelayFn, withDelayFnOn, withDelayFnWhen

Methods inherited from class dev.failsafe.FailurePolicyBuilder

handle, handle, handle, handleIf, handleIf, handleResult, handleResultIf

Methods inherited from class dev.failsafe.PolicyBuilder

onFailure, onSuccess

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface dev.failsafe.PolicyListeners

onFailure, onSuccess

Method Detail

build

public RetryPolicy<R> build()

Builds a new RetryPolicy using the builder's configuration.

abortIf

public RetryPolicyBuilder<R> abortIf(CheckedBiPredicate<R,? extends Throwable> completionPredicate)

Specifies that retries should be aborted if the completionPredicate matches the completion result. Any exception thrown from the completionPredicate is treated as a false result.

Throws:

NullPointerException - if completionPredicate is null

abortIf

public RetryPolicyBuilder<R> abortIf(CheckedPredicate<R> resultPredicate)

Specifies that retries should be aborted if the resultPredicate matches the result. Predicate is not invoked when the operation fails. Any exception thrown from the resultPredicate is treated as a false result.

Throws:

NullPointerException - if resultPredicate is null

abortOn

public RetryPolicyBuilder<R> abortOn(Class<? extends Throwable> exception)

Specifies when retries should be aborted. Any exception that is assignable from the exception will be result in retries being aborted.

Throws:

NullPointerException - if exception is null

abortOn

@SafeVarargs
public final RetryPolicyBuilder<R> abortOn(Class<? extends Throwable>... exceptions)

Specifies when retries should be aborted. Any exception that is assignable from the exceptions will be result in retries being aborted.

Throws:

NullPointerException - if exceptions is null

IllegalArgumentException - if exceptions is empty

abortOn

public RetryPolicyBuilder<R> abortOn(List<Class<? extends Throwable>> exceptions)

Specifies when retries should be aborted. Any exception that is assignable from the exceptions will be result in retries being aborted.

Throws:

NullPointerException - if exceptions is null

IllegalArgumentException - if exceptions is null or empty

abortOn

public RetryPolicyBuilder<R> abortOn(CheckedPredicate<? extends Throwable> abortPredicate)

Specifies that retries should be aborted if the abortPredicate matches the exception. Any exception thrown from the abortPredicate is treated as a false result.

Throws:

NullPointerException - if abortPredicate is null

abortWhen

public RetryPolicyBuilder<R> abortWhen(R result)

Specifies that retries should be aborted if the execution result matches the result.

onAbort

public RetryPolicyBuilder<R> onAbort(EventListener<ExecutionCompletedEvent<R>> listener)

Registers the listener to be called when an execution is aborted.

Note: Any exceptions that are thrown from within the listener are ignored. To provide an alternative result for a failed execution, use a Fallback.

Throws:

NullPointerException - if listener is null

onFailedAttempt

public RetryPolicyBuilder<R> onFailedAttempt(EventListener<ExecutionAttemptedEvent<R>> listener)

Registers the listener to be called when an execution attempt fails. You can also use onFailure to determine when the execution attempt fails and and all retries have failed.

Note: Any exceptions that are thrown from within the listener are ignored. To provide an alternative result for a failed execution, use a Fallback.

Throws:

NullPointerException - if listener is null

onRetriesExceeded

public RetryPolicyBuilder<R> onRetriesExceeded(EventListener<ExecutionCompletedEvent<R>> listener)

Registers the listener to be called when an execution fails and the max retry attempts or max duration are exceeded.

Note: Any exceptions that are thrown from within the listener are ignored. To provide an alternative result for a failed execution, use a Fallback.

Throws:

NullPointerException - if listener is null

onRetry

public RetryPolicyBuilder<R> onRetry(EventListener<ExecutionAttemptedEvent<R>> listener)

Registers the listener to be called when a retry is about to be attempted.

Note: Any exceptions that are thrown from within the listener are ignored. To provide an alternative result for a failed execution, use a Fallback.

Throws:

NullPointerException - if listener is null

See Also:

onRetryScheduled(EventListener)

onRetryScheduled

public RetryPolicyBuilder<R> onRetryScheduled(EventListener<ExecutionScheduledEvent<R>> listener)

Registers the listener to be called when a retry for an async call is about to be scheduled. This method differs from onRetry(EventListener) since it is called when a retry is initially scheduled but before any configured delay, whereas onRetry is called after a delay, just before the retry attempt takes place.

Note: Any exceptions that are thrown from within the listener are ignored. To provide an alternative result for a failed execution, use a Fallback.

Throws:

NullPointerException - if listener is null

See Also:

onRetry(EventListener)

withBackoff

public RetryPolicyBuilder<R> withBackoff(Duration delay,
                                         Duration maxDelay)

Sets the delay between retries, exponentially backing off to the maxDelay and multiplying consecutive delays by a factor of 2. Replaces any previously configured fixed or random delays.

Throws:

NullPointerException - if delay or maxDelay are null

IllegalArgumentException - if delay is <= 0 or delay is >= maxDelay

IllegalStateException - if delay is >= the maxDuration or delay is < a configured jitter duration

withBackoff

public RetryPolicyBuilder<R> withBackoff(long delay,
                                         long maxDelay,
                                         ChronoUnit chronoUnit)

Sets the delay between retries, exponentially backing off to the maxDelay and multiplying consecutive delays by a factor of 2. Replaces any previously configured fixed or random delays.

Throws:

NullPointerException - if chronoUnit is null

IllegalArgumentException - if delay is <= 0 or delay is >= maxDelay

IllegalStateException - if delay is >= the maxDuration or delay is < a configured jitter duration

withBackoff

public RetryPolicyBuilder<R> withBackoff(long delay,
                                         long maxDelay,
                                         ChronoUnit chronoUnit,
                                         double delayFactor)

Sets the delay between retries, exponentially backing off to the maxDelay and multiplying consecutive delays by the delayFactor. Replaces any previously configured fixed or random delays.

Throws:

NullPointerException - if chronoUnit is null

IllegalArgumentException - if delay <= 0, delay is >= maxDelay, or the delayFactor is <= 1

IllegalStateException - if delay is >= the maxDuration or delay is < a configured jitter duration

withBackoff

public RetryPolicyBuilder<R> withBackoff(Duration delay,
                                         Duration maxDelay,
                                         double delayFactor)

Sets the delay between retries, exponentially backing off to the maxDelay and multiplying consecutive delays by the delayFactor. Replaces any previously configured fixed or random delays.

Throws:

NullPointerException - if delay or maxDelay are null

IllegalArgumentException - if delay <= 0, delay is >= maxDelay, or the delayFactor is <= 1

IllegalStateException - if delay is >= the maxDuration or delay is < a configured jitter duration

withDelay

public RetryPolicyBuilder<R> withDelay(Duration delay)

Sets the fixed delay to occur between retries. Replaces any previously configured backoff or random delays.

Overrides:

withDelay in class DelayablePolicyBuilder<RetryPolicyBuilder<R>,RetryPolicyConfig<R>,R>

Throws:

NullPointerException - if delay is null

IllegalArgumentException - if delay <= 0

IllegalStateException - if delay is >= the maxDuration or delay is < a configured jitter duration

withDelay

public RetryPolicyBuilder<R> withDelay(long delayMin,
                                       long delayMax,
                                       ChronoUnit chronoUnit)

Sets a random delay between the delayMin and delayMax (inclusive) to occur between retries. Replaces any previously configured fixed or backoff delays.

Throws:

NullPointerException - if chronoUnit is null

IllegalArgumentException - if delayMin or delayMax are <= 0, or delayMin >= delayMax

IllegalStateException - if delayMax is >= the maxDuration or delayMin is < a configured jitter duration

withDelay

public RetryPolicyBuilder<R> withDelay(Duration delayMin,
                                       Duration delayMax)

Sets a random delay between the delayMin and delayMax (inclusive) to occur between retries. Replaces any previously configured fixed or backoff delays.

Throws:

NullPointerException - if delayMin or delayMax are null

IllegalArgumentException - if delayMin or delayMax are <= 0, or delayMin >= delayMax

IllegalStateException - if delayMax is >= the maxDuration or delay is < a configured jitter duration

withJitter

public RetryPolicyBuilder<R> withJitter(double jitterFactor)

Sets the jitterFactor to randomly vary retry delays by. For each retry delay, a random portion of the delay multiplied by the jitterFactor will be added or subtracted to the delay. For example: a retry delay of 100 milliseconds and a jitterFactor of .25 will result in a random retry delay between 75 and 125 milliseconds. Replaces any previously configured jitter duration.

Jitter should be combined with fixed, random or exponential backoff delays. If no delays are configured, this setting is ignored.

Throws:

IllegalArgumentException - if jitterFactor is < 0 or > 1

withJitter

public RetryPolicyBuilder<R> withJitter(Duration jitter)

Sets the jitter to randomly vary retry delays by. For each retry delay, a random portion of the jitter will be added or subtracted to the delay. For example: a jitter of 100 milliseconds will randomly add between -100 and 100 milliseconds to each retry delay. Replaces any previously configured jitter factor.

Jitter should be combined with fixed, random or exponential backoff delays. If no delays are configured, this setting is ignored.

Throws:

NullPointerException - if jitter is null

IllegalArgumentException - if jitter is <= 0

IllegalStateException - if the jitter is greater than the min configured delay

withMaxAttempts

public RetryPolicyBuilder<R> withMaxAttempts(int maxAttempts)

Sets the max number of execution attempts to perform. -1 indicates no limit. This method has the same effect as setting 1 more than withMaxRetries(int). For example, 2 retries equal 3 attempts.

Throws:

IllegalArgumentException - if maxAttempts is 0 or less than -1

See Also:

withMaxRetries(int)

withMaxDuration

public RetryPolicyBuilder<R> withMaxDuration(Duration maxDuration)

Sets the max duration to perform retries for, else the execution will be failed.

Notes:

• This setting will not cause long running executions to be interrupted. For that capability, use a Timeout policy withInterrupt set.
• This setting will not disable max retries, which are still 2 by default. A max retries limit can be disabled via withMaxRetries(-1)

Throws:

NullPointerException - if maxDuration is null

IllegalStateException - if maxDuration is <= the delay or maxDuration is <= the max random delay.

withMaxRetries

public RetryPolicyBuilder<R> withMaxRetries(int maxRetries)

Sets the max number of retries to perform when an execution attempt fails. -1 indicates no limit. This method has the same effect as setting 1 less than withMaxAttempts(int). For example, 2 retries equal 3 attempts.

Throws:

IllegalArgumentException - if maxRetries < -1

See Also:

withMaxAttempts(int)