dev.failsafe

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.

Method Summary

Modifier and Type	Method and Description
<P extends Policy<R>> FailsafeExecutor<R>	compose(P innerPolicy) Returns a new FailsafeExecutor that composes the currently configured policies around the given innerPolicy.
<T extends R> T	get(CheckedSupplier<T> supplier) Executes the supplier until a successful result is returned or the configured policies are exceeded.
<T extends R> T	get(ContextualSupplier<T,T> supplier) Executes the supplier until a successful result is returned or the configured policies are exceeded.
<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.
<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.
<T extends R> CompletableFuture<T>	getAsyncExecution(AsyncRunnable<T> runnable) This method is intended for integration with asynchronous code.
List<? extends Policy<R>>	getPolicies() Returns the currently configured policies.
<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.
<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.
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.
<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.
FailsafeExecutor<R>	onComplete(EventListener<ExecutionCompletedEvent<R>> listener) Registers the listener to be called when an execution is complete.
FailsafeExecutor<R>	onFailure(EventListener<ExecutionCompletedEvent<R>> listener) Registers the listener to be called when an execution fails.
FailsafeExecutor<R>	onSuccess(EventListener<ExecutionCompletedEvent<R>> listener) Registers the listener to be called when an execution is successful.
void	run(CheckedRunnable runnable) Executes the runnable until successful or until the configured policies are exceeded.
void	run(ContextualRunnable<Void> runnable) Executes the runnable until successful or until the configured policies are exceeded.
CompletableFuture<Void>	runAsync(CheckedRunnable runnable) Executes the runnable asynchronously until successful or until the configured policies are exceeded.
CompletableFuture<Void>	runAsync(ContextualRunnable<Void> runnable) Executes the runnable asynchronously until successful or until the configured policies are exceeded.
CompletableFuture<Void>	runAsyncExecution(AsyncRunnable<Void> runnable) This method is intended for integration with asynchronous code.
FailsafeExecutor<R>	with(Executor executor) Configures the executor to use as a wrapper around executions.
FailsafeExecutor<R>	with(ExecutorService executorService) Configures the executorService to use for performing asynchronous executions and listener callbacks.
FailsafeExecutor<R>	with(ScheduledExecutorService scheduledExecutorService) Configures the scheduledExecutorService to use for performing asynchronous executions and listener callbacks.
FailsafeExecutor<R>	with(Scheduler scheduler) Configures the scheduler to use for performing asynchronous executions and listener callbacks.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getPolicies

public List<? extends Policy<R>> getPolicies()

Returns the currently configured policies.

See Also:

compose(Policy)

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:

getPolicies()

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