Package com.norconex.commons.lang.exec

# Class Retrier

java.lang.Object
com.norconex.commons.lang.exec.Retrier

public class Retrier extends Object
This class is responsible for executing `Retriable` instances. Upon reaching the maximum number of retries allowed, it will throw a `RetriableException`, wrapping the last exceptions encountered, if any, to a configurable maximum.

Since:
  1.13.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_MAX_CAUSES_KEPT`
  Default maximum number of exception causes kept.
  `static final int`
  `DEFAULT_MAX_RETRIES`
  Default maximum number of retries.
  `static final long`
  `DEFAULT_RETRY_DELAY`
  Default wait time (milliseconds) before making a new attempt.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Retrier()`
  Creates a new instance with the default maximum retries and default retry delay (no delay).
  `Retrier(int maxRetries)`
  Creates a new instance with the default retry delay (no delay).
  `Retrier(ExceptionFilter exceptionFilter)`
  Creates a new instance which will retry execution only if the exception thrown by an attempt is accepted by the `ExceptionFilter` (up to `maxRetries`).
  `Retrier(ExceptionFilter exceptionFilter, int maxRetries)`
  Creates a new instance which will retry execution only if the exception thrown by an attempt is accepted by the `ExceptionFilter` (up to `maxRetries`).

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected boolean`
  `canEqual(Object other)`
  `boolean`
  `equals(Object o)`
  `<T> T`
  `execute(Retriable<T> retriable)`
  Runs the `Retriable` instance.
  `ExceptionFilter`
  `getExceptionFilter()`
  Sets an exception filter that limits the exceptions eligible for retry.
  `int`
  `getMaxCauses()`
  Gets the maximum number of exception causes to keep when all attempts were made and a `RetriableException` is thrown.
  `int`
  `getMaxRetries()`
  Gets the maximum number of retries (the initial run does not count as a retry).
  `long`
  `getRetryDelay()`
  Gets the delay in milliseconds before attempting to execute again.
  `int`
  `hashCode()`
  `Retrier`
  `setExceptionFilter(ExceptionFilter exceptionFilter)`
  Sets an exception filter that limits the exceptions eligible for retry.
  `Retrier`
  `setMaxCauses(int maxCauses)`
  Sets the maximum number of exception causes to keep when all attempts were made and a `RetriableException` is thrown.
  `Retrier`
  `setMaxRetries(int maxRetries)`
  Sets the maximum number of retries (the initial run does not count as a retry).
  `Retrier`
  `setRetryDelay(long retryDelay)`
  Sets the delay in milliseconds before attempting to execute again.
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### DEFAULT_MAX_RETRIES

    public static final int DEFAULT_MAX_RETRIES
    Default maximum number of retries.
    See Also:
      - Constant Field Values

  - ### DEFAULT_RETRY_DELAY

    public static final long DEFAULT_RETRY_DELAY
    Default wait time (milliseconds) before making a new attempt.
    See Also:
      - Constant Field Values

  - ### DEFAULT_MAX_CAUSES_KEPT

    public static final int DEFAULT_MAX_CAUSES_KEPT
    Default maximum number of exception causes kept.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Retrier

    public Retrier()
    Creates a new instance with the default maximum retries and default retry delay (no delay).

  - ### Retrier

    public Retrier(int maxRetries)
    Creates a new instance with the default retry delay (no delay).
    Parameters:
      `maxRetries` - maximum number of execution retries

  - ### Retrier

    public Retrier(ExceptionFilter exceptionFilter)
    Creates a new instance which will retry execution only if the exception thrown by an attempt is accepted by the `ExceptionFilter` (up to `maxRetries`). Uses the default maximum retries and default retry delay.
    Parameters:
      `exceptionFilter` - exception filter

  - ### Retrier

    public Retrier(ExceptionFilter exceptionFilter, int maxRetries)
    Creates a new instance which will retry execution only if the exception thrown by an attempt is accepted by the `ExceptionFilter` (up to `maxRetries`).
    Parameters:
      `exceptionFilter` - exception filter
      `maxRetries` - maximum number of retries

- ## Method Details

  - ### getMaxRetries

    public int getMaxRetries()
    Gets the maximum number of retries (the initial run does not count as a retry).
    Returns:
      maximum number of retries

  - ### setMaxRetries

    public Retrier setMaxRetries(int maxRetries)
    Sets the maximum number of retries (the initial run does not count as a retry).
    Parameters:
      `maxRetries` - maximum number of retries
    Returns:
      this instance

  - ### getRetryDelay

    public long getRetryDelay()
    Gets the delay in milliseconds before attempting to execute again.
    Returns:
      delay in milliseconds

  - ### setRetryDelay

    public Retrier setRetryDelay(long retryDelay)
    Sets the delay in milliseconds before attempting to execute again.
    Parameters:
      `retryDelay` - delay in milliseconds
    Returns:
      this instance

  - ### getExceptionFilter

    public ExceptionFilter getExceptionFilter()
    Sets an exception filter that limits the exceptions eligible for retry.
    Returns:
      exception filter

  - ### setExceptionFilter

    public Retrier setExceptionFilter(ExceptionFilter exceptionFilter)
    Sets an exception filter that limits the exceptions eligible for retry.
    Parameters:
      `exceptionFilter` - exception filter
    Returns:
      this instance

  - ### getMaxCauses

    public int getMaxCauses()
    Gets the maximum number of exception causes to keep when all attempts were made and a `RetriableException` is thrown.
    Returns:
      max number of causes

  - ### setMaxCauses

    public Retrier setMaxCauses(int maxCauses)
    Sets the maximum number of exception causes to keep when all attempts were made and a `RetriableException` is thrown.
    Parameters:
      `maxCauses` - max number of causes
    Returns:
      this instance

  - ### execute

    public <T> T execute(Retriable<T> retriable) throws RetriableException
    Runs the `Retriable` instance. This method is only thread-safe if not modified after being used for the first time, and the exception filter is thread-safe (or `null`).
    Type Parameters:
      `T` - type of optional return value
    Parameters:
      `retriable` - the code to run
    Returns:
      execution output if any, or null
    Throws:
      `RetriableException` - wrapper around last exception encountered or exception thrown when max rerun attempts is reached.

  - ### equals

    public boolean equals(Object o)
    Overrides:
      `equals` in class `Object`

  - ### canEqual

    protected boolean canEqual(Object other)

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`