Package dev.failsafe

Class RetryPolicyBuilder<R>

    • Constructor Detail

      • RetryPolicyBuilder

        RetryPolicyBuilder()
    • Method Detail

      • abortIf

        public RetryPolicyBuilder<R> abortIf​(CheckedBiPredicate<R,​? extends java.lang.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:
        java.lang.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:
        java.lang.NullPointerException - if resultPredicate 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 the exception will be result in retries being aborted.
        Throws:
        java.lang.NullPointerException - if exception 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 the exceptions will be result in retries being aborted.
        Throws:
        java.lang.NullPointerException - if exceptions is null
        java.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 the exceptions will be result in retries being aborted.
        Throws:
        java.lang.NullPointerException - if exceptions is null
        java.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 the abortPredicate matches the exception. Any exception thrown from the abortPredicate is treated as a false result.
        Throws:
        java.lang.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:
        java.lang.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:
        java.lang.NullPointerException - if listener is null
      • 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:
        java.lang.NullPointerException - if listener is null
        See Also:
        onRetry(EventListener)
      • withBackoff

        public RetryPolicyBuilder<R> withBackoff​(java.time.Duration delay,
                                                 java.time.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:
        java.lang.NullPointerException - if delay or maxDelay are null
        java.lang.IllegalArgumentException - if delay is <= 0 or delay is >= maxDelay
        java.lang.IllegalStateException - if delay is >= the maxDuration or delay is < a configured jitter duration
      • withBackoff

        public RetryPolicyBuilder<R> withBackoff​(long delay,
                                                 long maxDelay,
                                                 java.time.temporal.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:
        java.lang.NullPointerException - if chronoUnit is null
        java.lang.IllegalArgumentException - if delay is <= 0 or delay is >= maxDelay
        java.lang.IllegalStateException - if delay is >= the maxDuration or delay is < a configured jitter duration
      • withBackoff

        public RetryPolicyBuilder<R> withBackoff​(long delay,
                                                 long maxDelay,
                                                 java.time.temporal.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:
        java.lang.NullPointerException - if chronoUnit is null
        java.lang.IllegalArgumentException - if delay <= 0, delay is >= maxDelay, or the delayFactor is <= 1
        java.lang.IllegalStateException - if delay is >= the maxDuration or delay is < a configured jitter duration
      • withBackoff

        public RetryPolicyBuilder<R> withBackoff​(java.time.Duration delay,
                                                 java.time.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:
        java.lang.NullPointerException - if delay or maxDelay are null
        java.lang.IllegalArgumentException - if delay <= 0, delay is >= maxDelay, or the delayFactor is <= 1
        java.lang.IllegalStateException - if delay is >= the maxDuration or delay is < a configured jitter duration
      • withDelay

        public RetryPolicyBuilder<R> withDelay​(long delayMin,
                                               long delayMax,
                                               java.time.temporal.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:
        java.lang.NullPointerException - if chronoUnit is null
        java.lang.IllegalArgumentException - if delayMin or delayMax are <= 0, or delayMin >= delayMax
        java.lang.IllegalStateException - if delayMax is >= the maxDuration or delayMin is < a configured jitter duration
      • withDelay

        public RetryPolicyBuilder<R> withDelay​(java.time.Duration delayMin,
                                               java.time.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:
        java.lang.NullPointerException - if delayMin or delayMax are null
        java.lang.IllegalArgumentException - if delayMin or delayMax are <= 0, or delayMin >= delayMax
        java.lang.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:
        java.lang.IllegalArgumentException - if jitterFactor is < 0 or > 1
      • withJitter

        public RetryPolicyBuilder<R> withJitter​(java.time.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:
        java.lang.NullPointerException - if jitter is null
        java.lang.IllegalArgumentException - if jitter is <= 0
        java.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 than withMaxRetries(int). For example, 2 retries equal 3 attempts.
        Throws:
        java.lang.IllegalArgumentException - if maxAttempts 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 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:
        java.lang.NullPointerException - if maxDuration is null
        java.lang.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:
        java.lang.IllegalArgumentException - if maxRetries < -1
        See Also:
        withMaxAttempts(int)