org.springframework.retry.support

Class RetryTemplate

java.lang.Object

org.springframework.retry.support.RetryTemplate

All Implemented Interfaces:

RetryOperations

public class RetryTemplate
extends java.lang.Object
implements RetryOperations

Template class that simplifies the execution of operations with retry semantics.
Retryable operations are encapsulated in implementations of the RetryCallback interface and are executed using one of the supplied execute methods.
By default, an operation is retried if is throws any Exception or subclass of Exception. This behaviour can be changed by using the setRetryPolicy(RetryPolicy) method.
Also by default, each operation is retried for a maximum of three attempts with no back off in between. This behaviour can be configured using the setRetryPolicy(RetryPolicy) and setBackOffPolicy(BackOffPolicy) properties. The BackOffPolicy controls how long the pause is between each individual retry attempt.
This class is thread-safe and suitable for concurrent access when executing operations and when performing configuration changes. As such, it is possible to change the number of retries on the fly, as well as the BackOffPolicy used and no in progress retryable operations will be affected.

Field Summary

Fields

Modifier and Type	Field and Description
private BackOffPolicy	backOffPolicy
private RetryListener[]	listeners
protected org.apache.commons.logging.Log	logger
private RetryContextCache	retryContextCache
private RetryPolicy	retryPolicy
private boolean	throwLastExceptionOnExhausted

Constructor Summary

Constructors

Constructor and Description
RetryTemplate()

Method Summary

Modifier and Type	Method and Description
protected boolean	canRetry(RetryPolicy retryPolicy, RetryContext context) Decide whether to proceed with the ongoing retry attempt.
protected void	close(RetryPolicy retryPolicy, RetryContext context, RetryState state, boolean succeeded) Clean up the cache if necessary and close the context provided (if the flag indicates that processing was successful).
private <T,E extends java.lang.Throwable> void	doCloseInterceptors(RetryCallback<T,E> callback, RetryContext context, java.lang.Throwable lastException)
protected <T,E extends java.lang.Throwable> T	doExecute(RetryCallback<T,E> retryCallback, RecoveryCallback<T> recoveryCallback, RetryState state) Execute the callback once if the policy dictates that we can, otherwise execute the recovery callback.
private <T,E extends java.lang.Throwable> void	doOnErrorInterceptors(RetryCallback<T,E> callback, RetryContext context, java.lang.Throwable throwable)
private <T,E extends java.lang.Throwable> boolean	doOpenInterceptors(RetryCallback<T,E> callback, RetryContext context)
private RetryContext	doOpenInternal(RetryPolicy retryPolicy)
<T,E extends java.lang.Throwable> T	execute(RetryCallback<T,E> retryCallback) Keep executing the callback until it either succeeds or the policy dictates that we stop, in which case the most recent exception thrown by the callback will be rethrown.
<T,E extends java.lang.Throwable> T	execute(RetryCallback<T,E> retryCallback, RecoveryCallback<T> recoveryCallback) Keep executing the callback until it either succeeds or the policy dictates that we stop, in which case the recovery callback will be executed.
<T,E extends java.lang.Throwable> T	execute(RetryCallback<T,E> retryCallback, RecoveryCallback<T> recoveryCallback, RetryState retryState) Execute the callback once if the policy dictates that we can, re-throwing any exception encountered so that clients can re-present the same task later.
<T,E extends java.lang.Throwable> T	execute(RetryCallback<T,E> retryCallback, RetryState retryState) Execute the callback once if the policy dictates that we can, re-throwing any exception encountered so that clients can re-present the same task later.
protected <T> T	handleRetryExhausted(RecoveryCallback<T> recoveryCallback, RetryContext context, RetryState state) Actions to take after final attempt has failed.
protected RetryContext	open(RetryPolicy retryPolicy, RetryState state) Delegate to the RetryPolicy having checked in the cache for an existing value if the state is not null.
void	registerListener(RetryListener listener) Register an additional listener.
protected void	registerThrowable(RetryPolicy retryPolicy, RetryState state, RetryContext context, java.lang.Throwable e)
protected <E extends java.lang.Throwable> void	rethrow(RetryContext context, java.lang.String message)
void	setBackOffPolicy(BackOffPolicy backOffPolicy) Setter for BackOffPolicy.
void	setListeners(RetryListener[] listeners) Setter for listeners.
void	setRetryContextCache(RetryContextCache retryContextCache) Public setter for the RetryContextCache.
void	setRetryPolicy(RetryPolicy retryPolicy) Setter for RetryPolicy.
void	setThrowLastExceptionOnExhausted(boolean throwLastExceptionOnExhausted)
protected boolean	shouldRethrow(RetryPolicy retryPolicy, RetryContext context, RetryState state) Extension point for subclasses to decide on behaviour after catching an exception in a RetryCallback.
private static <E extends java.lang.Throwable> E	wrapIfNecessary(java.lang.Throwable throwable) Re-throws the original throwable if it is an Exception, and wraps non-exceptions into RetryException.

Methods inherited from class java.lang.Object

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

Field Detail

logger

protected final org.apache.commons.logging.Log logger

backOffPolicy

private volatile BackOffPolicy backOffPolicy

retryPolicy

private volatile RetryPolicy retryPolicy

listeners

private volatile RetryListener[] listeners

retryContextCache

private RetryContextCache retryContextCache

throwLastExceptionOnExhausted

private boolean throwLastExceptionOnExhausted

Constructor Detail

RetryTemplate

public RetryTemplate()

Method Detail

setThrowLastExceptionOnExhausted

public void setThrowLastExceptionOnExhausted(boolean throwLastExceptionOnExhausted)

Parameters:

throwLastExceptionOnExhausted - the throwLastExceptionOnExhausted to set

setRetryContextCache

public void setRetryContextCache(RetryContextCache retryContextCache)

Public setter for the RetryContextCache.

Parameters:

retryContextCache - the RetryContextCache to set.

setListeners

public void setListeners(RetryListener[] listeners)

Setter for listeners. The listeners are executed before and after a retry block (i.e. before and after all the attempts), and on an error (every attempt).

Parameters:

listeners -

See Also:

RetryListener

registerListener

public void registerListener(RetryListener listener)

Register an additional listener.

Parameters:

listener -

See Also:

setListeners(RetryListener[])

setBackOffPolicy

public void setBackOffPolicy(BackOffPolicy backOffPolicy)

Setter for BackOffPolicy.

Parameters:

backOffPolicy -

setRetryPolicy

public void setRetryPolicy(RetryPolicy retryPolicy)

Setter for RetryPolicy.

Parameters:

retryPolicy -

execute

public final <T,E extends java.lang.Throwable> T execute(RetryCallback<T,E> retryCallback)
                                                  throws E extends java.lang.Throwable

Keep executing the callback until it either succeeds or the policy dictates that we stop, in which case the most recent exception thrown by the callback will be rethrown.

Specified by:

execute in interface RetryOperations

Returns:

the value returned by the RetryCallback upon successful invocation.

Throws:

TerminatedRetryException - if the retry has been manually terminated by a listener.

E extends java.lang.Throwable

See Also:

RetryOperations.execute(RetryCallback)

execute

public final <T,E extends java.lang.Throwable> T execute(RetryCallback<T,E> retryCallback,
                                                         RecoveryCallback<T> recoveryCallback)
                                                  throws E extends java.lang.Throwable

Keep executing the callback until it either succeeds or the policy dictates that we stop, in which case the recovery callback will be executed.

Specified by:

execute in interface RetryOperations

Returns:

the value returned by the RetryCallback upon successful invocation, and that returned by the RecoveryCallback otherwise.

Throws:

TerminatedRetryException - if the retry has been manually terminated by a listener.

E extends java.lang.Throwable

See Also:

RetryOperations.execute(RetryCallback, RecoveryCallback)

execute

public final <T,E extends java.lang.Throwable> T execute(RetryCallback<T,E> retryCallback,
                                                         RetryState retryState)
                                                  throws E extends java.lang.Throwable,
                                                         ExhaustedRetryException

Execute the callback once if the policy dictates that we can, re-throwing any exception encountered so that clients can re-present the same task later.

Specified by:

execute in interface RetryOperations

Returns:

the value returned by the RetryCallback upon successful invocation, and that returned by the RecoveryCallback otherwise.

Throws:

ExhaustedRetryException - if the retry has been exhausted.

E extends java.lang.Throwable

See Also:

RetryOperations.execute(RetryCallback, RetryState)

execute

public final <T,E extends java.lang.Throwable> T execute(RetryCallback<T,E> retryCallback,
                                                         RecoveryCallback<T> recoveryCallback,
                                                         RetryState retryState)
                                                  throws E extends java.lang.Throwable,
                                                         ExhaustedRetryException

Execute the callback once if the policy dictates that we can, re-throwing any exception encountered so that clients can re-present the same task later.

Specified by:

execute in interface RetryOperations

Returns:

the value returned by the RetryCallback upon successful invocation, and that returned by the RecoveryCallback otherwise.

Throws:

E extends java.lang.Throwable

ExhaustedRetryException

See Also:

RetryOperations.execute(RetryCallback, RetryState)

doExecute

protected <T,E extends java.lang.Throwable> T doExecute(RetryCallback<T,E> retryCallback,
                                                        RecoveryCallback<T> recoveryCallback,
                                                        RetryState state)
                                                 throws E extends java.lang.Throwable,
                                                        ExhaustedRetryException

Execute the callback once if the policy dictates that we can, otherwise execute the recovery callback.

Throws:

ExhaustedRetryException - if the retry has been exhausted. finally {

E extends java.lang.Throwable

See Also:

RetryOperations.execute(RetryCallback, RecoveryCallback, RetryState)

canRetry

protected boolean canRetry(RetryPolicy retryPolicy,
                           RetryContext context)

Decide whether to proceed with the ongoing retry attempt. This method is called before the RetryCallback is executed, but after the backoff and open interceptors.

Parameters:

retryPolicy - the policy to apply

context - the current retry context

Returns:

true if we can continue with the attempt

close

protected void close(RetryPolicy retryPolicy,
                     RetryContext context,
                     RetryState state,
                     boolean succeeded)

Clean up the cache if necessary and close the context provided (if the flag indicates that processing was successful).

Parameters:

context -

state -

succeeded -

registerThrowable

protected void registerThrowable(RetryPolicy retryPolicy,
                                 RetryState state,
                                 RetryContext context,
                                 java.lang.Throwable e)

Parameters:

retryPolicy -

state -

context -

e -

open

protected RetryContext open(RetryPolicy retryPolicy,
                            RetryState state)

Delegate to the RetryPolicy having checked in the cache for an existing value if the state is not null.

Parameters:

retryPolicy - a RetryPolicy to delegate the context creation

Returns:

a retry context, either a new one or the one used last time the same state was encountered

doOpenInternal

private RetryContext doOpenInternal(RetryPolicy retryPolicy)

Parameters:

retryPolicy -

Returns:

handleRetryExhausted

protected <T> T handleRetryExhausted(RecoveryCallback<T> recoveryCallback,
                                     RetryContext context,
                                     RetryState state)
                              throws java.lang.Throwable

Actions to take after final attempt has failed. If there is state clean up the cache. If there is a recovery callback, execute that and return its result. Otherwise throw an exception.

Parameters:

recoveryCallback - the callback for recovery (might be null)

context - the current retry context

Throws:

java.lang.Exception - if the callback does, and if there is no callback and the state is null then the last exception from the context

ExhaustedRetryException - if the state is not null and there is no recovery callback

java.lang.Throwable

rethrow

protected <E extends java.lang.Throwable> void rethrow(RetryContext context,
                                                       java.lang.String message)
                                                throws E extends java.lang.Throwable

Throws:

E extends java.lang.Throwable

shouldRethrow

protected boolean shouldRethrow(RetryPolicy retryPolicy,
                                RetryContext context,
                                RetryState state)

Extension point for subclasses to decide on behaviour after catching an exception in a RetryCallback. Normal stateless behaviour is not to rethrow, and if there is state we rethrow.

Parameters:

retryPolicy -

context - the current context

Returns:

true if the state is not null but subclasses might choose otherwise

doOpenInterceptors

private <T,E extends java.lang.Throwable> boolean doOpenInterceptors(RetryCallback<T,E> callback,
                                                                     RetryContext context)

doCloseInterceptors

private <T,E extends java.lang.Throwable> void doCloseInterceptors(RetryCallback<T,E> callback,
                                                                   RetryContext context,
                                                                   java.lang.Throwable lastException)

doOnErrorInterceptors

private <T,E extends java.lang.Throwable> void doOnErrorInterceptors(RetryCallback<T,E> callback,
                                                                     RetryContext context,
                                                                     java.lang.Throwable throwable)

wrapIfNecessary

private static <E extends java.lang.Throwable> E wrapIfNecessary(java.lang.Throwable throwable)
                                                          throws RetryException

Re-throws the original throwable if it is an Exception, and wraps non-exceptions into RetryException.

Throws:

RetryException