Package org.kiwiproject.retry

Class 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 Detail

      • 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 Detail

      • 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 an 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)