Class FailsafeExecutor<R>

java.lang.Object
dev.failsafe.FailsafeExecutor<R>
Type Parameters:
R - result type
public class FailsafeExecutor<R> extends Object

An executor that handles failures according to configured policies. Can be created via Failsafe.with(Policy, Policy[]) to support policy based execution failure handling, or Failsafe.none() to support execution with no failure handling.

Async executions are run by default on the ForkJoinPool.commonPool(). Alternative executors can be configured via with(ScheduledExecutorService) and similar methods. All async executions are cancellable and interruptable via the returned CompletableFuture, even those run by a ForkJoinPool or CompletionStage.

  • Field Details

  • Constructor Details

  • Method Details

    • getPolicies

      public List<? extends Policy<R>> getPolicies()
      Returns the currently configured policies.
      See Also:

    • compose

      public <P extends Policy<R>> FailsafeExecutor<R> compose(P innerPolicy)
      Returns a new FailsafeExecutor that composes the currently configured policies around the given innerPolicy. For example, consider: 

        Failsafe.with(fallback).compose(retryPolicy).compose(circuitBreaker);

      This results in the following internal composition when executing a runnable or supplier and handling its result: 

        Fallback(RetryPolicy(CircuitBreaker(Supplier)))

      This means the CircuitBreaker is first to evaluate the Supplier's result, then the RetryPolicy, then the Fallback. Each policy makes its own determination as to whether the result represents a failure. This allows different policies to be used for handling different types of failures.
      Throws:
      NullPointerException - if innerPolicy is null
      See Also:

    • get

      public <T extends R> T get(CheckedSupplier<T> supplier)
      Executes the supplier until a successful result is returned or the configured policies are exceeded.
      Throws:
      NullPointerException - if the supplier is null
      FailsafeException - if the execution fails with a checked Exception. Throwable.getCause() can be used to learn the underlying checked exception.

    • get

      public <T extends R> T get(ContextualSupplier<T,T> supplier)
      Executes the supplier until a successful result is returned or the configured policies are exceeded.
      Throws:
      NullPointerException - if the supplier is null
      FailsafeException - if the execution fails with a checked Exception. Throwable.getCause() can be used to learn the underlying checked exception.

    • newCall

      public Call<Void> newCall(ContextualRunnable<Void> runnable)
      Returns a call that can execute the runnable until a successful result is returned or the configured policies are exceeded.
      Throws:
      NullPointerException - if the runnable is null

    • newCall

      public <T extends R> Call<T> newCall(ContextualSupplier<T,T> supplier)
      Returns a call that can execute the supplier until a successful result is returned or the configured policies are exceeded.
      Throws:
      NullPointerException - if the supplier is null

    • getAsync

      public <T extends R> CompletableFuture<T> getAsync(CheckedSupplier<T> supplier)
      Executes the supplier asynchronously until a successful result is returned or the configured policies are exceeded.
      Throws:
      NullPointerException - if the supplier is null
      RejectedExecutionException - if the supplier cannot be scheduled for execution

    • getAsync

      public <T extends R> CompletableFuture<T> getAsync(ContextualSupplier<T,T> supplier)
      Executes the supplier asynchronously until a successful result is returned or the configured policies are exceeded.
      Throws:
      NullPointerException - if the supplier is null
      RejectedExecutionException - if the supplier cannot be scheduled for execution

    • getAsyncExecution

      public <T extends R> CompletableFuture<T> getAsyncExecution(AsyncRunnable<T> runnable)
      This method is intended for integration with asynchronous code.

      Executes the runnable asynchronously until a successful result is recorded or the configured policies are exceeded. Executions must be recorded via one of the AsyncExecution.record methods which will trigger failure handling, if needed, by the configured policies, else the resulting CompletableFuture will be completed. Any exception that is thrown from the runnable will automatically be recorded via AsyncExecution.recordException(Throwable).

      Throws:
      NullPointerException - if the runnable is null
      RejectedExecutionException - if the runnable cannot be scheduled for execution

    • getStageAsync

      public <T extends R> CompletableFuture<T> getStageAsync(CheckedSupplier<? extends CompletionStage<T>> supplier)
      Executes the supplier asynchronously until the resulting future is successfully completed or the configured policies are exceeded.

      Cancelling the resulting CompletableFuture will automatically cancels the supplied CompletionStage if it's a Future.

      Throws:
      NullPointerException - if the supplier is null
      RejectedExecutionException - if the supplier cannot be scheduled for execution

    • getStageAsync

      public <T extends R> CompletableFuture<T> getStageAsync(ContextualSupplier<T, ? extends CompletionStage<T>> supplier)
      Executes the supplier asynchronously until the resulting future is successfully completed or the configured policies are exceeded.

      Cancelling the resulting CompletableFuture will automatically cancels the supplied CompletionStage if it's a Future.

      Throws:
      NullPointerException - if the supplier is null
      RejectedExecutionException - if the supplier cannot be scheduled for execution

    • run

      public void run(CheckedRunnable runnable)
      Executes the runnable until successful or until the configured policies are exceeded.
      Throws:
      NullPointerException - if the runnable is null
      FailsafeException - if the execution fails with a checked Exception. Throwable.getCause() can be used to learn the underlying checked exception.

    • run

      public void run(ContextualRunnable<Void> runnable)
      Executes the runnable until successful or until the configured policies are exceeded.
      Throws:
      NullPointerException - if the runnable is null
      FailsafeException - if the execution fails with a checked Exception. Throwable.getCause() can be used to learn the underlying checked exception.

    • runAsync

      public CompletableFuture<Void> runAsync(CheckedRunnable runnable)
      Executes the runnable asynchronously until successful or until the configured policies are exceeded.
      Throws:
      NullPointerException - if the runnable is null
      RejectedExecutionException - if the runnable cannot be scheduled for execution

    • runAsync

      public CompletableFuture<Void> runAsync(ContextualRunnable<Void> runnable)
      Executes the runnable asynchronously until successful or until the configured policies are exceeded.
      Throws:
      NullPointerException - if the runnable is null
      RejectedExecutionException - if the runnable cannot be scheduled for execution

    • runAsyncExecution

      public CompletableFuture<Void> runAsyncExecution(AsyncRunnable<Void> runnable)
      This method is intended for integration with asynchronous code.

      Executes the runnable asynchronously until a successful result is recorded or the configured policies are exceeded. Executions must be recorded via one of the AsyncExecution.record methods which will trigger failure handling, if needed, by the configured policies, else the resulting CompletableFuture will be completed. Any exception that is thrown from the runnable will automatically be recorded via AsyncExecution.recordException(Throwable).

      Throws:
      NullPointerException - if the runnable is null
      RejectedExecutionException - if the runnable cannot be scheduled for execution

    • onComplete

      public FailsafeExecutor<R> onComplete(EventListener<ExecutionCompletedEvent<R>> listener)
      Registers the listener to be called when an execution is complete. This occurs when an execution is successful according to all policies, or all policies have been exceeded.

      Note: Any exceptions that are thrown from within the listener are ignored.

    • onFailure

      public FailsafeExecutor<R> onFailure(EventListener<ExecutionCompletedEvent<R>> listener)
      Registers the listener to be called when an execution fails. This occurs when the execution fails according to some policy, and all policies have been exceeded.

      Note: Any exceptions that are thrown from within the listener are ignored. To provide an alternative result for a failed execution, use a Fallback.

    • onSuccess

      public FailsafeExecutor<R> onSuccess(EventListener<ExecutionCompletedEvent<R>> listener)
      Registers the listener to be called when an execution is successful. If multiple policies, are configured, this handler is called when execution is complete and all policies succeed. If all policies do not succeed, then the onFailure(EventListener) registered listener is called instead.

      Note: Any exceptions that are thrown from within the listener are ignored.

    • with

      public FailsafeExecutor<R> with(ScheduledExecutorService scheduledExecutorService)
      Configures the scheduledExecutorService to use for performing asynchronous executions and listener callbacks.

      Note: The scheduledExecutorService should have a core pool size of at least 2 in order for timeouts to work.

      Throws:
      NullPointerException - if scheduledExecutorService is null
      IllegalArgumentException - if the scheduledExecutorService has a core pool size of less than 2

    • with

      public FailsafeExecutor<R> with(ExecutorService executorService)
      Configures the executorService to use for performing asynchronous executions and listener callbacks. For async executions that require a delay, an internal ScheduledExecutorService will be used for the delay, then the executorService will be used for actual execution.

      Note: The executorService should have a core pool size or parallelism of at least 2 in order for timeouts to work.

      Throws:
      NullPointerException - if executorService is null

    • with

      public FailsafeExecutor<R> with(Executor executor)
      Configures the executor to use as a wrapper around executions. If the executor is actually an instance of ExecutorService, then the executor will be configured via with(ExecutorService) instead.

      The executor is responsible for propagating executions. Executions that normally return a result, such as get(CheckedSupplier) will return null since the Executor interface does not support results.

      The executor will not be used for getStageAsync calls since those require a returned result.

      Throws:
      NullPointerException - if executor is null

    • with

      public FailsafeExecutor<R> with(Scheduler scheduler)
      Configures the scheduler to use for performing asynchronous executions and listener callbacks.
      Throws:
      NullPointerException - if scheduler is null

    • call

      private <T> T call(ContextualSupplier<T,T> innerSupplier)
      Calls the innerSupplier synchronously, handling results according to the configured policies.

    • callSync

      private <T> Call<T> callSync(ContextualSupplier<T,T> innerSupplier)
      Returns a Call that calls the innerSupplier synchronously, handling results according to the configured policies.

    • callAsync

      private <T> CompletableFuture<T> callAsync(Function<FailsafeFuture<T>, Function<AsyncExecutionInternal<T>, CompletableFuture<ExecutionResult<T>>>> innerFn, boolean asyncExecution)
      Calls the asynchronous innerFn via the configured Scheduler, handling results according to the configured policies.
      Parameters:
      asyncExecution - whether this is a detached, async execution that must be manually completed
      Throws:
      NullPointerException - if the innerFn is null
      RejectedExecutionException - if the innerFn cannot be scheduled for execution