Package com.linecorp.armeria.client.retry

Interface Backoff

All Superinterfaces:
Unwrappable
All Known Implementing Classes:
AbstractBackoff, BackoffWrapper
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface
public interface Backoff
extends Unwrappable
Controls back off between attempts in a single retry operation.

  • Method Details

    • ofDefault

      static Backoff ofDefault()
      Returns the default Backoff.

    • withoutDelay

      static Backoff withoutDelay()
      Returns a Backoff that will never wait between attempts. In most cases, using back off without delay is very dangerous. Please consider using exponential(long, long) with withJitter(double) or fixed(long) with pre calculated delay depending on the situation.

    • fixed

      static Backoff fixed​(long delayMillis)
      Returns a Backoff that waits a fixed delay between attempts.

    • exponential

      static Backoff exponential​(long initialDelayMillis, long maxDelayMillis)
      Returns a Backoff that waits an exponentially-increasing amount of time between attempts.

    • exponential

      static Backoff exponential​(long initialDelayMillis, long maxDelayMillis, double multiplier)
      Returns a Backoff that waits an exponentially-increasing amount of time between attempts.

    • fibonacci

      static Backoff fibonacci​(long initialDelayMillis, long maxDelayMillis)
      Returns a Backoff for which the backoff delay increases in line with the Fibonacci sequence f(n) = f(n-1) + f(n-2) where f(0) = f(1) = initialDelayMillis.

    • random

      static Backoff random​(long minDelayMillis, long maxDelayMillis)
      Returns a Backoff that computes backoff delay which is a random value between minDelayMillis and maxDelayMillis chosen by ThreadLocalRandom.

    • random

      static Backoff random​(long minDelayMillis, long maxDelayMillis, Supplier<Random> randomSupplier)
      Returns a Backoff that computes backoff delay which is a random value between minDelayMillis and maxDelayMillis.

    • of

      static Backoff of​(String specification)
      Creates a new Backoff that computes backoff delay using one of exponential(long, long, double), fibonacci(long, long), fixed(long) and random(long, long) chaining with withJitter(double, double) and withMaxAttempts(int) from the specification string that conforms to the following format: The order of options does not matter, and the specification needs at least one option. If you don't specify the base option exponential backoff will be used. If you only specify a base option, jitter and maxAttempts will be set by default values. For example:
      • exponential=200:10000:2.0,jitter=0.2 (default)
      • exponential=200:10000,jitter=0.2,maxAttempts=50 (multiplier omitted)
      • fibonacci=200:10000,jitter=0.2,maxAttempts=50
      • fixed=100,jitter=-0.5:0.2,maxAttempts=10 (fixed backoff with jitter variation)
      • random=200:1000 (jitter and maxAttempts will be set by default values)
      Parameters:
      specification - the specification used to create a Backoff

    • nextDelayMillis

      long nextDelayMillis​(int numAttemptsSoFar)
      Returns the number of milliseconds to wait for before attempting a retry.
      Parameters:
      numAttemptsSoFar - the number of attempts made by a client so far, including the first attempt and its following retries.
      Returns:
      the number of milliseconds to wait for before attempting a retry, or a negative value if no further retry has to be made.
      Throws:
      IllegalArgumentException - if numAttemptsSoFar is equal to or less than 0

    • as

      default <T> T as​(Class<T> type)
      Undecorates this Backoff to find the Backoff which is an instance of the specified type.
      Specified by:
      as in interface Unwrappable
      Parameters:
      type - the type of the desired Backoff
      Returns:
      the Backoff which is an instance of type if this Backoff decorated such a Backoff, or null otherwise.
      See Also:
      Unwrappable

    • unwrap

      default Backoff unwrap()
      Undecorates this Backoff and returns the object being decorated. If this Backoff is the innermost object, this method returns itself.
      Specified by:
      unwrap in interface Unwrappable
      See Also:
      Unwrappable

    • withJitter

      default Backoff withJitter​(double jitterRate)
      Returns a Backoff that adds a random jitter value to the original delay using full jitter strategy. The jitterRate is used to calculate the lower and upper bound of the ultimate delay. The lower bound will be ((1 - jitterRate) * originalDelay) and the upper bound will be ((1 + jitterRate) * originalDelay). For example, if the delay returned by exponential(long, long) is 1000 milliseconds and the provided jitter value is 0.3, the ultimate backoff delay will be chosen between 1000 * (1 - 0.3) and 1000 * (1 + 0.3) by ThreadLocalRandom. The rate value should be between 0.0 and 1.0.
      Parameters:
      jitterRate - the rate that used to calculate the lower and upper bound of the backoff delay
      Throws:
      IllegalArgumentException - if jitterRate is a negative value or greater than 1.0

    • withJitter

      default Backoff withJitter​(double minJitterRate, double maxJitterRate)
      Returns a Backoff that adds a random jitter value to the original delay using full jitter strategy. The minJitterRate and maxJitterRate is used to calculate the lower and upper bound of the ultimate delay. The lower bound will be ((1 - minJitterRate) * originalDelay) and the upper bound will be ((1 + maxJitterRate) * originalDelay). For example, if the delay returned by exponential(long, long) is 1000 milliseconds and the minJitterRate is -0.2, maxJitterRate is 0.3, the ultimate backoff delay will be chosen between 1000 * (1 - 0.2) and 1000 * (1 + 0.3) by ThreadLocalRandom. The rate values should be between -1.0 and 1.0.
      Parameters:
      minJitterRate - the rate that used to calculate the lower bound of the backoff delay
      maxJitterRate - the rate that used to calculate the upper bound of the backoff delay
      Throws:
      IllegalArgumentException - if minJitterRate is greater than maxJitterRate or if the minJitterRate and maxJitterRate values are not in between -1.0 and 1.0

    • withJitter

      default Backoff withJitter​(double minJitterRate, double maxJitterRate, Supplier<Random> randomSupplier)
      Returns a Backoff that adds a random jitter value to the original delay using full jitter strategy. The minJitterRate and maxJitterRate is used to calculate the lower and upper bound of the ultimate delay. The lower bound will be ((1 - minJitterRate) * originalDelay) and the upper bound will be ((1 + maxJitterRate) * originalDelay). For example, if the delay returned by exponential(long, long) is 1000 milliseconds and the minJitterRate is -0.2, maxJitterRate is 0.3, the ultimate backoff delay will be chosen between 1000 * (1 - 0.2) and 1000 * (1 + 0.3). The rate values should be between -1.0 and 1.0.
      Parameters:
      minJitterRate - the rate that used to calculate the lower bound of the backoff delay
      maxJitterRate - the rate that used to calculate the upper bound of the backoff delay
      randomSupplier - the supplier that provides Random in order to calculate the ultimate delay
      Throws:
      IllegalArgumentException - if minJitterRate is greater than maxJitterRate or if the minJitterRate and maxJitterRate values are not in between -1.0 and 1.0

    • withMaxAttempts

      default Backoff withMaxAttempts​(int maxAttempts)
      Returns a Backoff which limits the number of attempts up to the specified value.