Class FailsafeExecutor<R>
- Type Parameters:
R
- result type
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 Summary
FieldsModifier and TypeFieldDescriptionprivate EventHandler
<R> (package private) final BiConsumer
<ExecutionResult<R>, ExecutionContext<R>> private Executor
private EventHandler
<R> Policies sorted outermost firstprivate Scheduler
private EventHandler
<R> -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate <T> T
call
(ContextualSupplier<T, T> innerSupplier) Calls theinnerSupplier
synchronously, handling results according to the configured policies.private <T> CompletableFuture
<T> callAsync
(Function<FailsafeFuture<T>, Function<AsyncExecutionInternal<T>, CompletableFuture<ExecutionResult<T>>>> innerFn, boolean asyncExecution) Calls the asynchronousinnerFn
via the configured Scheduler, handling results according to the configured policies.private <T> Call
<T> callSync
(ContextualSupplier<T, T> innerSupplier) Returns a Call that calls theinnerSupplier
synchronously, handling results according to the configured policies.<P extends Policy<R>>
FailsafeExecutor<R> compose
(P innerPolicy) Returns a newFailsafeExecutor
that composes the currently configured policies around the giveninnerPolicy
.<T extends R>
Tget
(CheckedSupplier<T> supplier) Executes thesupplier
until a successful result is returned or the configured policies are exceeded.<T extends R>
Tget
(ContextualSupplier<T, T> supplier) Executes thesupplier
until a successful result is returned or the configured policies are exceeded.<T extends R>
CompletableFuture<T> getAsync
(CheckedSupplier<T> supplier) Executes thesupplier
asynchronously until a successful result is returned or the configured policies are exceeded.<T extends R>
CompletableFuture<T> getAsync
(ContextualSupplier<T, T> supplier) Executes thesupplier
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.Returns the currently configured policies.<T extends R>
CompletableFuture<T> getStageAsync
(CheckedSupplier<? extends CompletionStage<T>> supplier) Executes thesupplier
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 thesupplier
asynchronously until the resulting future is successfully completed or the configured policies are exceeded.newCall
(ContextualRunnable<Void> runnable) Returns a call that can execute therunnable
until a successful result is returned or the configured policies are exceeded.newCall
(ContextualSupplier<T, T> supplier) Returns a call that can execute thesupplier
until a successful result is returned or the configured policies are exceeded.onComplete
(EventListener<ExecutionCompletedEvent<R>> listener) Registers thelistener
to be called when an execution is complete.onFailure
(EventListener<ExecutionCompletedEvent<R>> listener) Registers thelistener
to be called when an execution fails.onSuccess
(EventListener<ExecutionCompletedEvent<R>> listener) Registers thelistener
to be called when an execution is successful.void
run
(CheckedRunnable runnable) Executes therunnable
until successful or until the configured policies are exceeded.void
run
(ContextualRunnable<Void> runnable) Executes therunnable
until successful or until the configured policies are exceeded.runAsync
(CheckedRunnable runnable) Executes therunnable
asynchronously until successful or until the configured policies are exceeded.runAsync
(ContextualRunnable<Void> runnable) Executes therunnable
asynchronously until successful or until the configured policies are exceeded.runAsyncExecution
(AsyncRunnable<Void> runnable) This method is intended for integration with asynchronous code.Configures thescheduler
to use for performing asynchronous executions and listener callbacks.Configures theexecutor
to use as a wrapper around executions.with
(ExecutorService executorService) Configures theexecutorService
to use for performing asynchronous executions and listener callbacks.with
(ScheduledExecutorService scheduledExecutorService) Configures thescheduledExecutorService
to use for performing asynchronous executions and listener callbacks.
-
Field Details
-
scheduler
-
executor
-
policies
Policies sorted outermost first -
completeHandler
-
failureHandler
-
successHandler
-
completionHandler
-
-
Constructor Details
-
FailsafeExecutor
- Throws:
IllegalArgumentException
- ifpolicies
is empty
-
-
Method Details
-
getPolicies
Returns the currently configured policies.- See Also:
-
compose
Returns a newFailsafeExecutor
that composes the currently configured policies around the giveninnerPolicy
. For example, consider:Failsafe.with(fallback).compose(retryPolicy).compose(circuitBreaker);
This results in the following internal composition when executing arunnable
orsupplier
and handling its result:Fallback(RetryPolicy(CircuitBreaker(Supplier)))
This means theCircuitBreaker
is first to evaluate theSupplier
's result, then theRetryPolicy
, then theFallback
. 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
- ifinnerPolicy
is null- See Also:
-
get
Executes thesupplier
until a successful result is returned or the configured policies are exceeded.- Throws:
NullPointerException
- if thesupplier
is nullFailsafeException
- if the execution fails with a checked Exception.Throwable.getCause()
can be used to learn the underlying checked exception.
-
get
Executes thesupplier
until a successful result is returned or the configured policies are exceeded.- Throws:
NullPointerException
- if thesupplier
is nullFailsafeException
- if the execution fails with a checked Exception.Throwable.getCause()
can be used to learn the underlying checked exception.
-
newCall
Returns a call that can execute therunnable
until a successful result is returned or the configured policies are exceeded.- Throws:
NullPointerException
- if therunnable
is null
-
newCall
Returns a call that can execute thesupplier
until a successful result is returned or the configured policies are exceeded.- Throws:
NullPointerException
- if thesupplier
is null
-
getAsync
Executes thesupplier
asynchronously until a successful result is returned or the configured policies are exceeded.- Throws:
NullPointerException
- if thesupplier
is nullRejectedExecutionException
- if thesupplier
cannot be scheduled for execution
-
getAsync
Executes thesupplier
asynchronously until a successful result is returned or the configured policies are exceeded.- Throws:
NullPointerException
- if thesupplier
is nullRejectedExecutionException
- if thesupplier
cannot be scheduled for execution
-
getAsyncExecution
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 theAsyncExecution.record
methods which will trigger failure handling, if needed, by the configured policies, else the resultingCompletableFuture
will be completed. Any exception that is thrown from therunnable
will automatically be recorded viaAsyncExecution.recordException(Throwable)
.- Throws:
NullPointerException
- if therunnable
is nullRejectedExecutionException
- if therunnable
cannot be scheduled for execution
-
getStageAsync
public <T extends R> CompletableFuture<T> getStageAsync(CheckedSupplier<? extends CompletionStage<T>> supplier) Executes thesupplier
asynchronously until the resulting future is successfully completed or the configured policies are exceeded.Cancelling the resulting
CompletableFuture
will automatically cancels the suppliedCompletionStage
if it's aFuture
.- Throws:
NullPointerException
- if thesupplier
is nullRejectedExecutionException
- if thesupplier
cannot be scheduled for execution
-
getStageAsync
public <T extends R> CompletableFuture<T> getStageAsync(ContextualSupplier<T, ? extends CompletionStage<T>> supplier) Executes thesupplier
asynchronously until the resulting future is successfully completed or the configured policies are exceeded.Cancelling the resulting
CompletableFuture
will automatically cancels the suppliedCompletionStage
if it's aFuture
.- Throws:
NullPointerException
- if thesupplier
is nullRejectedExecutionException
- if thesupplier
cannot be scheduled for execution
-
run
Executes therunnable
until successful or until the configured policies are exceeded.- Throws:
NullPointerException
- if therunnable
is nullFailsafeException
- if the execution fails with a checked Exception.Throwable.getCause()
can be used to learn the underlying checked exception.
-
run
Executes therunnable
until successful or until the configured policies are exceeded.- Throws:
NullPointerException
- if therunnable
is nullFailsafeException
- if the execution fails with a checked Exception.Throwable.getCause()
can be used to learn the underlying checked exception.
-
runAsync
Executes therunnable
asynchronously until successful or until the configured policies are exceeded.- Throws:
NullPointerException
- if therunnable
is nullRejectedExecutionException
- if therunnable
cannot be scheduled for execution
-
runAsync
Executes therunnable
asynchronously until successful or until the configured policies are exceeded.- Throws:
NullPointerException
- if therunnable
is nullRejectedExecutionException
- if therunnable
cannot be scheduled for execution
-
runAsyncExecution
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 theAsyncExecution.record
methods which will trigger failure handling, if needed, by the configured policies, else the resultingCompletableFuture
will be completed. Any exception that is thrown from therunnable
will automatically be recorded viaAsyncExecution.recordException(Throwable)
.- Throws:
NullPointerException
- if therunnable
is nullRejectedExecutionException
- if therunnable
cannot be scheduled for execution
-
onComplete
Registers thelistener
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
Registers thelistener
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 aFallback
. -
onSuccess
Registers thelistener
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 theonFailure(EventListener)
registered listener is called instead.Note: Any exceptions that are thrown from within the
listener
are ignored. -
with
Configures thescheduledExecutorService
to use for performing asynchronous executions and listener callbacks.Note: The
scheduledExecutorService
should have a core pool size of at least 2 in order fortimeouts
to work.- Throws:
NullPointerException
- ifscheduledExecutorService
is nullIllegalArgumentException
- if thescheduledExecutorService
has a core pool size of less than 2
-
with
Configures theexecutorService
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 theexecutorService
will be used for actual execution.Note: The
executorService
should have a core pool size or parallelism of at least 2 in order fortimeouts
to work.- Throws:
NullPointerException
- ifexecutorService
is null
-
with
Configures theexecutor
to use as a wrapper around executions. If theexecutor
is actually an instance ofExecutorService
, then theexecutor
will be configured viawith(ExecutorService)
instead.The
executor
is responsible for propagating executions. Executions that normally return a result, such asget(CheckedSupplier)
will returnnull
since theExecutor
interface does not support results.The
executor
will not be used forgetStageAsync
calls since those require a returned result.- Throws:
NullPointerException
- ifexecutor
is null
-
with
Configures thescheduler
to use for performing asynchronous executions and listener callbacks.- Throws:
NullPointerException
- ifscheduler
is null
-
call
Calls theinnerSupplier
synchronously, handling results according to the configured policies. -
callSync
Returns a Call that calls theinnerSupplier
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 asynchronousinnerFn
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 theinnerFn
is nullRejectedExecutionException
- if theinnerFn
cannot be scheduled for execution
-