Package com.linecorp.armeria.client.retry

Interface Backoff

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

Controls back off between attempts in a single retry operation.

Method Summary

Modifier and Type	Method	Description
default <T> Optional<T>	as(Class<T> backoffType)	Undecorates this Backoff to find the Backoff which is an instance of the specified backoffType.
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	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), fixed(long) and random(long, long) chaining with withJitter(double, double) and withMaxAttempts(int) from the specification.
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.

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), fixed(long) and random(long, long) chaining with withJitter(double, double) and withMaxAttempts(int) from the specification. This is the format for the specification:

• exponential=[initialDelayMillis:maxDelayMillis:multiplier] is for exponential(long, long, double) (multiplier will be 2.0 if it's omitted)
• 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. These are a few examples:

• exponential=200:10000:2.0,jitter=0.2 (default)
• exponential=200:10000,jitter=0.2,maxAttempts=50 (multiplier omitted)
• 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 the 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> Optional<T> as(Class<T> backoffType)

Undecorates this Backoff to find the Backoff which is an instance of the specified backoffType.

Parameters:

backoffType - the type of the desired Backoff

Returns:

the Backoff which is an instance of backoffType if this Backoff decorated such a Backoff. Optional.empty() otherwise.

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.