Top Description Inners Methods
io.github.resilience4j.circuitbreaker

public Interface CircuitBreaker

Known Direct Implementers
io.github.resilience4j.circuitbreaker.internal.CircuitBreakerStateMachine
Imports
io.github.resilience4j.circuitbreaker.event.*, io.github.resilience4j.circuitbreaker.internal.CircuitBreakerStateMachine, io.github.resilience4j.core.EventConsumer, io.github.resilience4j.core.functions.*, java.time.Duration, .Instant, java.util.Arrays, .Map, .Objects, java.util.concurrent.*, java.util.function.Consumer, .Function, .Supplier, java.util.stream.Collectors

A CircuitBreaker instance is thread-safe can be used to decorate multiple requests.

A 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 CircuitBreaker#onSuccess and CircuitBreaker#onError events. Before communicating with the backend, the permission to do so must be obtained via the method CircuitBreaker#tryAcquirePermission().

The state of the CircuitBreaker changes from CLOSED to OPEN when the failure rate is greater than or equal to 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 greater than or equal to 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.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static class
CircuitBreaker.CircuitBreakerFuture<
of return type
T
>

This class decorates future to add CircuitBreaking functionality around invocation.

public static interface
CircuitBreaker.EventPublisher

An EventPublisher can be used to register event consumers.

public static interface
public static enum
CircuitBreaker.State

States of the CircuitBreaker state machine.

public static enum
CircuitBreaker.StateTransition

State transitions of the CircuitBreaker state machine.

Method Summary

Modifier and TypeMethod and Description
public void
acquirePermission()

Try to obtain a permission to execute a call.

public static <
the result type of callable
T
>
Callable<T>

Returns:

a supplier which is decorated by a CircuitBreaker.
decorateCallable
(CircuitBreaker
the CircuitBreaker
circuitBreaker
,
Callable<T>
the original Callable
callable
)

Returns a callable which is decorated by a CircuitBreaker.

public default <
the result type of callable
T
>
Callable<T>

Returns:

a supplier which is decorated by a CircuitBreaker.
decorateCallable
(Callable<T>
the original Callable
callable
)

Returns a callable which is decorated by a CircuitBreaker.

public static <
the type of the input to the consumer
T
>
CheckedConsumer<T>

Returns:

a consumer which is decorated by a CircuitBreaker.
decorateCheckedConsumer
(CircuitBreaker
the CircuitBreaker
circuitBreaker
,
CheckedConsumer<T>
the original consumer
consumer
)

Returns a consumer which is decorated by a CircuitBreaker.

public default <
the type of the input to the consumer
T
>
CheckedConsumer<T>

Returns:

a consumer which is decorated by a CircuitBreaker.
decorateCheckedConsumer
(CheckedConsumer<T>
the original consumer
consumer
)

Returns a consumer which is decorated by a CircuitBreaker.

public static <
the type of the input to the function
T
,
the type of the result of the function
R
>
CheckedFunction<T, R>

Returns:

a function which is decorated by a CircuitBreaker.
decorateCheckedFunction
(CircuitBreaker
the CircuitBreaker
circuitBreaker
,
CheckedFunction<T, R>
the original function
function
)

Returns a function which is decorated by a CircuitBreaker.

public static CheckedRunnable

Returns:

a runnable which is decorated by a CircuitBreaker.
decorateCheckedRunnable
(CircuitBreaker
the CircuitBreaker
circuitBreaker
,
CheckedRunnable
the original runnable
runnable
)

Returns a runnable which is decorated by a CircuitBreaker.

public default CheckedRunnable

Returns:

a runnable which is decorated by a CircuitBreaker.
decorateCheckedRunnable
(CheckedRunnable
the original runnable
runnable
)

Returns a runnable which is decorated by a CircuitBreaker.

public static <
the type of results supplied by this supplier
T
>
CheckedSupplier<T>

Returns:

a supplier which is decorated by a CircuitBreaker.
decorateCheckedSupplier
(CircuitBreaker
the CircuitBreaker
circuitBreaker
,
CheckedSupplier<T>
the original supplier
supplier
)

Returns a supplier which is decorated by a CircuitBreaker.

public default <
the type of results supplied by this supplier
T
>
CheckedSupplier<T>

Returns:

a supplier which is decorated by a CircuitBreaker.
decorateCheckedSupplier
(CheckedSupplier<T>
the original supplier
checkedSupplier
)

Returns a supplier which is decorated by a CircuitBreaker.

public static <
the type of the returned CompletionStage's result
T
>
Supplier<CompletionStage<T>>

Returns:

a supplier which is decorated by a CircuitBreaker.
decorateCompletionStage
(CircuitBreaker
the CircuitBreaker
circuitBreaker
,
Supplier<CompletionStage<T>>
the original supplier
supplier
)

Returns a supplier which is decorated by a CircuitBreaker.

public default <
the type of the returned CompletionStage's result
T
>
Supplier<CompletionStage<T>>

Returns:

a supplier which is decorated by a CircuitBreaker.
decorateCompletionStage
(Supplier<CompletionStage<T>>
the original supplier
supplier
)

Returns a supplier which is decorated by a CircuitBreaker.

public static <
the type of the input to the consumer
T
>
Consumer<T>

Returns:

a consumer which is decorated by a CircuitBreaker.
decorateConsumer
(CircuitBreaker
the CircuitBreaker
circuitBreaker
,
Consumer<T>
the original consumer
consumer
)

Returns a consumer which is decorated by a CircuitBreaker.

public default <
the type of the input to the consumer
T
>
Consumer<T>

Returns:

a consumer which is decorated by a CircuitBreaker.
decorateConsumer
(Consumer<T>
the original consumer
consumer
)

Returns a consumer which is decorated by a CircuitBreaker.

public static <
the type of the input to the function
T
,
the type of the result of the function
R
>
Function<T, R>

Returns:

a function which is decorated by a CircuitBreaker.
decorateFunction
(CircuitBreaker
the CircuitBreaker
circuitBreaker
,
Function<T, R>
the original function
function
)

Returns a function which is decorated by a CircuitBreaker.

public static <
the type of the returned Future's result
T
>
Supplier<Future<T>>

Returns:

a supplier which is decorated by a CircuitBreaker.
decorateFuture
(CircuitBreaker
the CircuitBreaker
circuitBreaker
,
Supplier<Future<T>>
the original supplier
supplier
)

Returns a supplier of type Future which is decorated by a CircuitBreaker.

public default <
the type of the returned CompletionStage's result
T
>
Supplier<Future<T>>

Returns:

a supplier which is decorated by a CircuitBreaker.
decorateFuture
(Supplier<Future<T>>
the original supplier
supplier
)

Returns a supplier of type Future which is decorated by a CircuitBreaker.

public static Runnable

Returns:

a runnable which is decorated by a CircuitBreaker.
decorateRunnable
(CircuitBreaker
the CircuitBreaker
circuitBreaker
,
Runnable
the original runnable
runnable
)

Returns a runnable which is decorated by a CircuitBreaker.

public default Runnable

Returns:

a runnable which is decorated by a CircuitBreaker.
decorateRunnable
(Runnable
the original runnable
runnable
)

Returns a runnable which is decorated by a CircuitBreaker.

public static <
the type of results supplied by this supplier
T
>
Supplier<T>

Returns:

a supplier which is decorated by a CircuitBreaker.
decorateSupplier
(CircuitBreaker
the CircuitBreaker
circuitBreaker
,
Supplier<T>
the original supplier
supplier
)

Returns a supplier which is decorated by a CircuitBreaker.

public default <
the type of results supplied by this supplier
T
>
Supplier<T>

Returns:

a supplier which is decorated by a CircuitBreaker.
decorateSupplier
(Supplier<T>
the original supplier
supplier
)

Returns a supplier which is decorated by a CircuitBreaker.

public default <
the result type of callable
T
>
T

Returns:

the result of the decorated Callable.
executeCallable
(Callable<T>
the original Callable
callable
)

Decorates and executes the decorated Callable.

public default void
executeCheckedRunnable(CheckedRunnable
the original runnable
runnable
)

Decorates and executes the decorated Runnable.

public default <
the type of results supplied by this supplier
T
>
T

Returns:

the result of the decorated Supplier.
executeCheckedSupplier
(CheckedSupplier<T>
the original Supplier
checkedSupplier
)

Decorates and executes the decorated Supplier.

public default <
the type of results supplied by this supplier
T
>
CompletionStage<T>

Returns:

the decorated CompletionStage.
executeCompletionStage
(Supplier<CompletionStage<T>>
the original CompletionStage
supplier
)

Decorates and executes the decorated CompletionStage.

public default void
executeRunnable(Runnable
the original Runnable
runnable
)

Decorates and executes the decorated Runnable.

public default <
the type of results supplied by this supplier
T
>
T

Returns:

the result of the decorated Supplier.
executeSupplier
(Supplier<T>
the original Supplier
supplier
)

Decorates and executes the decorated Supplier.

public CircuitBreakerConfig

Returns:

the CircuitBreakerConfig of this CircuitBreaker
getCircuitBreakerConfig
()

Returns the CircuitBreakerConfig of this CircuitBreaker.

public long

Returns:

current timestamp
getCurrentTimestamp
()

Returns the current time with respect to the CircuitBreaker currentTimeFunction.

public CircuitBreaker.EventPublisher

Returns:

an EventPublisher
getEventPublisher
()

Returns an EventPublisher which can be used to register event consumers.

public CircuitBreaker.Metrics

Returns:

the Metrics of this CircuitBreaker
getMetrics
()

Returns the Metrics of this CircuitBreaker.

public String

Returns:

the name of this CircuitBreaker
getName
()

Returns the name of this CircuitBreaker.

public CircuitBreaker.State

Returns:

the state of this CircuitBreaker
getState
()

Returns the state of this CircuitBreaker.

public Map<String, String>

Returns:

the tags assigned to this CircuitBreaker in an unmodifiable map
getTags
()

Returns an unmodifiable map with tags assigned to this CircuitBreaker.

public TimeUnit

Returns:

the timeUnit of current timestamp
getTimestampUnit
()

Returns the timeUnit of current timestamp.

public static CircuitBreaker

Returns:

a CircuitBreaker with a custom CircuitBreaker configuration.
of
(String
the name of the CircuitBreaker
name
,
CircuitBreakerConfig
a custom CircuitBreaker configuration
circuitBreakerConfig
)

Creates a CircuitBreaker with a custom CircuitBreaker configuration.

public static CircuitBreaker

Returns:

a CircuitBreaker with a custom CircuitBreaker configuration.
of
(String
the name of the CircuitBreaker
name
,
CircuitBreakerConfig
a custom CircuitBreaker configuration
circuitBreakerConfig
,
Map<String, String>
tags added to the CircuitBreaker
tags
)

Creates a CircuitBreaker with a custom CircuitBreaker configuration.

public static CircuitBreaker

Returns:

a CircuitBreaker with a custom CircuitBreaker configuration.
of
(String
the name of the CircuitBreaker
name
,
Supplier<CircuitBreakerConfig>
a supplier of a custom CircuitBreaker configuration
circuitBreakerConfigSupplier
)

Creates a CircuitBreaker with a custom CircuitBreaker configuration.

public static CircuitBreaker

Returns:

a CircuitBreaker with a custom CircuitBreaker configuration.
of
(String
the name of the CircuitBreaker
name
,
Supplier<CircuitBreakerConfig>
a supplier of a custom CircuitBreaker configuration
circuitBreakerConfigSupplier
,
Map<String, String>
tags added to the CircuitBreaker
tags
)

Creates a CircuitBreaker with a custom CircuitBreaker configuration.

public static CircuitBreaker

Returns:

a CircuitBreaker with a default CircuitBreaker configuration.
ofDefaults
(String
the name of the CircuitBreaker
name
)

Creates a CircuitBreaker with a default CircuitBreaker configuration.

public void
onError(long
The elapsed time duration of the call
duration
,
TimeUnit
The duration unit
durationUnit
,
Throwable
The throwable which must be recorded
throwable
)

Records a failed call.

public void
onResult(long
The elapsed time duration of the call
duration
,
TimeUnit
The duration unit
durationUnit
,
Object
The result of the protected function
result
)

This method must be invoked when a call returned a result and the result predicate should decide if the call was successful or not.

public void
onSuccess(long
The elapsed time duration of the call
duration
,
TimeUnit
The duration unit
durationUnit
)

Records a successful call.

public void
releasePermission()

Releases a permission.

public void
reset()

Returns the circuit breaker to its original closed state, losing statistics.

public void
transitionToClosedState()

Transitions the state machine to CLOSED state.

public void
transitionToDisabledState()

Transitions the state machine to a DISABLED state, stopping state transition, metrics and event publishing.

public void
transitionToForcedOpenState()

Transitions the state machine to a FORCED_OPEN state, stopping state transition, metrics and event publishing.

public void
transitionToHalfOpenState()

Transitions the state machine to HALF_OPEN state.

public void
transitionToMetricsOnlyState()

Transitions the state machine to METRICS_ONLY state, stopping all state transitions but continues to capture metrics and publish events.

public void
transitionToOpenState()

Transitions the state machine to OPEN state.

public void
transitionToOpenStateFor(Duration
how long should we wait in open state
waitDuration
)

Same as transitionToOpenState() but waits in open state for the given amount of time instead of relaying on configurations to determine it.

public void
transitionToOpenStateUntil(Instant
how long should we wait in open state
waitUntil
)

Same as transitionToOpenState() but waits in open state until the given in time instead of relaying on configurations to determine it.

public boolean

Returns:

true if a permission was acquired and false otherwise
tryAcquirePermission
()

Acquires a permission to execute a call, only if one is available at the time of invocation.