Interface CircuitBreaker<R>
- Type Parameters:
R
- result type
- All Superinterfaces:
Policy<R>
- All Known Implementing Classes:
CircuitBreakerImpl
Circuit breakers have three states: closed, open, and half-open. When a circuit breaker is in
the closed (initial) state, executions are allowed. If a configurable number
of failures occur, optionally over some time period
, the circuit breaker transitions to the open state. In the open state a circuit
breaker will fail executions with CircuitBreakerOpenException
. After a configurable delay
, the circuit breaker will transition to a
half-open state. In the
half-open state a configurable number
of trial
executions will be allowed, after which the circuit breaker will transition back to closed or open
depending on how many were successful.
A circuit breaker can be count based or time based:
- Count based circuit breakers will transition between states when recent execution results exceed a threshold.
- Time based circuit breakers will transition between states when recent execution results exceed a threshold within a time period.
A minimum number of executions must be performed in order for a state transition to occur. Time based circuit
breakers use a sliding window to aggregate execution results. The window is divided into 10
time slices,
each representing 1/10th of the failureThresholdingPeriod
.
As time progresses, statistics for old time slices are gradually discarded, which smoothes the calculation of
success and failure rates.
This class is threadsafe.
- See Also:
-
Nested Class Summary
Nested Classes -
Method Summary
Modifier and TypeMethodDescriptiondefault void
Attempts to acquire a permit for the circuit breaker and throwsCircuitBreakerOpenException
if a permit could not be acquired.static <R> CircuitBreakerBuilder
<R> builder()
Creates a CircuitBreakerBuilder that by default will build a count based circuit breaker that opens after asingle failure
, closes after asingle success
, and has a 1 minutedelay
, unless configured otherwise.static <R> CircuitBreakerBuilder
<R> builder
(CircuitBreakerConfig<R> config) Creates a new CircuitBreakerBuilder that will be based on theconfig
.void
close()
Closes the circuit.Returns theCircuitBreakerConfig
that the CircuitBreaker was built with.int
Returns the number of executions recorded in the current state when the state is CLOSED or HALF_OPEN.long
Returns the number of failures recorded in the current state when the state is CLOSED or HALF_OPEN.int
The percentage rate of failed executions, from 0 to 100, in the current state when the state is CLOSED or HALF_OPEN.When in the OPEN state, returns the remaining delay until the circuit is half-opened and allows another execution, else returnsDuration.ZERO
.getState()
Gets the state of the circuit.int
Returns the number of successes recorded in the current state when the state is CLOSED or HALF_OPEN.int
The percentage rate of successful executions, from 0 to 100, in the current state when the state is CLOSED or HALF_OPEN.void
halfOpen()
Half-opens the circuit.boolean
isClosed()
Returns whether the circuit is closed.boolean
Returns whether the circuit is half open.boolean
isOpen()
Returns whether the circuit is open.static <R> CircuitBreaker
<R> void
open()
Opens the circuit.void
recordException
(Throwable exception) Records anexception
as a success or failure based on the failure configuration.void
Records an execution failure.void
recordResult
(R result) Records an executionresult
as a success or failure based on the failure configuration.void
Records an execution success.boolean
Tries to acquire a permit to use the circuit breaker and returns whether a permit was acquired.Methods inherited from interface dev.failsafe.Policy
toExecutor
-
Method Details
-
builder
Creates a CircuitBreakerBuilder that by default will build a count based circuit breaker that opens after asingle failure
, closes after asingle success
, and has a 1 minutedelay
, unless configured otherwise.- See Also:
-
builder
Creates a new CircuitBreakerBuilder that will be based on theconfig
. -
ofDefaults
Creates a count based CircuitBreaker that opens after onefailure
, half-opens after a one minutedelay
, and closes after onesuccess
. To configure additional options on a CircuitBreaker, usebuilder()
instead.- See Also:
-
getConfig
CircuitBreakerConfig<R> getConfig()Returns theCircuitBreakerConfig
that the CircuitBreaker was built with. -
acquirePermit
default void acquirePermit()Attempts to acquire a permit for the circuit breaker and throwsCircuitBreakerOpenException
if a permit could not be acquired. Permission will be automatically released when a result or failure is recorded.- Throws:
CircuitBreakerOpenException
- if the circuit breaker is in a half-open state and no permits remain according to the configured success or failure thresholding capacity.- See Also:
-
tryAcquirePermit
boolean tryAcquirePermit()Tries to acquire a permit to use the circuit breaker and returns whether a permit was acquired. Permission will be automatically released when a result or failure is recorded.- See Also:
-
open
void open()Opens the circuit. -
close
void close()Closes the circuit. -
halfOpen
void halfOpen()Half-opens the circuit. -
getState
CircuitBreaker.State getState()Gets the state of the circuit. -
getExecutionCount
int getExecutionCount()Returns the number of executions recorded in the current state when the state is CLOSED or HALF_OPEN. When the state is OPEN, returns the executions recorded during the previous CLOSED state.For count based thresholding, the max number of executions is limited to the execution threshold. For time based thresholds, the number of executions may vary within the thresholding period.
-
getRemainingDelay
Duration getRemainingDelay()When in the OPEN state, returns the remaining delay until the circuit is half-opened and allows another execution, else returnsDuration.ZERO
. -
getFailureCount
long getFailureCount()Returns the number of failures recorded in the current state when the state is CLOSED or HALF_OPEN. When the state is OPEN, returns the failures recorded during the previous CLOSED state.For count based thresholds, the max number of failures is based on the
failure threshold
. For time based thresholds, the number of failures may vary within thefailure thresholding period
. -
getFailureRate
int getFailureRate()The percentage rate of failed executions, from 0 to 100, in the current state when the state is CLOSED or HALF_OPEN. When the state is OPEN, returns the rate recorded during the previous CLOSED state.The rate is based on the configured
failure thresholding capacity
. -
getSuccessCount
int getSuccessCount()Returns the number of successes recorded in the current state when the state is CLOSED or HALF_OPEN. When the state is OPEN, returns the successes recorded during the previous CLOSED state.The max number of successes is based on the
success threshold
. -
getSuccessRate
int getSuccessRate()The percentage rate of successful executions, from 0 to 100, in the current state when the state is CLOSED or HALF_OPEN. When the state is OPEN, returns the rate recorded during the previous CLOSED state.The rate is based on the configured
success thresholding capacity
. -
isClosed
boolean isClosed()Returns whether the circuit is closed. -
isHalfOpen
boolean isHalfOpen()Returns whether the circuit is half open. -
isOpen
boolean isOpen()Returns whether the circuit is open. -
recordFailure
void recordFailure()Records an execution failure. -
recordException
Records anexception
as a success or failure based on the failure configuration. -
recordResult
Records an executionresult
as a success or failure based on the failure configuration. -
recordSuccess
void recordSuccess()Records an execution success.
-