public interface CircuitBreaker
CircuitBreaker
manages the state of a backend system.
The CircuitBreaker is implemented via a finite state machine with five states: CLOSED, OPEN, HALF_OPEN, DISABLED AND FORCED_OPEN.
The CircuitBreaker does not know anything about the backend's state by itself, but uses the information provided by the decorators via
onSuccess(long)
and onError(long, java.lang.Throwable)
events.
Before communicating with the backend, the permission to do so must be obtained via the method tryAcquirePermission()
.
The state of the CircuitBreaker changes from CLOSED to OPEN when the failure rate is above a (configurable) threshold.
Then, all access to the backend is rejected for a (configurable) time duration. No further calls are permitted.
After the time duration has elapsed, the CircuitBreaker state changes from OPEN to HALF_OPEN and allows a number of calls to see if the backend is still unavailable or has become available again.
If the failure rate is above the configured threshold, the state changes back to OPEN. If the failure rate is below or equal to the threshold, the state changes back to CLOSED.Modifier and Type | Interface and Description |
---|---|
static interface |
CircuitBreaker.EventPublisher
An EventPublisher can be used to register event consumers.
|
static interface |
CircuitBreaker.Metrics |
static class |
CircuitBreaker.State
States of the CircuitBreaker state machine.
|
static class |
CircuitBreaker.StateTransition
State transitions of the CircuitBreaker state machine.
|
Modifier and Type | Method and Description |
---|---|
void |
acquirePermission()
Try to obtain a permission to execute a call.
|
default <T> java.util.concurrent.Callable<T> |
decorateCallable(java.util.concurrent.Callable<T> callable)
Returns a callable which is decorated by a CircuitBreaker.
|
static <T> java.util.concurrent.Callable<T> |
decorateCallable(CircuitBreaker circuitBreaker,
java.util.concurrent.Callable<T> callable)
Returns a callable which is decorated by a CircuitBreaker.
|
default <T> io.vavr.CheckedConsumer<T> |
decorateCheckedConsumer(io.vavr.CheckedConsumer<T> consumer)
Returns a consumer which is decorated by a CircuitBreaker.
|
static <T> io.vavr.CheckedConsumer<T> |
decorateCheckedConsumer(CircuitBreaker circuitBreaker,
io.vavr.CheckedConsumer<T> consumer)
Returns a consumer which is decorated by a CircuitBreaker.
|
static <T,R> io.vavr.CheckedFunction1<T,R> |
decorateCheckedFunction(CircuitBreaker circuitBreaker,
io.vavr.CheckedFunction1<T,R> function)
Returns a function which is decorated by a CircuitBreaker.
|
default io.vavr.CheckedRunnable |
decorateCheckedRunnable(io.vavr.CheckedRunnable runnable)
Returns a runnable which is decorated by a CircuitBreaker.
|
static io.vavr.CheckedRunnable |
decorateCheckedRunnable(CircuitBreaker circuitBreaker,
io.vavr.CheckedRunnable runnable)
Returns a runnable which is decorated by a CircuitBreaker.
|
default <T> io.vavr.CheckedFunction0<T> |
decorateCheckedSupplier(io.vavr.CheckedFunction0<T> checkedSupplier)
Returns a supplier which is decorated by a CircuitBreaker.
|
static <T> io.vavr.CheckedFunction0<T> |
decorateCheckedSupplier(CircuitBreaker circuitBreaker,
io.vavr.CheckedFunction0<T> supplier)
Returns a supplier which is decorated by a CircuitBreaker.
|
static <T> java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> |
decorateCompletionStage(CircuitBreaker circuitBreaker,
java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> supplier)
Returns a supplier which is decorated by a CircuitBreaker.
|
default <T> java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> |
decorateCompletionStage(java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> supplier)
Returns a supplier which is decorated by a CircuitBreaker.
|
static <T> java.util.function.Consumer<T> |
decorateConsumer(CircuitBreaker circuitBreaker,
java.util.function.Consumer<T> consumer)
Returns a consumer which is decorated by a CircuitBreaker.
|
default <T> java.util.function.Consumer<T> |
decorateConsumer(java.util.function.Consumer<T> consumer)
Returns a consumer which is decorated by a CircuitBreaker.
|
static <T,R> java.util.function.Function<T,R> |
decorateFunction(CircuitBreaker circuitBreaker,
java.util.function.Function<T,R> function)
Returns a function which is decorated by a CircuitBreaker.
|
static java.lang.Runnable |
decorateRunnable(CircuitBreaker circuitBreaker,
java.lang.Runnable runnable)
Returns a runnable which is decorated by a CircuitBreaker.
|
default java.lang.Runnable |
decorateRunnable(java.lang.Runnable runnable)
Returns a runnable which is decorated by a CircuitBreaker.
|
static <T> java.util.function.Supplier<T> |
decorateSupplier(CircuitBreaker circuitBreaker,
java.util.function.Supplier<T> supplier)
Returns a supplier which is decorated by a CircuitBreaker.
|
default <T> java.util.function.Supplier<T> |
decorateSupplier(java.util.function.Supplier<T> supplier)
Returns a supplier which is decorated by a CircuitBreaker.
|
default <T> T |
executeCallable(java.util.concurrent.Callable<T> callable)
Decorates and executes the decorated Callable.
|
default void |
executeCheckedRunnable(io.vavr.CheckedRunnable runnable)
Decorates and executes the decorated Runnable.
|
default <T> T |
executeCheckedSupplier(io.vavr.CheckedFunction0<T> checkedSupplier)
Decorates and executes the decorated Supplier.
|
default <T> java.util.concurrent.CompletionStage<T> |
executeCompletionStage(java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> supplier)
Decorates and executes the decorated CompletionStage.
|
default void |
executeRunnable(java.lang.Runnable runnable)
Decorates and executes the decorated Runnable.
|
default <T> T |
executeSupplier(java.util.function.Supplier<T> supplier)
Decorates and executes the decorated Supplier.
|
CircuitBreakerConfig |
getCircuitBreakerConfig()
Returns the CircuitBreakerConfig of this CircuitBreaker.
|
CircuitBreaker.EventPublisher |
getEventPublisher()
Returns an EventPublisher which can be used to register event consumers.
|
CircuitBreaker.Metrics |
getMetrics()
Returns the Metrics of this CircuitBreaker.
|
java.lang.String |
getName()
Returns the name of this CircuitBreaker.
|
CircuitBreaker.State |
getState()
Returns the state of this CircuitBreaker.
|
boolean |
isCallPermitted()
Deprecated.
Use
tryAcquirePermission() ()} instead. |
static CircuitBreaker |
of(java.lang.String name,
CircuitBreakerConfig circuitBreakerConfig)
Creates a CircuitBreaker with a custom CircuitBreaker configuration.
|
static CircuitBreaker |
of(java.lang.String name,
java.util.function.Supplier<CircuitBreakerConfig> circuitBreakerConfigSupplier)
Creates a CircuitBreaker with a custom CircuitBreaker configuration.
|
static CircuitBreaker |
ofDefaults(java.lang.String name)
Creates a CircuitBreaker with a default CircuitBreaker configuration.
|
void |
onError(long durationInNanos,
java.lang.Throwable throwable)
Records a failed call.
|
void |
onSuccess(long durationInNanos)
Records a successful call.
|
void |
releasePermission()
Releases a permission.
|
void |
reset()
Returns the circuit breaker to its original closed state, losing statistics.
|
void |
transitionToClosedState()
Transitions the state machine to CLOSED state.
|
void |
transitionToDisabledState()
Transitions the state machine to a DISABLED state, stopping state transition, metrics and event publishing.
|
void |
transitionToForcedOpenState()
Transitions the state machine to a FORCED_OPEN state, stopping state transition, metrics and event publishing.
|
void |
transitionToHalfOpenState()
Transitions the state machine to HALF_OPEN state.
|
void |
transitionToOpenState()
Transitions the state machine to OPEN state.
|
boolean |
tryAcquirePermission()
Acquires a permission to execute a call, only if one is available at the time of invocation.
|
@Deprecated boolean isCallPermitted()
tryAcquirePermission()
()} instead.boolean tryAcquirePermission()
true
if a permission was acquired and false
otherwisevoid releasePermission()
onSuccess(long)
or onError(long, Throwable)
to signal a completed or failed call.
If the state is HALF_OPEN, the number of allowed test calls is increased by one.void acquirePermission()
CallNotPermittedException
- when CircuitBreaker is OPEN or HALF_OPEN and no further test calls are permitted.void onError(long durationInNanos, java.lang.Throwable throwable)
durationInNanos
- The elapsed time duration of the callthrowable
- The throwable which must be recordedvoid onSuccess(long durationInNanos)
durationInNanos
- The elapsed time duration of the call
This method must be invoked when a call was successful.void reset()
void transitionToClosedState()
void transitionToOpenState()
void transitionToHalfOpenState()
void transitionToDisabledState()
void transitionToForcedOpenState()
java.lang.String getName()
CircuitBreaker.State getState()
CircuitBreakerConfig getCircuitBreakerConfig()
CircuitBreaker.Metrics getMetrics()
CircuitBreaker.EventPublisher getEventPublisher()
default <T> T executeSupplier(java.util.function.Supplier<T> supplier)
T
- the type of results supplied by this suppliersupplier
- the original Supplierdefault <T> java.util.function.Supplier<T> decorateSupplier(java.util.function.Supplier<T> supplier)
T
- the type of results supplied by this suppliersupplier
- the original supplierdefault <T> T executeCallable(java.util.concurrent.Callable<T> callable) throws java.lang.Exception
T
- the result type of callablecallable
- the original Callablejava.lang.Exception
- if unable to compute a resultdefault <T> java.util.concurrent.Callable<T> decorateCallable(java.util.concurrent.Callable<T> callable)
T
- the result type of callablecallable
- the original Callabledefault void executeRunnable(java.lang.Runnable runnable)
runnable
- the original Runnabledefault java.lang.Runnable decorateRunnable(java.lang.Runnable runnable)
runnable
- the original runnabledefault <T> java.util.concurrent.CompletionStage<T> executeCompletionStage(java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> supplier)
T
- the type of results supplied by this suppliersupplier
- the original CompletionStagedefault <T> java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> decorateCompletionStage(java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> supplier)
T
- the type of the returned CompletionStage's resultsupplier
- the original supplierdefault <T> T executeCheckedSupplier(io.vavr.CheckedFunction0<T> checkedSupplier) throws java.lang.Throwable
T
- the type of results supplied by this suppliercheckedSupplier
- the original Supplierjava.lang.Throwable
- if something goes wrong applying this function to the given argumentsdefault <T> io.vavr.CheckedFunction0<T> decorateCheckedSupplier(io.vavr.CheckedFunction0<T> checkedSupplier)
T
- the type of results supplied by this suppliercheckedSupplier
- the original supplierdefault io.vavr.CheckedRunnable decorateCheckedRunnable(io.vavr.CheckedRunnable runnable)
runnable
- the original runnabledefault void executeCheckedRunnable(io.vavr.CheckedRunnable runnable) throws java.lang.Throwable
runnable
- the original runnablejava.lang.Throwable
default <T> java.util.function.Consumer<T> decorateConsumer(java.util.function.Consumer<T> consumer)
T
- the type of the input to the consumerconsumer
- the original consumerdefault <T> io.vavr.CheckedConsumer<T> decorateCheckedConsumer(io.vavr.CheckedConsumer<T> consumer)
T
- the type of the input to the consumerconsumer
- the original consumerstatic <T> io.vavr.CheckedFunction0<T> decorateCheckedSupplier(CircuitBreaker circuitBreaker, io.vavr.CheckedFunction0<T> supplier)
T
- the type of results supplied by this suppliercircuitBreaker
- the CircuitBreakersupplier
- the original supplierstatic <T> java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> decorateCompletionStage(CircuitBreaker circuitBreaker, java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> supplier)
T
- the type of the returned CompletionStage's resultcircuitBreaker
- the CircuitBreakersupplier
- the original supplierstatic io.vavr.CheckedRunnable decorateCheckedRunnable(CircuitBreaker circuitBreaker, io.vavr.CheckedRunnable runnable)
circuitBreaker
- the CircuitBreakerrunnable
- the original runnablestatic <T> java.util.concurrent.Callable<T> decorateCallable(CircuitBreaker circuitBreaker, java.util.concurrent.Callable<T> callable)
T
- the result type of callablecircuitBreaker
- the CircuitBreakercallable
- the original Callablestatic <T> java.util.function.Supplier<T> decorateSupplier(CircuitBreaker circuitBreaker, java.util.function.Supplier<T> supplier)
T
- the type of results supplied by this suppliercircuitBreaker
- the CircuitBreakersupplier
- the original supplierstatic <T> java.util.function.Consumer<T> decorateConsumer(CircuitBreaker circuitBreaker, java.util.function.Consumer<T> consumer)
T
- the type of the input to the consumercircuitBreaker
- the CircuitBreakerconsumer
- the original consumerstatic <T> io.vavr.CheckedConsumer<T> decorateCheckedConsumer(CircuitBreaker circuitBreaker, io.vavr.CheckedConsumer<T> consumer)
T
- the type of the input to the consumercircuitBreaker
- the CircuitBreakerconsumer
- the original consumerstatic java.lang.Runnable decorateRunnable(CircuitBreaker circuitBreaker, java.lang.Runnable runnable)
circuitBreaker
- the CircuitBreakerrunnable
- the original runnablestatic <T,R> java.util.function.Function<T,R> decorateFunction(CircuitBreaker circuitBreaker, java.util.function.Function<T,R> function)
T
- the type of the input to the functionR
- the type of the result of the functioncircuitBreaker
- the CircuitBreakerfunction
- the original functionstatic <T,R> io.vavr.CheckedFunction1<T,R> decorateCheckedFunction(CircuitBreaker circuitBreaker, io.vavr.CheckedFunction1<T,R> function)
T
- the type of the input to the functionR
- the type of the result of the functioncircuitBreaker
- the CircuitBreakerfunction
- the original functionstatic CircuitBreaker ofDefaults(java.lang.String name)
name
- the name of the CircuitBreakerstatic CircuitBreaker of(java.lang.String name, CircuitBreakerConfig circuitBreakerConfig)
name
- the name of the CircuitBreakercircuitBreakerConfig
- a custom CircuitBreaker configurationstatic CircuitBreaker of(java.lang.String name, java.util.function.Supplier<CircuitBreakerConfig> circuitBreakerConfigSupplier)
name
- the name of the CircuitBreakercircuitBreakerConfigSupplier
- a supplier of a custom CircuitBreaker configuration