Class Retryer


  • public final class Retryer
    extends java.lang.Object
    Immutable object that retries actions upon exceptions.

    Backoff intervals are configured through chaining upon() calls. It's critical to use the new Retryer instances returned by upon(). Just remember Retryer is immutable.

    If the retried operation still fails after retry, the previous exceptions can be accessed through Throwable.getSuppressed().

    Since:
    2.0
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Retryer.Delay<E>
      Represents a delay upon an event of type E prior to the retry attempt.
      static class  Retryer.ForReturnValue<T>
      Retries based on return values.
    • Constructor Summary

      Constructors 
      Constructor Description
      Retryer()
      Constructs an empty Retryer.
    • Method Summary

      Modifier and Type Method Description
      <T> Retryer.ForReturnValue<T> ifReturns​(java.util.function.Predicate<T> condition, java.util.List<? extends Retryer.Delay<? super T>> delays)
      Returns a new object that retries if the return value satisfies condition.
      <T> Retryer.ForReturnValue<T> ifReturns​(java.util.function.Predicate<T> condition, java.util.stream.Stream<? extends Retryer.Delay<? super T>> delays)
      Returns a new object that retries if the return value satisfies condition.
      <T> java.util.concurrent.CompletionStage<T> retry​(CheckedSupplier<T,​?> supplier, java.util.concurrent.ScheduledExecutorService executor)
      Invokes and possibly retries supplier upon exceptions, according to the retry strategies specified with upon().
      <T> java.util.concurrent.CompletionStage<T> retryAsync​(CheckedSupplier<? extends java.util.concurrent.CompletionStage<T>,​?> asyncSupplier, java.util.concurrent.ScheduledExecutorService executor)
      Invokes and possibly retries asyncSupplier upon exceptions, according to the retry strategies specified with upon().
      <T,​E extends java.lang.Throwable>
      T
      retryBlockingly​(CheckedSupplier<T,​E> supplier)
      Invokes and possibly retries supplier upon exceptions, according to the retry strategies specified with upon().
      <E extends java.lang.Throwable>
      Retryer
      upon​(java.lang.Class<E> exceptionType, java.util.function.Predicate<? super E> condition, java.util.List<? extends Retryer.Delay<? super E>> delays)
      Returns a new Retryer that uses delays when an exception is instance of exceptionType and satisfies condition.
      <E extends java.lang.Throwable>
      Retryer
      upon​(java.lang.Class<E> exceptionType, java.util.function.Predicate<? super E> condition, java.util.stream.Stream<? extends Retryer.Delay<? super E>> delays)
      Returns a new Retryer that uses delays when an exception is instance of exceptionType and satisfies condition.
      <E extends java.lang.Throwable>
      Retryer
      upon​(java.lang.Class<E> exceptionType, java.util.List<? extends Retryer.Delay<? super E>> delays)
      Returns a new Retryer that uses delays when an exception is instance of exceptionType.
      <E extends java.lang.Throwable>
      Retryer
      upon​(java.lang.Class<E> exceptionType, java.util.stream.Stream<? extends Retryer.Delay<? super E>> delays)
      Returns a new Retryer that uses delays when an exception is instance of exceptionType.
      <T> Retryer.ForReturnValue<T> uponReturn​(T returnValue, java.util.List<? extends Retryer.Delay<? super T>> delays)
      Returns a new object that retries if the function returns returnValue.
      <T> Retryer.ForReturnValue<T> uponReturn​(T returnValue, java.util.stream.Stream<? extends Retryer.Delay<? super T>> delays)
      Returns a new object that retries if the function returns returnValue.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Retryer

        public Retryer()
        Constructs an empty Retryer.
    • Method Detail

      • upon

        public final <E extends java.lang.Throwable> Retryer upon​(java.lang.Class<E> exceptionType,
                                                                  java.util.List<? extends Retryer.Delay<? super E>> delays)
        Returns a new Retryer that uses delays when an exception is instance of exceptionType.

        InterruptedException is always considered a request to stop retrying. Calling upon(InterruptedException.class, ...) is illegal.

      • upon

        public final <E extends java.lang.Throwable> Retryer upon​(java.lang.Class<E> exceptionType,
                                                                  java.util.stream.Stream<? extends Retryer.Delay<? super E>> delays)
        Returns a new Retryer that uses delays when an exception is instance of exceptionType.

        InterruptedException is always considered a request to stop retrying. Calling upon(InterruptedException.class, ...) is illegal.

      • upon

        public <E extends java.lang.Throwable> Retryer upon​(java.lang.Class<E> exceptionType,
                                                            java.util.function.Predicate<? super E> condition,
                                                            java.util.List<? extends Retryer.Delay<? super E>> delays)
        Returns a new Retryer that uses delays when an exception is instance of exceptionType and satisfies condition.

        InterruptedException is always considered a request to stop retrying. Calling upon(InterruptedException.class, ...) is illegal.

      • upon

        public <E extends java.lang.Throwable> Retryer upon​(java.lang.Class<E> exceptionType,
                                                            java.util.function.Predicate<? super E> condition,
                                                            java.util.stream.Stream<? extends Retryer.Delay<? super E>> delays)
        Returns a new Retryer that uses delays when an exception is instance of exceptionType and satisfies condition.

        InterruptedException is always considered a request to stop retrying. Calling upon(InterruptedException.class, ...) is illegal.

      • retryBlockingly

        public <T,​E extends java.lang.Throwable> T retryBlockingly​(CheckedSupplier<T,​E> supplier)
                                                                  throws E extends java.lang.Throwable
        Invokes and possibly retries supplier upon exceptions, according to the retry strategies specified with upon().

        This method blocks while waiting to retry. If interrupted, retry is canceled.

        If supplier fails despite retrying, the exception from the most recent invocation is propagated.

        Throws:
        E extends java.lang.Throwable
      • retry

        public <T> java.util.concurrent.CompletionStage<T> retry​(CheckedSupplier<T,​?> supplier,
                                                                 java.util.concurrent.ScheduledExecutorService executor)
        Invokes and possibly retries supplier upon exceptions, according to the retry strategies specified with upon().

        The first invocation is done in the current thread. Unchecked exceptions thrown by supplier directly are propagated unless explicitly configured to retry. This is to avoid hiding programming errors. Checked exceptions are reported through the returned CompletionStage so callers only need to deal with them in one place.

        Retries are scheduled and performed by executor.

        Canceling the returned future object will cancel currently pending retry attempts. Same if supplier throws InterruptedException.

        NOTE that if executor.shutdownNow() is called, the returned CompletionStage will never be done.

      • retryAsync

        public <T> java.util.concurrent.CompletionStage<T> retryAsync​(CheckedSupplier<? extends java.util.concurrent.CompletionStage<T>,​?> asyncSupplier,
                                                                      java.util.concurrent.ScheduledExecutorService executor)
        Invokes and possibly retries asyncSupplier upon exceptions, according to the retry strategies specified with upon().

        The first invocation is done in the current thread. Unchecked exceptions thrown by asyncSupplier directly are propagated unless explicitly configured to retry. This is to avoid hiding programming errors. Checked exceptions are reported through the returned CompletionStage so callers only need to deal with them in one place.

        Retries are scheduled and performed by executor.

        Canceling the returned future object will cancel currently pending retry attempts. Same if supplier throws InterruptedException.

        NOTE that if executor.shutdownNow() is called, the returned CompletionStage will never be done.

      • ifReturns

        public <T> Retryer.ForReturnValue<T> ifReturns​(java.util.function.Predicate<T> condition,
                                                       java.util.List<? extends Retryer.Delay<? super T>> delays)
        Returns a new object that retries if the return value satisfies condition. delays specify the backoffs between retries.
      • ifReturns

        public <T> Retryer.ForReturnValue<T> ifReturns​(java.util.function.Predicate<T> condition,
                                                       java.util.stream.Stream<? extends Retryer.Delay<? super T>> delays)
        Returns a new object that retries if the return value satisfies condition. delays specify the backoffs between retries.
      • uponReturn

        public <T> Retryer.ForReturnValue<T> uponReturn​(T returnValue,
                                                        java.util.stream.Stream<? extends Retryer.Delay<? super T>> delays)
        Returns a new object that retries if the function returns returnValue.
        Parameters:
        returnValue - The nullable return value that triggers retry
        delays - specify the backoffs between retries
      • uponReturn

        public <T> Retryer.ForReturnValue<T> uponReturn​(T returnValue,
                                                        java.util.List<? extends Retryer.Delay<? super T>> delays)
        Returns a new object that retries if the function returns returnValue.
        Parameters:
        returnValue - The nullable return value that triggers retry
        delays - specify the backoffs between retries