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 Summary
Modifier and Type Method Description default <T> T
as(Class<T> type)
static Backoff
exponential(long initialDelayMillis, long maxDelayMillis)
Returns aBackoff
that waits an exponentiallyincreasing amount of time between attempts.static Backoff
exponential(long initialDelayMillis, long maxDelayMillis, double multiplier)
Returns aBackoff
that waits an exponentiallyincreasing amount of time between attempts.static Backoff
fibonacci(long initialDelayMillis, long maxDelayMillis)
Returns aBackoff
for which the backoff delay increases in line with the Fibonacci sequence f(n) = f(n1) + f(n2) where f(0) = f(1) =initialDelayMillis
.static Backoff
fixed(long delayMillis)
Returns aBackoff
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 newBackoff
that computes backoff delay using one ofexponential(long, long, double)
,fibonacci(long, long)
,fixed(long)
andrandom(long, long)
chaining withwithJitter(double, double)
andwithMaxAttempts(int)
from thespecification
string that conforms to the following format:exponential=[initialDelayMillis:maxDelayMillis:multiplier]
is forexponential(long, long, double)
(multiplier will be 2.0 if it's omitted)fibonacci=[initialDelayMillis:maxDelayMillis]
is forfibonacci(long, long)
fixed=[delayMillis]
is forfixed(long)
random=[minDelayMillis:maxDelayMillis]
is forrandom(long, long)
jitter=[minJitterRate:maxJitterRate]
is forwithJitter(double, double)
(if only one jitter value is specified, it will be used forwithJitter(double)
maxAttempts=[maxAttempts]
is forwithMaxAttempts(int)
The order of options does not matter, and thespecification
needs at least one option.static Backoff
ofDefault()
Returns the defaultBackoff
.static Backoff
random(long minDelayMillis, long maxDelayMillis)
Returns aBackoff
that computes backoff delay which is a random value betweenminDelayMillis
andmaxDelayMillis
chosen byThreadLocalRandom
.static Backoff
random(long minDelayMillis, long maxDelayMillis, Supplier<Random> randomSupplier)
Returns aBackoff
that computes backoff delay which is a random value betweenminDelayMillis
andmaxDelayMillis
.default Backoff
withJitter(double jitterRate)
Returns aBackoff
that adds a random jitter value to the original delay using full jitter strategy.default Backoff
withJitter(double minJitterRate, double maxJitterRate)
Returns aBackoff
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 aBackoff
that adds a random jitter value to the original delay using full jitter strategy.default Backoff
withMaxAttempts(int maxAttempts)
Returns aBackoff
which limits the number of attempts up to the specified value.static Backoff
withoutDelay()
Returns aBackoff
that will never wait between attempts.

Method Details

ofDefault
Returns the defaultBackoff
. 
withoutDelay
Returns aBackoff
that will never wait between attempts. In most cases, using back off without delay is very dangerous. Please consider usingexponential(long, long)
withwithJitter(double)
orfixed(long)
with pre calculated delay depending on the situation. 
fixed
Returns aBackoff
that waits a fixed delay between attempts. 
exponential
Returns aBackoff
that waits an exponentiallyincreasing amount of time between attempts. 
exponential
Returns aBackoff
that waits an exponentiallyincreasing amount of time between attempts. 
fibonacci
Returns aBackoff
for which the backoff delay increases in line with the Fibonacci sequence f(n) = f(n1) + f(n2) where f(0) = f(1) =initialDelayMillis
. 
random
Returns aBackoff
that computes backoff delay which is a random value betweenminDelayMillis
andmaxDelayMillis
chosen byThreadLocalRandom
. 
random
Returns aBackoff
that computes backoff delay which is a random value betweenminDelayMillis
andmaxDelayMillis
. 
of
Creates a newBackoff
that computes backoff delay using one ofexponential(long, long, double)
,fibonacci(long, long)
,fixed(long)
andrandom(long, long)
chaining withwithJitter(double, double)
andwithMaxAttempts(int)
from thespecification
string that conforms to the following format:exponential=[initialDelayMillis:maxDelayMillis:multiplier]
is forexponential(long, long, double)
(multiplier will be 2.0 if it's omitted)fibonacci=[initialDelayMillis:maxDelayMillis]
is forfibonacci(long, long)
fixed=[delayMillis]
is forfixed(long)
random=[minDelayMillis:maxDelayMillis]
is forrandom(long, long)
jitter=[minJitterRate:maxJitterRate]
is forwithJitter(double, double)
(if only one jitter value is specified, it will be used forwithJitter(double)
maxAttempts=[maxAttempts]
is forwithMaxAttempts(int)
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 aBackoff

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
 ifnumAttemptsSoFar
is equal to or less than0

as
 Specified by:
as
in interfaceUnwrappable
 Parameters:
type
 the type of the desiredBackoff
 Returns:
 the
Backoff
which is an instance oftype
if thisBackoff
decorated such aBackoff
, ornull
otherwise.  See Also:
Unwrappable

withJitter
Returns aBackoff
that adds a random jitter value to the original delay using full jitter strategy. ThejitterRate
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 byexponential(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) byThreadLocalRandom
. 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
 ifjitterRate
is a negative value or greater than 1.0

withJitter
Returns aBackoff
that adds a random jitter value to the original delay using full jitter strategy. TheminJitterRate
andmaxJitterRate
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 byexponential(long, long)
is 1000 milliseconds and theminJitterRate
is 0.2,maxJitterRate
is 0.3, the ultimate backoff delay will be chosen between 1000 * (1  0.2) and 1000 * (1 + 0.3) byThreadLocalRandom
. 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 delaymaxJitterRate
 the rate that used to calculate the upper bound of the backoff delay Throws:
IllegalArgumentException
 ifminJitterRate
is greater thanmaxJitterRate
or if theminJitterRate
andmaxJitterRate
values are not in between 1.0 and 1.0

withJitter
default Backoff withJitter(double minJitterRate, double maxJitterRate, Supplier<Random> randomSupplier)Returns aBackoff
that adds a random jitter value to the original delay using full jitter strategy. TheminJitterRate
andmaxJitterRate
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 byexponential(long, long)
is 1000 milliseconds and theminJitterRate
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 delaymaxJitterRate
 the rate that used to calculate the upper bound of the backoff delayrandomSupplier
 the supplier that providesRandom
in order to calculate the ultimate delay Throws:
IllegalArgumentException
 ifminJitterRate
is greater thanmaxJitterRate
or if theminJitterRate
andmaxJitterRate
values are not in between 1.0 and 1.0

withMaxAttempts
Returns aBackoff
which limits the number of attempts up to the specified value.
