Package org.springframework.retry.support

Class RetryTemplateBuilder

java.lang.Object

org.springframework.retry.support.RetryTemplateBuilder

public class RetryTemplateBuilder
extends Object

Builder that provides a fluent API to configure new instances of RetryTemplate.

By default, the builder configures a BinaryExceptionClassifier that acts upon Exception and its subclasses without traversing causes, a NoBackOffPolicy and a MaxAttemptsRetryPolicy that attempts actions MaxAttemptsRetryPolicy.DEFAULT_MAX_ATTEMPTS times.

The builder is not thread-safe.

Example usage:

 RetryTemplate.builder()
      .maxAttempts(10)
      .exponentialBackoff(100, 2, 10000)
      .retryOn(IOException.class)
      .traversingCauses()
      .build();

 RetryTemplate.builder()
      .fixedBackoff(10)
      .withinMillis(3000)
      .build();

 RetryTemplate.builder()
      .infiniteRetry()
      .retryOn(IOException.class)
      .uniformRandomBackoff(1000, 3000)
      .build();
 

Since:

1.3

Author:

Aleksandr Shamukov, Artem Bilan, Kim In Hoi, Andreas Ahlenstorf, Morulai Planinski, Tobias Soloschenko

Constructor Summary

Constructors

Constructor	Description
RetryTemplateBuilder()

Method Summary

Modifier and Type	Method	Description
RetryTemplate	build()	Build a new RetryTemplate.
RetryTemplateBuilder	customBackoff(BackOffPolicy backOffPolicy)	Use the provided BackOffPolicy.
RetryTemplateBuilder	customPolicy(RetryPolicy policy)	Use the provided RetryPolicy.
RetryTemplateBuilder	exponentialBackoff(long initialInterval, double multiplier, long maxInterval)	Use an exponential backoff policy.
RetryTemplateBuilder	exponentialBackoff(long initialInterval, double multiplier, long maxInterval, boolean withRandom)	Use an exponential backoff policy.
RetryTemplateBuilder	exponentialBackoff(Duration initialInterval, double multiplier, Duration maxInterval)	Use an exponential backoff policy.
RetryTemplateBuilder	exponentialBackoff(Duration initialInterval, double multiplier, Duration maxInterval, boolean withRandom)	Use an exponential backoff policy.
RetryTemplateBuilder	fixedBackoff(long interval)	Perform each retry after a fixed amount of time.
RetryTemplateBuilder	fixedBackoff(Duration interval)	Perform each retry after fixed amount of time.
RetryTemplateBuilder	infiniteRetry()	Retry actions infinitely.
RetryTemplateBuilder	maxAttempts(int maxAttempts)	Attempt an action no more than maxAttempts times.
RetryTemplateBuilder	noBackoff()	Retry immediately without pausing between attempts.
RetryTemplateBuilder	notRetryOn(Class<? extends Throwable> throwable)	Add the Throwable and its subclasses to the list of exceptions that do not cause a retry.
RetryTemplateBuilder	notRetryOn(List<Class<? extends Throwable>> throwables)	Add the list of Throwable classes and their subclasses to the list of exceptions that do not cause a retry.
RetryTemplateBuilder	retryOn(Class<? extends Throwable> throwable)	Add the Throwable and its subclasses to the list of exceptions that cause a retry.
RetryTemplateBuilder	retryOn(Predicate<Throwable> predicate)	Set a Predicate<Throwable> that decides if the exception causes a retry.
RetryTemplateBuilder	retryOn(List<Class<? extends Throwable>> throwables)	Add the list of Throwable classes and their subclasses to the list of exceptions that cause a retry.
RetryTemplateBuilder	traversingCauses()	Enable examining exception causes for Throwable instances that cause a retry.
RetryTemplateBuilder	uniformRandomBackoff(long minInterval, long maxInterval)	Use UniformRandomBackOffPolicy.
RetryTemplateBuilder	uniformRandomBackoff(Duration minInterval, Duration maxInterval)	Use UniformRandomBackOffPolicy.
RetryTemplateBuilder	withinMillis(long timeout)	Deprecated, for removal: This API element is subject to removal in a future version. Use withTimeout(long) instead.
RetryTemplateBuilder	withListener(RetryListener listener)	Append the provided listener to RetryTemplate's list of listeners.
RetryTemplateBuilder	withListeners(List<RetryListener> listeners)	Append all provided listeners to RetryTemplate's list of listeners.
RetryTemplateBuilder	withLogger(org.apache.commons.logging.Log logger)	Applies a dedicated logger to the RetryTemplate.
RetryTemplateBuilder	withTimeout(long timeoutMillis)	Retry until timeoutMillis has passed since the initial attempt.
RetryTemplateBuilder	withTimeout(Duration timeout)	Retry until timeout has passed since the initial attempt.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

RetryTemplateBuilder

public RetryTemplateBuilder()

Method Details

maxAttempts

public RetryTemplateBuilder maxAttempts(int maxAttempts)

Attempt an action no more than maxAttempts times.

Parameters:

maxAttempts - how many times an action should be attempted. A value of 3 would result in an initial attempt and two retries.

Returns:

this

Throws:

IllegalArgumentException - if maxAttempts is 0 or less, or if another retry policy has already been selected.

See Also:

• MaxAttemptsRetryPolicy

withinMillis

@Deprecated(since="2.0.2",
            forRemoval=true)
public RetryTemplateBuilder withinMillis(long timeout)

Deprecated, for removal: This API element is subject to removal in a future version.

Use withTimeout(long) instead.

Retry until timeout has passed since the initial attempt.

Parameters:

timeout - timeout in milliseconds

Returns:

this

Throws:

IllegalArgumentException - if timeout is <= 0 or if another retry policy has already been selected.

See Also:

• TimeoutRetryPolicy

withTimeout

public RetryTemplateBuilder withTimeout(long timeoutMillis)

Retry until timeoutMillis has passed since the initial attempt.

Parameters:

timeoutMillis - timeout in milliseconds

Returns:

this

Throws:

IllegalArgumentException - if timeout is <= 0 or if another retry policy has already been selected.

Since:

2.0.2

See Also:

• TimeoutRetryPolicy

withTimeout

public RetryTemplateBuilder withTimeout(Duration timeout)

Retry until timeout has passed since the initial attempt.

Parameters:

timeout - duration for how long retries should be attempted

Returns:

this

Throws:

IllegalArgumentException - if timeout is null or 0, or if another retry policy has already been selected.

Since:

2.0.2

See Also:

• TimeoutRetryPolicy

infiniteRetry

public RetryTemplateBuilder infiniteRetry()

Retry actions infinitely.

Returns:

this

Throws:

IllegalArgumentException - if another retry policy has already been selected.

See Also:

• AlwaysRetryPolicy

customPolicy

public RetryTemplateBuilder customPolicy(RetryPolicy policy)

Use the provided RetryPolicy.

Parameters:

policy - RetryPolicy to use

Returns:

this

Throws:

IllegalArgumentException - if another backoff policy has already been selected, if any argument is null, or if another retry policy has already been selected.

exponentialBackoff

public RetryTemplateBuilder exponentialBackoff(long initialInterval,
 double multiplier,
 long maxInterval)

Use an exponential backoff policy. The formula for the backoff period is:

currentInterval = Math.min(initialInterval * Math.pow(multiplier, retryNum), maxInterval)

For the first attempt, retryNum = 0.

Parameters:

initialInterval - initial sleep duration in milliseconds

multiplier - backoff interval multiplier

maxInterval - maximum backoff duration in milliseconds

Returns:

this

Throws:

IllegalArgumentException - if another backoff policy has already been selected, if initialInterval is < 1, if multiplier is <= 1, or if maxInterval <= initialInterval.

See Also:

• ExponentialBackOffPolicy

exponentialBackoff

public RetryTemplateBuilder exponentialBackoff(Duration initialInterval,
 double multiplier,
 Duration maxInterval)

Use an exponential backoff policy. The formula for the backoff period is:

currentInterval = Math.min(initialInterval * Math.pow(multiplier, retryNum), maxInterval)

For the first attempt, retryNum = 0.

Parameters:

initialInterval - initial sleep duration

multiplier - backoff interval multiplier

maxInterval - maximum backoff duration

Returns:

this

Throws:

IllegalArgumentException - if another backoff policy has already been selected, if initialInterval is null or less than 1 millisecond, multiplier is <= 1, or if maxInterval is null or <= initialInterval.

Since:

2.0.2

See Also:

• ExponentialBackOffPolicy

exponentialBackoff

public RetryTemplateBuilder exponentialBackoff(long initialInterval,
 double multiplier,
 long maxInterval,
 boolean withRandom)

Use an exponential backoff policy. The formula for the backoff period is (without randomness):

currentInterval = Math.min(initialInterval * Math.pow(multiplier, retryNum), maxInterval)

For the first attempt, retryNum = 0.

Parameters:

initialInterval - initial sleep duration in milliseconds

multiplier - backoff interval multiplier

maxInterval - maximum backoff duration in milliseconds

withRandom - whether to use a ExponentialRandomBackOffPolicy (if true) or not

Returns:

this

Throws:

IllegalArgumentException - if another backoff policy has already been selected, if initialInterval is < 1, if multiplier is <= 1, or if maxInterval <= initialInterval.

See Also:

• ExponentialBackOffPolicy
• ExponentialRandomBackOffPolicy

exponentialBackoff

public RetryTemplateBuilder exponentialBackoff(Duration initialInterval,
 double multiplier,
 Duration maxInterval,
 boolean withRandom)

Use an exponential backoff policy. The formula for the backoff period is (without randomness):

currentInterval = Math.min(initialInterval * Math.pow(multiplier, retryNum), maxInterval)

For the first attempt, retryNum = 0.

Parameters:

initialInterval - initial sleep duration

multiplier - backoff interval multiplier

maxInterval - maximum backoff duration

withRandom - whether to use a ExponentialRandomBackOffPolicy (if true) or not

Returns:

this

Throws:

IllegalArgumentException - if another backoff policy has already been selected, if initialInterval is null or less than 1 millisecond, if multiplier is <= 1, or if maxInterval is null or <= initialInterval.

Since:

2.0.2

See Also:

• ExponentialBackOffPolicy
• ExponentialRandomBackOffPolicy

withLogger

public RetryTemplateBuilder withLogger(org.apache.commons.logging.Log logger)

Applies a dedicated logger to the RetryTemplate. If not applied the following is used:

LogFactory.getLog(getClass())

Parameters:

logger - the logger which should be used for logging

Returns:

this

Since:

2.0.10

fixedBackoff

public RetryTemplateBuilder fixedBackoff(long interval)

Perform each retry after a fixed amount of time.

Parameters:

interval - fixed interval in milliseconds

Returns:

this

Throws:

IllegalArgumentException - if another backoff policy has already been selected, or if interval is < 1.

See Also:

• FixedBackOffPolicy

fixedBackoff

public RetryTemplateBuilder fixedBackoff(Duration interval)

Perform each retry after fixed amount of time.

Parameters:

interval - fixed backoff duration

Returns:

this

Throws:

IllegalArgumentException - if another backoff policy has already been selected, or if interval is null or less than 1 millisecond

Since:

2.0.2

See Also:

• FixedBackOffPolicy

uniformRandomBackoff

public RetryTemplateBuilder uniformRandomBackoff(long minInterval,
 long maxInterval)

Use UniformRandomBackOffPolicy.

Parameters:

minInterval - minimal interval in milliseconds

maxInterval - maximal interval in milliseconds

Returns:

this

Throws:

IllegalArgumentException - if another backoff policy has already been selected, if minInterval is < 1, maxInterval is < 1, or if maxInterval is <= minInterval.

See Also:

• UniformRandomBackOffPolicy

uniformRandomBackoff

public RetryTemplateBuilder uniformRandomBackoff(Duration minInterval,
 Duration maxInterval)

Use UniformRandomBackOffPolicy.

Parameters:

minInterval - minimum backoff duration

maxInterval - maximum backoff duration

Returns:

this

Throws:

IllegalArgumentException - if another backoff policy has already been selected, if minInterval is null or < 1, maxInterval is null or less than 1 millisecond, or if maxInterval <= minInterval.

Since:

2.0.2

See Also:

• UniformRandomBackOffPolicy

noBackoff

public RetryTemplateBuilder noBackoff()

Retry immediately without pausing between attempts.

Returns:

this

Throws:

IllegalArgumentException - if another backoff policy has already been selected.

See Also:

• NoBackOffPolicy

customBackoff

public RetryTemplateBuilder customBackoff(BackOffPolicy backOffPolicy)

Use the provided BackOffPolicy.

Parameters:

backOffPolicy - BackOffPolicy to use

Returns:

this

Throws:

IllegalArgumentException - if backOffPolicy is null or if another backoff policy has already been selected.

retryOn

public RetryTemplateBuilder retryOn(Class<? extends Throwable> throwable)

Add the Throwable and its subclasses to the list of exceptions that cause a retry.

retryOn() and notRetryOn() are mutually exclusive. Trying to use both causes an IllegalArgumentException.

Parameters:

throwable - that causes a retry

Returns:

this

Throws:

IllegalArgumentException - if throwable is null, or if notRetryOn(java.lang.Class<? extends java.lang.Throwable>) has already been used.

See Also:

• BinaryExceptionClassifierBuilder.retryOn(java.lang.Class<? extends java.lang.Throwable>)
• BinaryExceptionClassifier

notRetryOn

public RetryTemplateBuilder notRetryOn(Class<? extends Throwable> throwable)

Add the Throwable and its subclasses to the list of exceptions that do not cause a retry.

retryOn() and notRetryOn() are mutually exclusive. Trying to use both causes an IllegalArgumentException.

Parameters:

throwable - that does not cause a retry

Returns:

this

Throws:

IllegalArgumentException - if throwable is null, or if retryOn(java.lang.Class<? extends java.lang.Throwable>) has already been used.

See Also:

• BinaryExceptionClassifierBuilder.notRetryOn(java.lang.Class<? extends java.lang.Throwable>)
• BinaryExceptionClassifier

retryOn

public RetryTemplateBuilder retryOn(List<Class<? extends Throwable>> throwables)

Add the list of Throwable classes and their subclasses to the list of exceptions that cause a retry.

retryOn() and notRetryOn() are mutually exclusive. Trying to use both causes an IllegalArgumentException.

Parameters:

throwables - that cause a retry

Returns:

this

Throws:

IllegalArgumentException - if notRetryOn(java.lang.Class<? extends java.lang.Throwable>) has already been used.

Since:

1.3.2

See Also:

• BinaryExceptionClassifierBuilder.retryOn(java.lang.Class<? extends java.lang.Throwable>)
• BinaryExceptionClassifier

notRetryOn

public RetryTemplateBuilder notRetryOn(List<Class<? extends Throwable>> throwables)

Add the list of Throwable classes and their subclasses to the list of exceptions that do not cause a retry.

retryOn() and notRetryOn() are mutually exclusive. Trying to use both causes an IllegalArgumentException.

Parameters:

throwables - that do not cause a retry

Returns:

this

Throws:

IllegalArgumentException - if retryOn(java.lang.Class<? extends java.lang.Throwable>) has already been used.

Since:

1.3.2

See Also:

• BinaryExceptionClassifierBuilder.notRetryOn(java.lang.Class<? extends java.lang.Throwable>)
• BinaryExceptionClassifier

retryOn

public RetryTemplateBuilder retryOn(Predicate<Throwable> predicate)

Set a Predicate<Throwable> that decides if the exception causes a retry.

retryOn(Predicate<Throwable>) cannot be mixed with other retryOn() or noRetryOn(). Attempting to do so will result in a IllegalArgumentException.

Parameters:

predicate - if the exception causes a retry.

Returns:

this

Throws:

IllegalArgumentException - if retryOn(java.lang.Class<? extends java.lang.Throwable>) or notRetryOn(java.lang.Class<? extends java.lang.Throwable>) has already been used.

Since:

2.0.7

See Also:

• BinaryExceptionClassifierRetryPolicy

traversingCauses

public RetryTemplateBuilder traversingCauses()

Enable examining exception causes for Throwable instances that cause a retry.

Suppose the following RetryTemplate:

 RetryTemplate.builder()
          .retryOn(IOException.class)
          .build()
 

It will act on code that throws an IOException, for example, throw new IOException(). But it will not retry the action if the IOException is wrapped in another exception, for example, throw new MyException(new IOException()). However, this RetryTemplate will:

 RetryTemplate.builder()
          .retryOn(IOException.class)
          .traversingCauses()
          .build()
 

Returns:

this

See Also:

• BinaryExceptionClassifier

withListener

public RetryTemplateBuilder withListener(RetryListener listener)

Append the provided listener to RetryTemplate's list of listeners.

Parameters:

listener - to be appended

Returns:

this

Throws:

IllegalArgumentException - if listener is null.

See Also:

• RetryListener

withListeners

public RetryTemplateBuilder withListeners(List<RetryListener> listeners)

Append all provided listeners to RetryTemplate's list of listeners.

Parameters:

listeners - to be appended

Returns:

this

Throws:

IllegalArgumentException - if any of the listeners is null.

See Also:

• RetryListener

build

public RetryTemplate build()

Build a new RetryTemplate.

Supports building multiple instances. However, it is not possible to change the configuration between multiple build() calls.

The retryPolicy of the returned RetryTemplate is always a CompositeRetryPolicy that consists of one base policy and of BinaryExceptionClassifierRetryPolicy to enable exception classification regardless of the base policy.

Returns:

new instance of RetryTemplate