Package org.kiwiproject.retry

Class RetryResult<T>

java.lang.Object
org.kiwiproject.retry.RetryResult<T>
Type Parameters:
T - the result type
public class RetryResult<T> extends Object
Defines a result of one or more attempts to get some type of object. The list of errors should reflect the order in which errors occurred, e.g. the first error should be the error for the first attempt, second error should be the error for the second attempt, etc.

A unique identifier is automatically assigned to new RetryResult instances for easy identification, e.g. when logging retry exceptions.

Note that there is nothing precluding a RetryResult from representing a failure but not actually have any errors. This could happen, for example, if retry code executes a Supplier and that supplier is implemented to catch all exceptions and return null to force a retry. We generally recommend to implement Suppliers to throw exceptions when errors occur. They will need to be subclasses of RuntimeException since Supplier doesn't permit checked exceptions, plus we generally prefer unchecked exceptions.

  • Constructor Details

    • RetryResult

      public RetryResult(int numAttemptsMade, int maxAttempts, @Nullable T object, @Nullable List<Exception> errors)
      Create new instance.
      Parameters:
      numAttemptsMade - the number of attempts (must be less than or equal to max attempts)
      maxAttempts - the maximum number of attempts
      object - the result, or null
      errors - a list containing any errors that occurred on attempts, or null or empty list if no errors occurred

  • Method Details

    • succeeded

      public boolean succeeded()
      The result succeeded if this result has an object.
      Returns:
      true if the result object is not null, otherwise false

    • failed

      public boolean failed()
      The result failed if this result does not have an object.
      Returns:
      true if the result object is null, otherwise false

    • hasObject

      public boolean hasObject()
      Does this result have an object that was successfully retrieved before the maximum number of attempts?
      Returns:
      true if the result object is not null, otherwise false

    • getObject

      public T getObject()
      Assumes there is an object and returns it, otherwise throws an exception.

      You should check if an object exists before calling this. Or, consider using getObjectIfPresent().

      Returns:
      the result object
      Throws:
      IllegalStateException - if this result does not have an object

    • getObjectIfPresent

      public Optional<T> getObjectIfPresent()
      Returns an Optional that contains the object if this result was successful, otherwise it will be empty.
      Returns:
      an Optional that may contain a result, or be empty

    • hasMoreThanOneAttempt

      public boolean hasMoreThanOneAttempt()
      Whether more than one attempt was made to retrieve the object.
      Returns:
      true if the number of attempts is more than one

    • hasAnyErrors

      public boolean hasAnyErrors()
      Did any attempts fail with an exception? The overall result can still be successful if an object is obtained before the maximum number of attempts is reached.
      Returns:
      true if there are any errors that occurred (independent of overall success/failure)

    • getNumErrors

      public int getNumErrors()
      The number of failed attempts, which can be zero up to the maximum number of attempts. A number greater than zero does not represent overall failure, however, since a result could have been obtained even if there were errors.
      Returns:
      the number of errors

    • getLastError

      public Exception getLastError()
      Assumes there is at least one error, and returns the last one that was thrown regardless of the number of attempts.

      You should check if there are any errors, e.g. using hasAnyErrors(), before calling this method. Alternatively consider using getLastErrorIfPresent().

      Returns:
      the most recent exception that occurred
      Throws:
      IllegalStateException - if this result does not have any errors

    • getLastErrorIfPresent

      public Optional<Exception> getLastErrorIfPresent()
      Returns an Optional that contains the last error if this result has any errors, otherwise empty.
      Returns:
      an Optional that may contain an error, or be empty

    • getUniqueErrorTypes

      public Set<String> getUniqueErrorTypes()
      Return a set containing the unique error types in this result. There is NO guarantee whatsoever about the order of the unique error types, so don't make any assumptions. That's why the return type is Set.
      Returns:
      set of unique error types (class names)

    • getResultUuid

      public String getResultUuid()

    • getNumAttemptsMade

      public int getNumAttemptsMade()

    • getMaxAttempts

      public int getMaxAttempts()

    • getErrors

      public List<Exception> getErrors()