org.springframework.retry.support

Class RetryTemplateBuilder

java.lang.Object

org.springframework.retry.support.RetryTemplateBuilder

public class RetryTemplateBuilder
extends Object

Fluent API to configure new instance of RetryTemplate. For detailed description of each builder method - see it's doc.

Examples:

 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();
 

The builder provides the following defaults:

• retry policy: max attempts = 3 (initial + 2 retries)
• backoff policy: no backoff (retry immediately)
• exception classification: retry only on Exception and it's subclasses, without traversing of causes

The builder supports only widely used properties of RetryTemplate. More specific properties can be configured directly (after building).

Not thread safe. Building should be performed in a single thread. Also, there is no guarantee that all constructors of all fields are thread safe in-depth (means employing only volatile and final writes), so, in concurrent environment, it is recommended to ensure presence of happens-before between publication and any usage. (e.g. publication via volatile write, or other safe publication technique)

Since:

1.3

Author:

Aleksandr Shamukov, Artem Bilan, Kim In Hoi

Constructor Summary

Constructors

Constructor and Description
RetryTemplateBuilder()

Method Summary

Modifier and Type	Method and Description
RetryTemplate	build() Finish configuration and build resulting RetryTemplate.
RetryTemplateBuilder	customBackoff(BackOffPolicy backOffPolicy) You can provide your own BackOffPolicy via this method.
RetryTemplateBuilder	customPolicy(RetryPolicy policy) If flexibility of this builder is not enough for you, you can provide your own RetryPolicy via this method.
RetryTemplateBuilder	exponentialBackoff(long initialInterval, double multiplier, long maxInterval) Use exponential backoff policy.
RetryTemplateBuilder	exponentialBackoff(long initialInterval, double multiplier, long maxInterval, boolean withRandom) Use exponential backoff policy.
RetryTemplateBuilder	fixedBackoff(long interval) Perform each retry after fixed amount of time.
RetryTemplateBuilder	infiniteRetry() Allows infinite retry, do not limit attempts by number or time.
RetryTemplateBuilder	maxAttempts(int maxAttempts) Limits maximum number of attempts to provided value.
RetryTemplateBuilder	noBackoff() Do not pause between attempts, retry immediately.
RetryTemplateBuilder	notRetryOn(Class<? extends Throwable> throwable) Add a throwable to the black list of retryable exceptions.
RetryTemplateBuilder	notRetryOn(List<Class<? extends Throwable>> throwables) Add all throwables to the black list of retryable exceptions.
RetryTemplateBuilder	retryOn(Class<? extends Throwable> throwable) Add a throwable to the while list of retryable exceptions.
RetryTemplateBuilder	retryOn(List<Class<? extends Throwable>> throwables) Add all throwables to the while list of retryable exceptions.
RetryTemplateBuilder	traversingCauses() Suppose throwing a new MyLogicException(new IOException()).
RetryTemplateBuilder	uniformRandomBackoff(long minInterval, long maxInterval) Use UniformRandomBackOffPolicy, see it's doc for details.
RetryTemplateBuilder	withinMillis(long timeout) Allows retry if there is no more than timeout millis since first attempt.
RetryTemplateBuilder	withListener(RetryListener listener) Appends provided listener to RetryTemplate's listener list.
RetryTemplateBuilder	withListeners(List<RetryListener> listeners) Appends all provided listeners to RetryTemplate's listener list.

Methods inherited from class java.lang.Object

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

Constructor Detail

RetryTemplateBuilder

public RetryTemplateBuilder()

Method Detail

maxAttempts

public RetryTemplateBuilder maxAttempts(int maxAttempts)

Limits maximum number of attempts to provided value.

Invocation of this method does not discard default exception classification rule, that is "retry only on Exception and it's subclasses".

Parameters:

maxAttempts - includes initial attempt and all retries. E.g: maxAttempts = 3 means one initial attempt and two retries.

Returns:

this

See Also:

MaxAttemptsRetryPolicy

withinMillis

public RetryTemplateBuilder withinMillis(long timeout)

Allows retry if there is no more than timeout millis since first attempt.

Invocation of this method does not discard default exception classification rule, that is "retry only on Exception and it's subclasses".

Parameters:

timeout - whole execution timeout in milliseconds

Returns:

this

See Also:

TimeoutRetryPolicy

infiniteRetry

public RetryTemplateBuilder infiniteRetry()

Allows infinite retry, do not limit attempts by number or time.

Invocation of this method does not discard default exception classification rule, that is "retry only on Exception and it's subclasses".

Returns:

this

See Also:

TimeoutRetryPolicy

customPolicy

public RetryTemplateBuilder customPolicy(RetryPolicy policy)

If flexibility of this builder is not enough for you, you can provide your own RetryPolicy via this method.

Invocation of this method does not discard default exception classification rule, that is "retry only on Exception and it's subclasses".

Parameters:

policy - will be directly set to resulting RetryTemplate

Returns:

this

exponentialBackoff

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

Use exponential backoff policy. The formula of backoff period:

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

(for first attempt retryNum = 0)

Parameters:

initialInterval - in milliseconds

multiplier - see the formula above

maxInterval - in milliseconds

Returns:

this

See Also:

ExponentialBackOffPolicy

exponentialBackoff

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

Use exponential backoff policy. The formula of backoff period (without randomness):

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

(for first attempt retryNum = 0)

Parameters:

initialInterval - in milliseconds

multiplier - see the formula above

maxInterval - in milliseconds

withRandom - adds some randomness to backoff intervals. For details, see ExponentialRandomBackOffPolicy

Returns:

this

See Also:

ExponentialBackOffPolicy, ExponentialRandomBackOffPolicy

fixedBackoff

public RetryTemplateBuilder fixedBackoff(long interval)

Perform each retry after fixed amount of time.

Parameters:

interval - fixed interval in milliseconds

Returns:

this

See Also:

FixedBackOffPolicy

uniformRandomBackoff

public RetryTemplateBuilder uniformRandomBackoff(long minInterval,
                                                 long maxInterval)

Use UniformRandomBackOffPolicy, see it's doc for details.

Parameters:

minInterval - in milliseconds

maxInterval - in milliseconds

Returns:

this

See Also:

UniformRandomBackOffPolicy

noBackoff

public RetryTemplateBuilder noBackoff()

Do not pause between attempts, retry immediately.

Returns:

this

See Also:

NoBackOffPolicy

customBackoff

public RetryTemplateBuilder customBackoff(BackOffPolicy backOffPolicy)

You can provide your own BackOffPolicy via this method.

Parameters:

backOffPolicy - will be directly set to resulting RetryTemplate

Returns:

this

retryOn

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

Add a throwable to the while list of retryable exceptions.

Warn: touching this method drops default retryOn(Exception.class) and you should configure whole classifier from scratch.

You should select the way you want to configure exception classifier: white list or black list. If you choose white list - use this method, if black - use notRetryOn(Class) or notRetryOn(List)

Parameters:

throwable - to be retryable (with it's subclasses)

Returns:

this

See Also:

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

notRetryOn

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

Add a throwable to the black list of retryable exceptions.

Warn: touching this method drops default retryOn(Exception.class) and you should configure whole classifier from scratch.

You should select the way you want to configure exception classifier: white list or black list. If you choose black list - use this method, if white - use retryOn(Class) or retryOn(List)

Parameters:

throwable - to be not retryable (with it's subclasses)

Returns:

this

See Also:

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

retryOn

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

Add all throwables to the while list of retryable exceptions.

Warn: touching this method drops default retryOn(Exception.class) and you should configure whole classifier from scratch.

You should select the way you want to configure exception classifier: white list or black list. If you choose white list - use this method, if black - use notRetryOn(Class) or notRetryOn(List)

Parameters:

throwables - to be retryable (with it's subclasses)

Returns:

this

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 all throwables to the black list of retryable exceptions.

Warn: touching this method drops default retryOn(Exception.class) and you should configure whole classifier from scratch.

You should select the way you want to configure exception classifier: white list or black list. If you choose black list - use this method, if white - use retryOn(Class) or retryOn(List)

Parameters:

throwables - to be not retryable (with it's subclasses)

Returns:

this

Since:

1.3.2

See Also:

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

traversingCauses

public RetryTemplateBuilder traversingCauses()

Suppose throwing a new MyLogicException(new IOException()). This template will not retry on it:

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

but this will retry:

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

Returns:

this

See Also:

BinaryExceptionClassifier

withListener

public RetryTemplateBuilder withListener(RetryListener listener)

Appends provided listener to RetryTemplate's listener list.

Parameters:

listener - to be appended

Returns:

this

See Also:

RetryTemplate, RetryListener

withListeners

public RetryTemplateBuilder withListeners(List<RetryListener> listeners)

Appends all provided listeners to RetryTemplate's listener list.

Parameters:

listeners - to be appended

Returns:

this

See Also:

RetryTemplate, RetryListener

build

public RetryTemplate build()

Finish configuration and build resulting RetryTemplate. For default behaviour and concurrency note see class-level doc of RetryTemplateBuilder. The retryPolicy of the returned RetryTemplate is always an instance of CompositeRetryPolicy, that consists of one base policy, and of BinaryExceptionClassifierRetryPolicy. The motivation is: whatever base policy we use, exception classification is extremely recommended.

Returns:

new instance of RetryTemplate