Class RetryPolicyBuilder<R>
- Type Parameters:
R
- result type
- All Implemented Interfaces:
PolicyListeners<RetryPolicyBuilder<R>,
R>
RetryPolicy
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:
-
Field Summary
FieldsFields inherited from class dev.failsafe.PolicyBuilder
config
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabortIf
(CheckedBiPredicate<R, ? extends Throwable> completionPredicate) Specifies that retries should be aborted if thecompletionPredicate
matches the completion result.abortIf
(CheckedPredicate<R> resultPredicate) Specifies that retries should be aborted if theresultPredicate
matches the result.abortOn
(CheckedPredicate<? extends Throwable> abortPredicate) Specifies that retries should be aborted if theabortPredicate
matches the exception.Specifies when retries should be aborted.final RetryPolicyBuilder
<R> Specifies when retries should be aborted.Specifies when retries should be aborted.Specifies that retries should be aborted if the execution result matches theresult
.build()
Builds a newRetryPolicy
using the builder's configuration.onAbort
(EventListener<ExecutionCompletedEvent<R>> listener) Registers thelistener
to be called when an execution is aborted.onFailedAttempt
(EventListener<ExecutionAttemptedEvent<R>> listener) Registers thelistener
to be called when an execution attempt fails.onRetriesExceeded
(EventListener<ExecutionCompletedEvent<R>> listener) Registers thelistener
to be called when an execution fails and themax retry attempts
ormax duration
are exceeded.onRetry
(EventListener<ExecutionAttemptedEvent<R>> listener) Registers thelistener
to be called when a retry is about to be attempted.onRetryScheduled
(EventListener<ExecutionScheduledEvent<R>> listener) Registers thelistener
to be called when a retry for an async call is about to be scheduled.withBackoff
(long delay, long maxDelay, ChronoUnit chronoUnit) Sets thedelay
between retries, exponentially backing off to themaxDelay
and multiplying consecutive delays by a factor of 2.withBackoff
(long delay, long maxDelay, ChronoUnit chronoUnit, double delayFactor) Sets thedelay
between retries, exponentially backing off to themaxDelay
and multiplying consecutive delays by thedelayFactor
.withBackoff
(Duration delay, Duration maxDelay) Sets thedelay
between retries, exponentially backing off to themaxDelay
and multiplying consecutive delays by a factor of 2.withBackoff
(Duration delay, Duration maxDelay, double delayFactor) Sets thedelay
between retries, exponentially backing off to themaxDelay
and multiplying consecutive delays by thedelayFactor
.withDelay
(long delayMin, long delayMax, ChronoUnit chronoUnit) Sets a random delay between thedelayMin
anddelayMax
(inclusive) to occur between retries.Sets the fixeddelay
to occur between retries.Sets a random delay between thedelayMin
anddelayMax
(inclusive) to occur between retries.withJitter
(double jitterFactor) Sets thejitterFactor
to randomly vary retry delays by.withJitter
(Duration jitter) Sets thejitter
to randomly vary retry delays by.withMaxAttempts
(int maxAttempts) Sets the max number of execution attempts to perform.withMaxDuration
(Duration maxDuration) Sets the max duration to perform retries for, else the execution will be failed.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 Details
-
DEFAULT_MAX_RETRIES
private static final int DEFAULT_MAX_RETRIES- See Also:
-
-
Constructor Details
-
RetryPolicyBuilder
RetryPolicyBuilder() -
RetryPolicyBuilder
RetryPolicyBuilder(RetryPolicyConfig<R> config)
-
-
Method Details
-
build
Builds a newRetryPolicy
using the builder's configuration. -
abortIf
Specifies that retries should be aborted if thecompletionPredicate
matches the completion result. Any exception thrown from thecompletionPredicate
is treated as afalse
result.- Throws:
NullPointerException
- ifcompletionPredicate
is null
-
abortIf
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:
NullPointerException
- ifresultPredicate
is null
-
abortOn
Specifies when retries should be aborted. Any exception that is assignable from theexception
will be result in retries being aborted.- Throws:
NullPointerException
- ifexception
is null
-
abortOn
Specifies when retries should be aborted. Any exception that is assignable from theexceptions
will be result in retries being aborted.- Throws:
NullPointerException
- ifexceptions
is nullIllegalArgumentException
- if exceptions is empty
-
abortOn
Specifies when retries should be aborted. Any exception that is assignable from theexceptions
will be result in retries being aborted.- Throws:
NullPointerException
- ifexceptions
is nullIllegalArgumentException
- if exceptions is null or empty
-
abortOn
Specifies that retries should be aborted if theabortPredicate
matches the exception. Any exception thrown from theabortPredicate
is treated as afalse
result.- Throws:
NullPointerException
- ifabortPredicate
is null
-
abortWhen
Specifies that retries should be aborted if the execution result matches theresult
. -
onAbort
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:
NullPointerException
- iflistener
is null
-
onFailedAttempt
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:
NullPointerException
- iflistener
is null
-
onRetriesExceeded
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:
NullPointerException
- iflistener
is null
-
onRetry
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:
NullPointerException
- iflistener
is null- See Also:
-
onRetryScheduled
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:
NullPointerException
- iflistener
is null- See Also:
-
withBackoff
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:
NullPointerException
- ifdelay
ormaxDelay
are nullIllegalArgumentException
- ifdelay
is invalid input: '<'= 0 ordelay
is >=maxDelay
IllegalStateException
- ifdelay
is >= themaxDuration
ordelay
is invalid input: '<' a configuredjitter duration
-
withBackoff
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:
NullPointerException
- ifchronoUnit
is nullIllegalArgumentException
- ifdelay
is invalid input: '<'= 0 ordelay
is >=maxDelay
IllegalStateException
- ifdelay
is >= themaxDuration
ordelay
is invalid input: '<' a configuredjitter duration
-
withBackoff
public RetryPolicyBuilder<R> withBackoff(long delay, long maxDelay, 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:
NullPointerException
- ifchronoUnit
is nullIllegalArgumentException
- ifdelay
invalid input: '<'= 0,delay
is >=maxDelay
, or thedelayFactor
is invalid input: '<'= 1IllegalStateException
- ifdelay
is >= themaxDuration
ordelay
is invalid input: '<' a configuredjitter duration
-
withBackoff
Sets thedelay
between retries, exponentially backing off to themaxDelay
and multiplying consecutive delays by thedelayFactor
. Replaces any previously configuredfixed
orrandom
delays.- Throws:
NullPointerException
- ifdelay
ormaxDelay
are nullIllegalArgumentException
- ifdelay
invalid input: '<'= 0,delay
is >=maxDelay
, or thedelayFactor
is invalid input: '<'= 1IllegalStateException
- ifdelay
is >= themaxDuration
ordelay
is invalid input: '<' a configuredjitter duration
-
withDelay
Sets the fixeddelay
to occur between retries. Replaces any previously configuredbackoff
orrandom
delays.- Overrides:
withDelay
in classDelayablePolicyBuilder<RetryPolicyBuilder<R>,
RetryPolicyConfig<R>, R> - Throws:
NullPointerException
- ifdelay
is nullIllegalArgumentException
- ifdelay
invalid input: '<'= 0IllegalStateException
- ifdelay
is >= themaxDuration
ordelay
is invalid input: '<' a configuredjitter duration
-
withDelay
Sets a random delay between thedelayMin
anddelayMax
(inclusive) to occur between retries. Replaces any previously configuredfixed
orbackoff
delays.- Throws:
NullPointerException
- ifchronoUnit
is nullIllegalArgumentException
- ifdelayMin
ordelayMax
are invalid input: '<'= 0, ordelayMin
>=delayMax
IllegalStateException
- ifdelayMax
is >= themaxDuration
ordelayMin
is invalid input: '<' a configuredjitter duration
-
withDelay
Sets a random delay between thedelayMin
anddelayMax
(inclusive) to occur between retries. Replaces any previously configuredfixed
orbackoff
delays.- Throws:
NullPointerException
- ifdelayMin
ordelayMax
are nullIllegalArgumentException
- ifdelayMin
ordelayMax
are invalid input: '<'= 0, ordelayMin
>=delayMax
IllegalStateException
- ifdelayMax
is >= themaxDuration
ordelay
is invalid input: '<' a configuredjitter duration
-
withJitter
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:
IllegalArgumentException
- ifjitterFactor
is invalid input: '<' 0 or > 1
-
withJitter
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:
NullPointerException
- ifjitter
is nullIllegalArgumentException
- ifjitter
is invalid input: '<'= 0IllegalStateException
- if the jitter is greater than the min configured delay
-
withMaxAttempts
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:
IllegalArgumentException
- ifmaxAttempts
is 0 or less than -1- See Also:
-
withMaxDuration
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:
NullPointerException
- ifmaxDuration
is nullIllegalStateException
- ifmaxDuration
is invalid input: '<'= thedelay
ormaxDuration
is invalid input: '<'= themax random delay
.
- This setting will not cause long running executions to be interrupted. For that capability, use a
-
withMaxRetries
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:
IllegalArgumentException
- ifmaxRetries
invalid input: '<' -1- See Also:
-