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>
BuildsRetryPolicy
instances.- By default, a RetryPolicy will retry up to
2
times when anyException
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 asFailurePolicyBuilder.handle(Class)
orFailurePolicyBuilder.handleIf(CheckedBiPredicate)
. Specifying a condition that only handles results, such asFailurePolicyBuilder.handleResult(Object)
orFailurePolicyBuilder.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
andabortIf
methods describe when retries should be aborted.
Note:
- This class extends
DelayablePolicyBuilder
andFailurePolicyBuilder
which offer additional configuration. - This class is not threadsafe.
- See Also:
RetryPolicyConfig
-
-
Field Summary
Fields Modifier and Type Field Description private static int
DEFAULT_MAX_RETRIES
-
Fields inherited from class dev.failsafe.PolicyBuilder
config
-
-
Constructor Summary
Constructors Constructor Description RetryPolicyBuilder()
RetryPolicyBuilder(RetryPolicyConfig<R> config)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description RetryPolicyBuilder<R>
abortIf(CheckedBiPredicate<R,? extends java.lang.Throwable> completionPredicate)
Specifies that retries should be aborted if thecompletionPredicate
matches the completion result.RetryPolicyBuilder<R>
abortIf(CheckedPredicate<R> resultPredicate)
Specifies that retries should be aborted if theresultPredicate
matches the result.RetryPolicyBuilder<R>
abortOn(CheckedPredicate<? extends java.lang.Throwable> abortPredicate)
Specifies that retries should be aborted if theabortPredicate
matches the exception.RetryPolicyBuilder<R>
abortOn(java.lang.Class<? extends java.lang.Throwable> exception)
Specifies when retries should be aborted.RetryPolicyBuilder<R>
abortOn(java.lang.Class<? extends java.lang.Throwable>... exceptions)
Specifies when retries should be aborted.RetryPolicyBuilder<R>
abortOn(java.util.List<java.lang.Class<? extends java.lang.Throwable>> exceptions)
Specifies when retries should be aborted.RetryPolicyBuilder<R>
abortWhen(R result)
Specifies that retries should be aborted if the execution result matches theresult
.RetryPolicy<R>
build()
Builds a newRetryPolicy
using the builder's configuration.RetryPolicyBuilder<R>
onAbort(EventListener<ExecutionCompletedEvent<R>> listener)
Registers thelistener
to be called when an execution is aborted.RetryPolicyBuilder<R>
onFailedAttempt(EventListener<ExecutionAttemptedEvent<R>> listener)
Registers thelistener
to be called when an execution attempt fails.RetryPolicyBuilder<R>
onRetriesExceeded(EventListener<ExecutionCompletedEvent<R>> listener)
Registers thelistener
to be called when an execution fails and themax retry attempts
ormax duration
are exceeded.RetryPolicyBuilder<R>
onRetry(EventListener<ExecutionAttemptedEvent<R>> listener)
Registers thelistener
to be called when a retry is about to be attempted.RetryPolicyBuilder<R>
onRetryScheduled(EventListener<ExecutionScheduledEvent<R>> listener)
Registers thelistener
to be called when a retry for an async call is about to be scheduled.RetryPolicyBuilder<R>
withBackoff(long delay, long maxDelay, java.time.temporal.ChronoUnit chronoUnit)
Sets thedelay
between retries, exponentially backing off to themaxDelay
and multiplying consecutive delays by a factor of 2.RetryPolicyBuilder<R>
withBackoff(long delay, long maxDelay, java.time.temporal.ChronoUnit chronoUnit, double delayFactor)
Sets thedelay
between retries, exponentially backing off to themaxDelay
and multiplying consecutive delays by thedelayFactor
.RetryPolicyBuilder<R>
withBackoff(java.time.Duration delay, java.time.Duration maxDelay)
Sets thedelay
between retries, exponentially backing off to themaxDelay
and multiplying consecutive delays by a factor of 2.RetryPolicyBuilder<R>
withBackoff(java.time.Duration delay, java.time.Duration maxDelay, double delayFactor)
Sets thedelay
between retries, exponentially backing off to themaxDelay
and multiplying consecutive delays by thedelayFactor
.RetryPolicyBuilder<R>
withDelay(long delayMin, long delayMax, java.time.temporal.ChronoUnit chronoUnit)
Sets a random delay between thedelayMin
anddelayMax
(inclusive) to occur between retries.RetryPolicyBuilder<R>
withDelay(java.time.Duration delay)
Sets the fixeddelay
to occur between retries.RetryPolicyBuilder<R>
withDelay(java.time.Duration delayMin, java.time.Duration delayMax)
Sets a random delay between thedelayMin
anddelayMax
(inclusive) to occur between retries.RetryPolicyBuilder<R>
withJitter(double jitterFactor)
Sets thejitterFactor
to randomly vary retry delays by.RetryPolicyBuilder<R>
withJitter(java.time.Duration jitter)
Sets thejitter
to randomly vary retry delays by.RetryPolicyBuilder<R>
withMaxAttempts(int maxAttempts)
Sets the max number of execution attempts to perform.RetryPolicyBuilder<R>
withMaxDuration(java.time.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
failurePredicateFor, failurePredicateFor, handle, handle, handle, handleIf, handleIf, handleResult, handleResultIf, resultPredicateFor, resultPredicateFor
-
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
-
-
-
-
Field Detail
-
DEFAULT_MAX_RETRIES
private static final int DEFAULT_MAX_RETRIES
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
RetryPolicyBuilder
RetryPolicyBuilder()
-
RetryPolicyBuilder
RetryPolicyBuilder(RetryPolicyConfig<R> config)
-
-
Method Detail
-
build
public RetryPolicy<R> build()
Builds a newRetryPolicy
using the builder's configuration.
-
abortIf
public RetryPolicyBuilder<R> abortIf(CheckedBiPredicate<R,? extends java.lang.Throwable> completionPredicate)
Specifies that retries should be aborted if thecompletionPredicate
matches the completion result. Any exception thrown from thecompletionPredicate
is treated as afalse
result.- Throws:
java.lang.NullPointerException
- ifcompletionPredicate
is null
-
abortIf
public RetryPolicyBuilder<R> abortIf(CheckedPredicate<R> resultPredicate)
Specifies that retries should be aborted if theresultPredicate
matches the result. Predicate is not invoked when the operation fails. Any exception thrown from theresultPredicate
is treated as afalse
result.- Throws:
java.lang.NullPointerException
- ifresultPredicate
is null
-
abortOn
public RetryPolicyBuilder<R> abortOn(java.lang.Class<? extends java.lang.Throwable> exception)
Specifies when retries should be aborted. Any exception that is assignable from theexception
will be result in retries being aborted.- Throws:
java.lang.NullPointerException
- ifexception
is null
-
abortOn
@SafeVarargs public final RetryPolicyBuilder<R> abortOn(java.lang.Class<? extends java.lang.Throwable>... exceptions)
Specifies when retries should be aborted. Any exception that is assignable from theexceptions
will be result in retries being aborted.- Throws:
java.lang.NullPointerException
- ifexceptions
is nulljava.lang.IllegalArgumentException
- if exceptions is empty
-
abortOn
public RetryPolicyBuilder<R> abortOn(java.util.List<java.lang.Class<? extends java.lang.Throwable>> exceptions)
Specifies when retries should be aborted. Any exception that is assignable from theexceptions
will be result in retries being aborted.- Throws:
java.lang.NullPointerException
- ifexceptions
is nulljava.lang.IllegalArgumentException
- if exceptions is null or empty
-
abortOn
public RetryPolicyBuilder<R> abortOn(CheckedPredicate<? extends java.lang.Throwable> abortPredicate)
Specifies that retries should be aborted if theabortPredicate
matches the exception. Any exception thrown from theabortPredicate
is treated as afalse
result.- Throws:
java.lang.NullPointerException
- ifabortPredicate
is null
-
abortWhen
public RetryPolicyBuilder<R> abortWhen(R result)
Specifies that retries should be aborted if the execution result matches theresult
.
-
onAbort
public RetryPolicyBuilder<R> onAbort(EventListener<ExecutionCompletedEvent<R>> listener)
Registers thelistener
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 aFallback
.- Throws:
java.lang.NullPointerException
- iflistener
is null
-
onFailedAttempt
public RetryPolicyBuilder<R> onFailedAttempt(EventListener<ExecutionAttemptedEvent<R>> listener)
Registers thelistener
to be called when an execution attempt fails. You can also useonFailure
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 aFallback
.- Throws:
java.lang.NullPointerException
- iflistener
is null
-
onRetriesExceeded
public RetryPolicyBuilder<R> onRetriesExceeded(EventListener<ExecutionCompletedEvent<R>> listener)
Registers thelistener
to be called when an execution fails and themax retry attempts
ormax 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 aFallback
.- Throws:
java.lang.NullPointerException
- iflistener
is null
-
onRetry
public RetryPolicyBuilder<R> onRetry(EventListener<ExecutionAttemptedEvent<R>> listener)
Registers thelistener
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 aFallback
.- Throws:
java.lang.NullPointerException
- iflistener
is null- See Also:
onRetryScheduled(EventListener)
-
onRetryScheduled
public RetryPolicyBuilder<R> onRetryScheduled(EventListener<ExecutionScheduledEvent<R>> listener)
Registers thelistener
to be called when a retry for an async call is about to be scheduled. This method differs fromonRetry(EventListener)
since it is called when a retry is initially scheduled but before any configured delay, whereasonRetry
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 aFallback
.- Throws:
java.lang.NullPointerException
- iflistener
is null- See Also:
onRetry(EventListener)
-
withBackoff
public RetryPolicyBuilder<R> withBackoff(java.time.Duration delay, java.time.Duration maxDelay)
Sets thedelay
between retries, exponentially backing off to themaxDelay
and multiplying consecutive delays by a factor of 2. Replaces any previously configuredfixed
orrandom
delays.- Throws:
java.lang.NullPointerException
- ifdelay
ormaxDelay
are nulljava.lang.IllegalArgumentException
- ifdelay
is <= 0 ordelay
is >=maxDelay
java.lang.IllegalStateException
- ifdelay
is >= themaxDuration
ordelay
is < a configuredjitter duration
-
withBackoff
public RetryPolicyBuilder<R> withBackoff(long delay, long maxDelay, java.time.temporal.ChronoUnit chronoUnit)
Sets thedelay
between retries, exponentially backing off to themaxDelay
and multiplying consecutive delays by a factor of 2. Replaces any previously configuredfixed
orrandom
delays.- Throws:
java.lang.NullPointerException
- ifchronoUnit
is nulljava.lang.IllegalArgumentException
- ifdelay
is <= 0 ordelay
is >=maxDelay
java.lang.IllegalStateException
- ifdelay
is >= themaxDuration
ordelay
is < a configuredjitter duration
-
withBackoff
public RetryPolicyBuilder<R> withBackoff(long delay, long maxDelay, java.time.temporal.ChronoUnit chronoUnit, double delayFactor)
Sets thedelay
between retries, exponentially backing off to themaxDelay
and multiplying consecutive delays by thedelayFactor
. Replaces any previously configuredfixed
orrandom
delays.- Throws:
java.lang.NullPointerException
- ifchronoUnit
is nulljava.lang.IllegalArgumentException
- ifdelay
<= 0,delay
is >=maxDelay
, or thedelayFactor
is <= 1java.lang.IllegalStateException
- ifdelay
is >= themaxDuration
ordelay
is < a configuredjitter duration
-
withBackoff
public RetryPolicyBuilder<R> withBackoff(java.time.Duration delay, java.time.Duration maxDelay, double delayFactor)
Sets thedelay
between retries, exponentially backing off to themaxDelay
and multiplying consecutive delays by thedelayFactor
. Replaces any previously configuredfixed
orrandom
delays.- Throws:
java.lang.NullPointerException
- ifdelay
ormaxDelay
are nulljava.lang.IllegalArgumentException
- ifdelay
<= 0,delay
is >=maxDelay
, or thedelayFactor
is <= 1java.lang.IllegalStateException
- ifdelay
is >= themaxDuration
ordelay
is < a configuredjitter duration
-
withDelay
public RetryPolicyBuilder<R> withDelay(java.time.Duration delay)
Sets the fixeddelay
to occur between retries. Replaces any previously configuredbackoff
orrandom
delays.- Overrides:
withDelay
in classDelayablePolicyBuilder<RetryPolicyBuilder<R>,RetryPolicyConfig<R>,R>
- Throws:
java.lang.NullPointerException
- ifdelay
is nulljava.lang.IllegalArgumentException
- ifdelay
<= 0java.lang.IllegalStateException
- ifdelay
is >= themaxDuration
ordelay
is < a configuredjitter duration
-
withDelay
public RetryPolicyBuilder<R> withDelay(long delayMin, long delayMax, java.time.temporal.ChronoUnit chronoUnit)
Sets a random delay between thedelayMin
anddelayMax
(inclusive) to occur between retries. Replaces any previously configuredfixed
orbackoff
delays.- Throws:
java.lang.NullPointerException
- ifchronoUnit
is nulljava.lang.IllegalArgumentException
- ifdelayMin
ordelayMax
are <= 0, ordelayMin
>=delayMax
java.lang.IllegalStateException
- ifdelayMax
is >= themaxDuration
ordelayMin
is < a configuredjitter duration
-
withDelay
public RetryPolicyBuilder<R> withDelay(java.time.Duration delayMin, java.time.Duration delayMax)
Sets a random delay between thedelayMin
anddelayMax
(inclusive) to occur between retries. Replaces any previously configuredfixed
orbackoff
delays.- Throws:
java.lang.NullPointerException
- ifdelayMin
ordelayMax
are nulljava.lang.IllegalArgumentException
- ifdelayMin
ordelayMax
are <= 0, ordelayMin
>=delayMax
java.lang.IllegalStateException
- ifdelayMax
is >= themaxDuration
ordelay
is < a configuredjitter duration
-
withJitter
public RetryPolicyBuilder<R> withJitter(double jitterFactor)
Sets thejitterFactor
to randomly vary retry delays by. For each retry delay, a random portion of the delay multiplied by thejitterFactor
will be added or subtracted to the delay. For example: a retry delay of100
milliseconds and ajitterFactor
of.25
will result in a random retry delay between75
and125
milliseconds. Replaces any previously configuredjitter duration
.Jitter should be combined with
fixed
,random
orexponential backoff
delays. If no delays are configured, this setting is ignored.- Throws:
java.lang.IllegalArgumentException
- ifjitterFactor
is < 0 or > 1
-
withJitter
public RetryPolicyBuilder<R> withJitter(java.time.Duration jitter)
Sets thejitter
to randomly vary retry delays by. For each retry delay, a random portion of thejitter
will be added or subtracted to the delay. For example: ajitter
of100
milliseconds will randomly add between-100
and100
milliseconds to each retry delay. Replaces any previously configuredjitter factor
.Jitter should be combined with
fixed
,random
orexponential backoff
delays. If no delays are configured, this setting is ignored.- Throws:
java.lang.NullPointerException
- ifjitter
is nulljava.lang.IllegalArgumentException
- ifjitter
is <= 0java.lang.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 thanwithMaxRetries(int)
. For example, 2 retries equal 3 attempts.- Throws:
java.lang.IllegalArgumentException
- ifmaxAttempts
is 0 or less than -1- See Also:
withMaxRetries(int)
-
withMaxDuration
public RetryPolicyBuilder<R> withMaxDuration(java.time.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
policywithInterrupt
set. - This setting will not disable
max retries
, which are still2
by default. A max retries limit can be disabled viawithMaxRetries(-1)
- Throws:
java.lang.NullPointerException
- ifmaxDuration
is nulljava.lang.IllegalStateException
- ifmaxDuration
is <= thedelay
ormaxDuration
is <= themax random delay
.
- This setting will not cause long running executions to be interrupted. For that capability, use a
-
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 thanwithMaxAttempts(int)
. For example, 2 retries equal 3 attempts.- Throws:
java.lang.IllegalArgumentException
- ifmaxRetries
< -1- See Also:
withMaxAttempts(int)
-
-