io.vertx.circuitbreaker

Interface CircuitBreaker

public interface CircuitBreaker

An implementation of the circuit breaker pattern for Vert.x

Author:

Clement Escoffier

Method Summary

Modifier and Type	Method and Description
CircuitBreaker	close() Closes the circuit breaker.
CircuitBreaker	closeHandler(Handler<Void> handler) Sets a Handler invoked when the circuit breaker state switches to close.
static CircuitBreaker	create(String name, Vertx vertx) Creates a new instance of CircuitBreaker, with default options.
static CircuitBreaker	create(String name, Vertx vertx, CircuitBreakerOptions options) Creates a new instance of CircuitBreaker.
<T> Future<T>	execute(Handler<Promise<T>> command) Same as executeWithFallback(Handler, Function) but using the circuit breaker default fallback.
default <T> void	execute(Handler<Promise<T>> command, Handler<AsyncResult<T>> handler) Same as executeWithFallback(Handler, Function) but using the circuit breaker default fallback.
<T> CircuitBreaker	executeAndReport(Promise<T> resultPromise, Handler<Promise<T>> command) Same as executeAndReportWithFallback(Promise, Handler, Function) but using the circuit breaker default fallback.
<T> CircuitBreaker	executeAndReportWithFallback(Promise<T> resultPromise, Handler<Promise<T>> command, Function<Throwable,T> fallback) Executes the given operation with the circuit breaker control.
<T> Future<T>	executeWithFallback(Handler<Promise<T>> command, Function<Throwable,T> fallback) Executes the given operation with the circuit breaker control.
default <T> void	executeWithFallback(Handler<Promise<T>> command, Function<Throwable,T> fallback, Handler<AsyncResult<T>> handler) Same as executeWithFallback(Handler, Function) but using a callback.
long	failureCount()
<T> CircuitBreaker	fallback(Function<Throwable,T> handler) Sets a default Function invoked when the bridge is open to handle the "request", or on failure if CircuitBreakerOptions.isFallbackOnFailure() is enabled.
CircuitBreaker	halfOpenHandler(Handler<Void> handler) Sets a Handler invoked when the circuit breaker state switches to half-open.
String	name()
CircuitBreaker	open() Explicitly opens the circuit.
CircuitBreaker	openHandler(Handler<Void> handler) Sets a Handler invoked when the circuit breaker state switches to open.
CircuitBreaker	reset() Resets the circuit breaker state (number of failure set to 0 and state set to closed).
CircuitBreaker	retryPolicy(Function<Integer,Long> retryPolicy)
CircuitBreakerState	state()

Method Detail

create

static CircuitBreaker create(String name,
                             Vertx vertx,
                             CircuitBreakerOptions options)

Creates a new instance of CircuitBreaker.

Parameters:

name - the name

vertx - the Vert.x instance

options - the configuration option

Returns:

the created instance

create

static CircuitBreaker create(String name,
                             Vertx vertx)

Creates a new instance of CircuitBreaker, with default options.

Parameters:

name - the name

vertx - the Vert.x instance

Returns:

the created instance

close

CircuitBreaker close()

Closes the circuit breaker. It stops sending events on its state on the event bus. This method is not related to the close state of the circuit breaker. To set the circuit breaker in the close state, use reset().

openHandler

CircuitBreaker openHandler(Handler<Void> handler)

Sets a Handler invoked when the circuit breaker state switches to open.

Parameters:

handler - the handler, must not be null

Returns:

the current CircuitBreaker

halfOpenHandler

CircuitBreaker halfOpenHandler(Handler<Void> handler)

Sets a Handler invoked when the circuit breaker state switches to half-open.

Parameters:

handler - the handler, must not be null

Returns:

the current CircuitBreaker

closeHandler

CircuitBreaker closeHandler(Handler<Void> handler)

Sets a Handler invoked when the circuit breaker state switches to close.

Parameters:

handler - the handler, must not be null

Returns:

the current CircuitBreaker

executeWithFallback

<T> Future<T> executeWithFallback(Handler<Promise<T>> command,
                                  Function<Throwable,T> fallback)

Executes the given operation with the circuit breaker control. The operation is generally calling an external system. The operation receives a Promise object as parameter and must call Promise.complete(Object) when the operation has terminated successfully. The operation must also call Promise.fail(Throwable) in case of failure.

The operation is not invoked if the circuit breaker is open, and the given fallback is called immediately. The circuit breaker also monitor the completion of the operation before a configure timeout. The operation is considered as failed if it does not terminate in time.

This method returns a Future object to retrieve the status and result of the operation, with the status being a success or a failure. If the fallback is called, the returned future is successfully completed with the value returned from the fallback. If the fallback throws an exception, the returned future is marked as failed.

Type Parameters:

T - the type of result

Parameters:

command - the operation

fallback - the fallback function. It gets an exception as parameter and returns the fallback result

Returns:

a future object completed when the operation or its fallback completes

executeWithFallback

default <T> void executeWithFallback(Handler<Promise<T>> command,
                                     Function<Throwable,T> fallback,
                                     Handler<AsyncResult<T>> handler)

Same as executeWithFallback(Handler, Function) but using a callback.

Type Parameters:

T - the type of result

Parameters:

command - the operation

fallback - the fallback

handler - the completion handler receiving either the operation result or the fallback result. The parameter is an AsyncResult because if the fallback is not called, the error is passed to the handler.

execute

<T> Future<T> execute(Handler<Promise<T>> command)

Same as executeWithFallback(Handler, Function) but using the circuit breaker default fallback.

Type Parameters:

T - the type of result

Parameters:

command - the operation

Returns:

a future object completed when the operation or its fallback completes

execute

default <T> void execute(Handler<Promise<T>> command,
                         Handler<AsyncResult<T>> handler)

Same as executeWithFallback(Handler, Function) but using the circuit breaker default fallback.

Type Parameters:

T - the type of result

Parameters:

command - the operation

handler - the completion handler receiving either the operation result or the fallback result. The parameter is an AsyncResult because if the fallback is not called, the error is passed to the handler.

executeAndReport

<T> CircuitBreaker executeAndReport(Promise<T> resultPromise,
                                    Handler<Promise<T>> command)

Same as executeAndReportWithFallback(Promise, Handler, Function) but using the circuit breaker default fallback.

Type Parameters:

T - the type of result

Parameters:

resultPromise - the promise on which the operation result is reported

command - the operation

Returns:

the current CircuitBreaker

executeAndReportWithFallback

<T> CircuitBreaker executeAndReportWithFallback(Promise<T> resultPromise,
                                                Handler<Promise<T>> command,
                                                Function<Throwable,T> fallback)

Executes the given operation with the circuit breaker control. The operation is generally calling an external system. The operation receives a Promise object as parameter and must call Promise.complete(Object) when the operation has terminated successfully. The operation must also call Promise.fail(Throwable) in case of failure.

The operation is not invoked if the circuit breaker is open, and the given fallback is called immediately. The circuit breaker also monitor the completion of the operation before a configure timeout. The operation is considered as failed if it does not terminate in time.

Unlike executeWithFallback(Handler, Function), this method does return a Future object, but let the caller pass a Future object on which the result is reported. If the fallback is called, the future is successfully completed with the value returned by the fallback function. If the fallback throws an exception, the future is marked as failed.

Type Parameters:

T - the type of result

Parameters:

resultPromise - the promise on which the operation result is reported

command - the operation

fallback - the fallback function. It gets an exception as parameter and returns the fallback result

Returns:

the current CircuitBreaker

fallback

<T> CircuitBreaker fallback(Function<Throwable,T> handler)

Sets a default Function invoked when the bridge is open to handle the "request", or on failure if CircuitBreakerOptions.isFallbackOnFailure() is enabled.

The function gets the exception as parameter and returns the fallback result.

Parameters:

handler - the handler

Returns:

the current CircuitBreaker

reset

CircuitBreaker reset()

Resets the circuit breaker state (number of failure set to 0 and state set to closed).

Returns:

the current CircuitBreaker

open

CircuitBreaker open()

Explicitly opens the circuit.

Returns:

the current CircuitBreaker

state

CircuitBreakerState state()

Returns:

the current state.

failureCount

long failureCount()

Returns:

the current number of failures.

name

String name()

Returns:

the name of the circuit breaker.

retryPolicy

CircuitBreaker retryPolicy(Function<Integer,Long> retryPolicy)