Backoff (filter-service-metrics 1.13 1.13 API)

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 Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`default <T> T`	`as(Class<T> type)` Undecorates this `Backoff` to find the `Backoff` which is an instance of the specified `type`.
`static Backoff`	`exponential(long initialDelayMillis, long maxDelayMillis)` Returns a `Backoff` that waits an exponentially-increasing amount of time between attempts.
`static Backoff`	`exponential(long initialDelayMillis, long maxDelayMillis, double multiplier)` Returns a `Backoff` that waits an exponentially-increasing amount of time between attempts.
`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`.
`static Backoff`	`fixed(long delayMillis)` Returns a `Backoff` that waits a fixed delay between attempts.
`long`	`nextDelayMillis(int numAttemptsSoFar)` Returns the number of milliseconds to wait for before attempting a retry.
`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: `exponential=[initialDelayMillis:maxDelayMillis:multiplier]` is for `exponential(long, long, double)` (multiplier will be 2.0 if it's omitted) `fibonacci=[initialDelayMillis:maxDelayMillis]` is for `fibonacci(long, long)` `fixed=[delayMillis]` is for `fixed(long)` `random=[minDelayMillis:maxDelayMillis]` is for `random(long, long)` `jitter=[minJitterRate:maxJitterRate]` is for `withJitter(double, double)` (if only one jitter value is specified, it will be used for `withJitter(double)` `maxAttempts=[maxAttempts]` is for `withMaxAttempts(int)` The order of options does not matter, and the `specification` needs at least one option.
`static Backoff`	`ofDefault()` Returns the default `Backoff`.
`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`.
`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`.
`default Backoff`	`withJitter(double jitterRate)` Returns a `Backoff` that adds a random jitter value to the original delay using full jitter strategy.
`default Backoff`	`withJitter(double minJitterRate, double maxJitterRate)` Returns a `Backoff` that adds a random jitter value to the original delay using full jitter strategy.
`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.
`default Backoff`	`withMaxAttempts(int maxAttempts)` Returns a `Backoff` which limits the number of attempts up to the specified value.
`static Backoff`	`withoutDelay()` Returns a `Backoff` that will never wait between attempts.

- Method Detail
  - 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:
    - exponential=[initialDelayMillis:maxDelayMillis:multiplier] is for exponential(long, long, double) (multiplier will be 2.0 if it's omitted)
    - fibonacci=[initialDelayMillis:maxDelayMillis] is for fibonacci(long, long)
    - fixed=[delayMillis] is for fixed(long)
    - random=[minDelayMillis:maxDelayMillis] is for random(long, long)
    - jitter=[minJitterRate:maxJitterRate] is for withJitter(double, double) (if only one jitter value is specified, it will be used for withJitter(double)
    - maxAttempts=[maxAttempts] is for withMaxAttempts(int)
    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
  - 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.

Interface Backoff

Method Summary

Method Detail

ofDefault

withoutDelay

fixed

exponential

exponential

fibonacci

random

random

of

nextDelayMillis

as

withJitter

withJitter

withJitter

withMaxAttempts