net.jodah.failsafe

Class FailsafeExecutor<R>

java.lang.Object

net.jodah.failsafe.PolicyListeners<FailsafeExecutor<R>,R>

net.jodah.failsafe.FailsafeExecutor<R>

Type Parameters:

R - result type

public class FailsafeExecutor<R>
extends PolicyListeners<FailsafeExecutor<R>,R>

An executor that handles failures according to configured policies. Can be created via Failsafe.with(Policy[]).

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 via the returned CompletableFuture, even those run by a ForkJoinPool or CompletionStage.

Method Summary

Modifier and Type	Method and Description
<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> 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> supplier) Executes the supplier asynchronously until a successful result is returned or the configured policies are exceeded.
<T extends R> CompletableFuture<T>	getAsyncExecution(AsyncSupplier<T> supplier) Executes the supplier asynchronously until a successful result is returned or the configured policies are exceeded.
<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<? 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>	getStageAsyncExecution(AsyncSupplier<? extends CompletionStage<T>> supplier) Executes the supplier asynchronously until the resulting future is successfully completed or the configured policies are exceeded.
FailsafeExecutor<R>	onComplete(CheckedConsumer<? extends ExecutionCompletedEvent<R>> listener) Registers the listener to be called when an execution is complete for all of the configured policies are exceeded.
FailsafeExecutor<R>	onFailure(CheckedConsumer<? extends ExecutionCompletedEvent<R>> listener) Registers the listener to be called when an execution fails.
FailsafeExecutor<R>	onSuccess(CheckedConsumer<? extends 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 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 runnable) Executes the runnable asynchronously until successful or until the configured policies are exceeded.
CompletableFuture<Void>	runAsyncExecution(AsyncRunnable runnable) Executes the runnable asynchronously until successful or until the configured policies are exceeded.
FailsafeExecutor<R>	with(ExecutorService executor) Configures the executor to use for performing asynchronous executions and listener callbacks.
FailsafeExecutor<R>	with(ScheduledExecutorService executor) Configures the executor 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

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 supplier fails with a checked Exception. Throwable.getCause() can be used to learn the checked exception that caused the failure.

TimeoutExceededException - if a configured Timeout is exceeded.

CircuitBreakerOpenException - if a configured CircuitBreaker is open.

get

public <T extends R> T get(ContextualSupplier<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 supplier fails with a checked Exception. Throwable.getCause() can be used to learn the checked exception that caused the failure.

TimeoutExceededException - if a configured Timeout is exceeded.

CircuitBreakerOpenException - if a configured CircuitBreaker is open.

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.

If a configured Timeout is exceeded, the resulting future is completed exceptionally with TimeoutExceededException.

If a configured CircuitBreaker is open, the resulting future is completed exceptionally with CircuitBreakerOpenException.

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> supplier)

Executes the supplier asynchronously until a successful result is returned or the configured policies are exceeded.

If a configured Timeout is exceeded, the resulting future is completed exceptionally with TimeoutExceededException.

If a configured CircuitBreaker is open, the resulting future is completed exceptionally with CircuitBreakerOpenException.

Throws:

NullPointerException - if the supplier is null

RejectedExecutionException - if the supplier cannot be scheduled for execution

getAsyncExecution

public <T extends R> CompletableFuture<T> getAsyncExecution(AsyncSupplier<T> supplier)

Executes the supplier asynchronously until a successful result is returned or the configured policies are exceeded. This method is intended for integration with asynchronous code. Retries must be manually scheduled via one of the AsyncExecution.retry methods.

If a configured Timeout is exceeded, the resulting future is completed exceptionally with TimeoutExceededException.

If a configured CircuitBreaker is open, the resulting future is completed exceptionally with CircuitBreakerOpenException.

Throws:

NullPointerException - if the supplier is null

RejectedExecutionException - if the supplier 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.

If a configured Timeout is exceeded, the resulting future is completed exceptionally with TimeoutExceededException.

If a configured CircuitBreaker is open, the resulting future is completed exceptionally with CircuitBreakerOpenException.

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<? extends CompletionStage<T>> supplier)

Executes the supplier asynchronously until the resulting future is successfully completed or the configured policies are exceeded.

If a configured Timeout is exceeded, the resulting future is completed exceptionally with TimeoutExceededException.

If a configured CircuitBreaker is open, the resulting future is completed exceptionally with CircuitBreakerOpenException.

Throws:

NullPointerException - if the supplier is null

RejectedExecutionException - if the supplier cannot be scheduled for execution

getStageAsyncExecution

public <T extends R> CompletableFuture<T> getStageAsyncExecution(AsyncSupplier<? extends CompletionStage<T>> supplier)

Executes the supplier asynchronously until the resulting future is successfully completed or the configured policies are exceeded. This method is intended for integration with asynchronous code. Retries must be manually scheduled via one of the AsyncExecution.retry methods.

If a configured Timeout is exceeded, the resulting future is completed exceptionally with TimeoutExceededException.

If a configured CircuitBreaker is open, the resulting future is completed exceptionally with CircuitBreakerOpenException.

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 runnable fails with a checked Exception. Throwable.getCause() can be used to learn the checked exception that caused the failure.

TimeoutExceededException - if a configured Timeout is exceeded.

CircuitBreakerOpenException - if a configured CircuitBreaker is open.

run

public void run(ContextualRunnable runnable)

Executes the runnable until successful or until the configured policies are exceeded.

Throws:

NullPointerException - if the runnable is null

FailsafeException - if the runnable fails with a checked Exception. Throwable.getCause() can be used to learn the checked exception that caused the failure.

TimeoutExceededException - if a configured Timeout is exceeded.

CircuitBreakerOpenException - if a configured CircuitBreaker is open.

runAsync

public CompletableFuture<Void> runAsync(CheckedRunnable runnable)

Executes the runnable asynchronously until successful or until the configured policies are exceeded.

If a configured Timeout is exceeded, the resulting future is completed exceptionally with TimeoutExceededException.

If a configured CircuitBreaker is open, the resulting future is completed exceptionally with CircuitBreakerOpenException.

Throws:

NullPointerException - if the runnable is null

RejectedExecutionException - if the runnable cannot be scheduled for execution

runAsync

public CompletableFuture<Void> runAsync(ContextualRunnable runnable)

Executes the runnable asynchronously until successful or until the configured policies are exceeded.

If a configured Timeout is exceeded, the resulting future is completed exceptionally with TimeoutExceededException.

If a configured CircuitBreaker is open, the resulting future is completed exceptionally with CircuitBreakerOpenException.

Throws:

NullPointerException - if the runnable is null

RejectedExecutionException - if the runnable cannot be scheduled for execution

runAsyncExecution

public CompletableFuture<Void> runAsyncExecution(AsyncRunnable runnable)

Executes the runnable asynchronously until successful or until the configured policies are exceeded. This method is intended for integration with asynchronous code. Retries must be manually scheduled via one of the AsyncExecution.retry methods.

If a configured Timeout is exceeded, the resulting future is completed exceptionally with TimeoutExceededException.

If a configured CircuitBreaker is open, the resulting future is completed exceptionally with CircuitBreakerOpenException.

Throws:

NullPointerException - if the runnable is null

RejectedExecutionException - if the runnable cannot be scheduled for execution

onComplete

public FailsafeExecutor<R> onComplete(CheckedConsumer<? extends ExecutionCompletedEvent<R>> listener)

Registers the listener to be called when an execution is complete for all of the configured policies are exceeded.

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

onFailure

public FailsafeExecutor<R> onFailure(CheckedConsumer<? extends ExecutionCompletedEvent<R>> listener)

Registers the listener to be called when an execution fails. If multiple policies, are configured, this handler is called when execution is complete and any policy fails.

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

Overrides:

onFailure in class PolicyListeners<FailsafeExecutor<R>,R>

onSuccess

public FailsafeExecutor<R> onSuccess(CheckedConsumer<? extends 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(CheckedConsumer) registered listener is called instead.

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

Overrides:

onSuccess in class PolicyListeners<FailsafeExecutor<R>,R>

with

public FailsafeExecutor<R> with(ScheduledExecutorService executor)

Configures the executor to use for performing asynchronous executions and listener callbacks.

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

Throws:

NullPointerException - if executor is null

IllegalArgumentException - if the executor has a core pool size of less than 2

with

public FailsafeExecutor<R> with(ExecutorService executor)

Configures the executor to use for performing asynchronous executions and listener callbacks. For executions that require a delay, an internal ScheduledExecutorService will be used for the delay, then the executor will be used for actual execution.

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

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