public class ExponentialBackOff extends java.lang.Object implements BackOff
Implementation of BackOff that increases the back off period for each retry attempt using
a randomization function that grows exponentially.
<p>
nextBackOffMillis() is calculated using the following formula:
</p>
<pre> randomized_interval = retry_interval * (random value in range [1 - randomization_factor, 1 + randomization_factor]) </pre>
<p>
In other words nextBackOffMillis() will range between the randomization factor
percentage below and above the retry interval. For example, using 2 seconds as the base retry
interval and 0.5 as the randomization factor, the actual back off period used in the next retry
attempt will be between 1 and 3 seconds.
</p>
<p> <b>Note:</b> max_interval caps the retry_interval and not the randomized_interval. </p>
<p>
If the time elapsed since an ExponentialBackOff instance is created goes past the
max_elapsed_time then the method nextBackOffMillis() starts returning
BackOff.STOP. The elapsed time can be reset by calling reset().
</p>
<p> Example: The default retry_interval is .5 seconds, default randomization_factor is 0.5, default multiplier is 1.5 and the default max_interval is 1 minute. For 10 tries the sequence will be (values in seconds) and assuming we go over the max_elapsed_time on the 10th try: </p>
<pre> request# retry_interval randomized_interval
1 0.5 [0.25, 0.75]
2 0.75 [0.375, 1.125]
3 1.125 [0.562, 1.687]
4 1.687 [0.8435, 2.53]
5 2.53 [1.265, 3.795]
6 3.795 [1.897, 5.692]
7 5.692 [2.846, 8.538]
8 8.538 [4.269, 12.807]
9 12.807 [6.403, 19.210]
10 19.210 BackOff.STOP
</pre>
<p> Implementation is not thread-safe. </p>
| Modifier and Type | Class and Description |
|---|---|
static class |
ExponentialBackOff.Builder
Builder for
ExponentialBackOff. |
static interface |
ExponentialBackOff.NanoClock
Nano clock which can be used to measure elapsed time in nanoseconds.
|
| Modifier and Type | Field and Description |
|---|---|
static int |
DEFAULT_INITIAL_INTERVAL_MILLIS
The default initial interval value in milliseconds (0.5 seconds).
|
static int |
DEFAULT_MAX_ELAPSED_TIME_MILLIS
The default maximum elapsed time in milliseconds (15 minutes).
|
static int |
DEFAULT_MAX_INTERVAL_MILLIS
The default maximum back off time in milliseconds (1 minute).
|
static double |
DEFAULT_MULTIPLIER
The default multiplier value (1.5 which is 50% increase per back off).
|
static double |
DEFAULT_RANDOMIZATION_FACTOR
The default randomization factor (0.5 which results in a random period ranging between 50%
below and 50% above the retry interval).
|
STOP, STOP_BACKOFF, ZERO_BACKOFF| Constructor and Description |
|---|
ExponentialBackOff()
Creates an instance of ExponentialBackOffPolicy using default values.
|
| Modifier and Type | Method and Description |
|---|---|
int |
getCurrentIntervalMillis()
Returns the current retry interval in milliseconds.
|
long |
getElapsedTimeMillis()
Returns the elapsed time in milliseconds since an
ExponentialBackOff instance is
created and is reset when reset() is called. |
int |
getInitialIntervalMillis()
Returns the initial retry interval in milliseconds.
|
int |
getMaxElapsedTimeMillis()
Returns the maximum elapsed time in milliseconds.
|
int |
getMaxIntervalMillis()
Returns the maximum value of the back off period in milliseconds.
|
double |
getMultiplier()
Returns the value to multiply the current interval with for each retry attempt.
|
double |
getRandomizationFactor()
Returns the randomization factor to use for creating a range around the retry interval.
|
static int |
getRandomValueFromInterval(double randomizationFactor,
double random,
int currentIntervalMillis)
Returns a random value from the interval [randomizationFactor * currentInterval,
randomizationFactor * currentInterval].
|
long |
nextBackOffMillis()
Gets the number of milliseconds to wait before retrying the operation or
BackOff.STOP to
indicate that no retries should be made. |
void |
reset()
Sets the interval back to the initial retry interval and restarts the timer.
|
void |
setStartTimeNanos(long startTimeNanos) |
public static final int DEFAULT_INITIAL_INTERVAL_MILLIS
The default initial interval value in milliseconds (0.5 seconds).
public static final double DEFAULT_RANDOMIZATION_FACTOR
The default randomization factor (0.5 which results in a random period ranging between 50% below and 50% above the retry interval).
public static final double DEFAULT_MULTIPLIER
The default multiplier value (1.5 which is 50% increase per back off).
public static final int DEFAULT_MAX_INTERVAL_MILLIS
The default maximum back off time in milliseconds (1 minute).
public static final int DEFAULT_MAX_ELAPSED_TIME_MILLIS
The default maximum elapsed time in milliseconds (15 minutes).
public ExponentialBackOff()
Creates an instance of ExponentialBackOffPolicy using default values.
<p>
To override the defaults use ExponentialBackOff.Builder.
</p>
<ul>
<li>initialIntervalMillis defaults to DEFAULT_INITIAL_INTERVAL_MILLIS</li>
<li>randomizationFactor defaults to DEFAULT_RANDOMIZATION_FACTOR</li>
<li>multiplier defaults to DEFAULT_MULTIPLIER</li>
<li>maxIntervalMillis defaults to DEFAULT_MAX_INTERVAL_MILLIS</li>
<li>maxElapsedTimeMillis defaults in DEFAULT_MAX_ELAPSED_TIME_MILLIS</li>
</ul>
public final void reset()
Sets the interval back to the initial retry interval and restarts the timer.
public void setStartTimeNanos(long startTimeNanos)
public long nextBackOffMillis()
Gets the number of milliseconds to wait before retrying the operation or BackOff.STOP to
indicate that no retries should be made.
<p> Example usage: </p>
<pre> long backOffMillis = backoff.nextBackOffMillis(); if (backOffMillis == Backoff.STOP) { // do not retry operation } else { // sleep for backOffMillis milliseconds and retry operation } </pre>
<p> This method calculates the next back off interval using the formula: randomized_interval = retry_interval +/- (randomization_factor * retry_interval) </p>
<p> Subclasses may override if a different algorithm is required. </p>
nextBackOffMillis in interface BackOffpublic static int getRandomValueFromInterval(double randomizationFactor,
double random,
int currentIntervalMillis)
Returns a random value from the interval [randomizationFactor * currentInterval, randomizationFactor * currentInterval].
public final int getInitialIntervalMillis()
Returns the initial retry interval in milliseconds.
public final double getRandomizationFactor()
Returns the randomization factor to use for creating a range around the retry interval.
<p> A randomization factor of 0.5 results in a random period ranging between 50% below and 50% above the retry interval. </p>
public final int getCurrentIntervalMillis()
Returns the current retry interval in milliseconds.
public final double getMultiplier()
Returns the value to multiply the current interval with for each retry attempt.
public final int getMaxIntervalMillis()
Returns the maximum value of the back off period in milliseconds. Once the current interval reaches this value it stops increasing.
public final int getMaxElapsedTimeMillis()
Returns the maximum elapsed time in milliseconds.
<p>
If the time elapsed since an ExponentialBackOff instance is created goes past the
max_elapsed_time then the method nextBackOffMillis() starts returning
BackOff.STOP. The elapsed time can be reset by calling reset().
</p>
public final long getElapsedTimeMillis()
Returns the elapsed time in milliseconds since an ExponentialBackOff instance is
created and is reset when reset() is called.
<p>
The elapsed time is computed using System.nanoTime().
</p>