org.libj.util.retry

Class RetryPolicy<E extends Exception>

java.lang.Object

org.libj.util.retry.RetryPolicy<E>

Type Parameters:

E - The type parameter of the Exception instance signifying terminal failure of the RetryPolicy execution.

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

ExponentialBackoffRetryPolicy, LinearDelayRetryPolicy

public abstract class RetryPolicy<E extends Exception>
extends Object
implements Serializable

A policy that defines the conditions and timing of when retries should be performed.

The retryOn(Exception) method specifies the exception conditions of when a retry should occur.

The run(Retryable) method is the entrypoint for a Retryable object to be executed.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
RetryPolicy(int maxRetries, double jitter) Creates a new RetryPolicy with the specified maxRetries value.

Method Summary

Modifier and Type	Method and Description
protected abstract long	getDelayMs(int attemptNo) Returns the delay in milliseconds for the specified attempt number.
int	getMaxRetries() Returns the number of retry attempts allowed by this RetryPolicy.
protected void	onRetry(int attemptNo) Method that is called before each execution of Retryable.retry(RetryPolicy,int).
protected E	onRetryFailure(Exception e, int attemptNo, long delayMs) Callback to return the Exception instance of type <E> to be thrown in the event of terminal failure of the RetryPolicy execution.
protected abstract boolean	retryOn(Exception e) Specifies the exception conditions of when a retry should occur.
<T> T	run(Retryable<T,E> retryable) The entrypoint for a Retryable object to be executed.
<T> T	run(Retryable<T,E> retryable, long timeout) The entrypoint for a Retryable object to be executed.

Methods inherited from class java.lang.Object

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

Constructor Detail

RetryPolicy

public RetryPolicy(int maxRetries,
                   double jitter)

Creates a new RetryPolicy with the specified maxRetries value.

Parameters:

maxRetries - A positive value representing the number of retry attempts allowed by the RetryPolicy.

jitter - The factor multiplier to be applied to getDelayMs(int) to thereafter be added to the delay for each retry.

Throws:

IllegalArgumentException - If maxRetries or jitter is negative.

Method Detail

retryOn

protected abstract boolean retryOn(Exception e)

Specifies the exception conditions of when a retry should occur.

Parameters:

e - The exception that occurred during execution of a Retryable object.

Returns:

true if a retry should occur, otherwise false.

onRetryFailure

protected E onRetryFailure(Exception e,
                           int attemptNo,
                           long delayMs)

Callback to return the Exception instance of type <E> to be thrown in the event of terminal failure of the RetryPolicy execution.

If this method is not overridden, or if it returns null, a RetryFailureException will be thrown instead.

Parameters:

e - The exception that occurred during execution of a Retryable object.

attemptNo - The attempt number on which the exception was thrown.

delayMs - The delay (in milliseconds) from the previous invocation attempt.

Returns:

The Exception instance signifying the terminal failure of the RetryPolicy execution.

run

public final <T> T run(Retryable<T,E> retryable)
                throws E extends Exception

The entrypoint for a Retryable object to be executed. Exceptions in Retryable.retry(RetryPolicy,int) will be considered for retry if the number of maxRetries has not been exceeded, and retryOn(Exception) returns true.

Type Parameters:

T - The type of the result object.

Parameters:

retryable - The Retryable object to run.

Returns:

The resulting value from Retryable.retry(RetryPolicy,int).

Throws:

RetryFailureException - If retry attempts have exceeded maxRetries, or if retryOn(Exception) returns false.

NullPointerException - If retryable is null.

E extends Exception

run

public final <T> T run(Retryable<T,E> retryable,
                       long timeout)
                throws E extends Exception

The entrypoint for a Retryable object to be executed. Exceptions in Retryable.retry(RetryPolicy,int) will be considered for retry if the number of maxRetries has not been exceeded, and retryOn(Exception) returns true.

Type Parameters:

T - The type of the result object.

Parameters:

retryable - The Retryable object to run.

timeout - The maximum time to retry in milliseconds.

Returns:

The resulting value from Retryable.retry(RetryPolicy,int).

Throws:

RetryFailureException - If retry attempts have exceeded maxRetries, if retryOn(Exception) returns false, or if timeout is exceeded.

IllegalArgumentException - If timeout is negative.

NullPointerException - If the value of timeout is negative.

E extends Exception

onRetry

protected void onRetry(int attemptNo)

Method that is called before each execution of Retryable.retry(RetryPolicy,int).

Runtime exceptions thrown from this method will result in the termination of the RetryPolicy execution.

Parameters:

attemptNo - The next attempt number.

getMaxRetries

public int getMaxRetries()

Returns the number of retry attempts allowed by this RetryPolicy.

Returns:

The number of retry attempts allowed by this RetryPolicy.

getDelayMs

protected abstract long getDelayMs(int attemptNo)

Returns the delay in milliseconds for the specified attempt number. This method is intended to be implemented by a subclass to define the backoff function for retry attempts.

Parameters:

attemptNo - The attempt number, starting with 1.

Returns:

The delay in milliseconds for the specified attempt number.