Interface CircuitBreaker<R>
-
- Type Parameters:
R
- result type
- All Superinterfaces:
Policy<R>
- All Known Implementing Classes:
CircuitBreakerImpl
public interface CircuitBreaker<R> extends Policy<R>
A circuit breaker temporarily blocks execution when a configured number of failures are exceeded.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 sometime period
, the circuit breaker transitions to the open state. In the open state a circuit breaker will fail executions withCircuitBreakerOpenException
. After aconfigurable delay
, the circuit breaker will transition to a half-open state. In the half-open state aconfigurable 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 thefailureThresholdingPeriod
. As time progresses, statistics for old time slices are gradually discarded, which smoothes the calculation of success and failure rates.This class is threadsafe.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
CircuitBreaker.State
The state of the circuit.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default void
acquirePermit()
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.CircuitBreakerConfig<R>
getConfig()
Returns theCircuitBreakerConfig
that the CircuitBreaker was built with.int
getExecutionCount()
Returns the number of executions recorded in the current state when the state is CLOSED or HALF_OPEN.long
getFailureCount()
Returns the number of failures recorded in the current state when the state is CLOSED or HALF_OPEN.int
getFailureRate()
The percentage rate of failed executions, from 0 to 100, in the current state when the state is CLOSED or HALF_OPEN.java.time.Duration
getRemainingDelay()
When in the OPEN state, returns the remaining delay until the circuit is half-opened and allows another execution, else returnsDuration.ZERO
.CircuitBreaker.State
getState()
Gets the state of the circuit.int
getSuccessCount()
Returns the number of successes recorded in the current state when the state is CLOSED or HALF_OPEN.int
getSuccessRate()
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
isHalfOpen()
Returns whether the circuit is half open.boolean
isOpen()
Returns whether the circuit is open.static <R> CircuitBreaker<R>
ofDefaults()
void
open()
Opens the circuit.void
recordException(java.lang.Throwable exception)
Records anexception
as a success or failure based on the failure configuration.void
recordFailure()
Records an execution failure.void
recordResult(R result)
Records an executionresult
as a success or failure based on the failure configuration.void
recordSuccess()
Records an execution success.boolean
tryAcquirePermit()
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 Detail
-
builder
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.- See Also:
ofDefaults()
-
builder
static <R> CircuitBreakerBuilder<R> builder(CircuitBreakerConfig<R> config)
Creates a new CircuitBreakerBuilder that will be based on theconfig
.
-
ofDefaults
static <R> CircuitBreaker<R> 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:
builder()
-
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()
,recordResult(Object)
,recordException(Throwable)
,recordSuccess()
,recordFailure()
-
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.
-
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
java.time.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
void recordException(java.lang.Throwable exception)
Records anexception
as a success or failure based on the failure configuration.
-
recordResult
void recordResult(R result)
Records an executionresult
as a success or failure based on the failure configuration.
-
recordSuccess
void recordSuccess()
Records an execution success.
-
-