CircuitBreaker (Failsafe 3.3.1-SNAPSHOT API)

Type Parameters:

R - result type

All Superinterfaces:

Policy<R>
```
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 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:

CircuitBreakerConfig, CircuitBreakerBuilder, CircuitBreakerOpenException

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class CircuitBreaker.State
The state of the circuit.

Nested Classes
Modifier and Type	Interface and 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 and Description
`default void`	`acquirePermit()` Attempts to acquire a permit for the circuit breaker and throws `CircuitBreakerOpenException` 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 a `single failure`, closes after a `single success`, and has a 1 minute `delay`, unless configured otherwise.
`static <R> CircuitBreakerBuilder<R>`	`builder(CircuitBreakerConfig<R> config)` Creates a new CircuitBreakerBuilder that will be based on the `config`.
`void`	`close()` Closes the circuit.
`CircuitBreakerConfig<R>`	`getConfig()` Returns the `CircuitBreakerConfig` 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.
`Duration`	`getRemainingDelay()` When in the OPEN state, returns the remaining delay until the circuit is half-opened and allows another execution, else returns `Duration.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()` Creates a count based CircuitBreaker that opens after a `single failure`, closes after a `single success`, and has a 1 minute `delay` by default.
`void`	`open()` Opens the circuit.
`void`	`recordException(Throwable exception)` Records an `exception` as a success or failure based on the exception configuration.
`void`	`recordFailure()` Records an execution failure.
`void`	`recordResult(R result)` Records an execution `result` 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 a single failure, closes after a single success, and has a 1 minute delay, unless configured otherwise.
    
    See Also:
    
    ofDefaults()
  - builder
```
static <R> CircuitBreakerBuilder<R> builder(CircuitBreakerConfig<R> config)
```
    Creates a new CircuitBreakerBuilder that will be based on the config.
  - ofDefaults
```
static <R> CircuitBreaker<R> ofDefaults()
```
    Creates a count based CircuitBreaker that opens after a single failure, closes after a single success, and has a 1 minute delay by default. To configure additional options on a CircuitBreaker, use builder() instead.
    
    See Also:
    
    builder()
  - getConfig
```
CircuitBreakerConfig<R> getConfig()
```
    Returns the CircuitBreakerConfig that the CircuitBreaker was built with.
    
    Specified by:
    
    getConfig in interface Policy<R>
  - acquirePermit
```
default void acquirePermit()
```
    Attempts to acquire a permit for the circuit breaker and throws CircuitBreakerOpenException 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.
    
    See Also:
    
    recordResult(Object), recordException(Throwable), recordSuccess(), recordFailure()
  - 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 returns Duration.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 the failure 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(Throwable exception)
```
    Records an exception as a success or failure based on the exception configuration.
  - recordResult
```
void recordResult(R result)
```
    Records an execution result as a success or failure based on the failure configuration.
  - recordSuccess
```
void recordSuccess()
```
    Records an execution success.

Interface CircuitBreaker<R>

Nested Class Summary

Method Summary

Methods inherited from interface dev.failsafe.Policy

Method Detail

builder

builder

ofDefaults

getConfig

acquirePermit

tryAcquirePermit

open

close

halfOpen

getState

getExecutionCount

getRemainingDelay

getFailureCount

getFailureRate

getSuccessCount

getSuccessRate

isClosed

isHalfOpen

isOpen

recordFailure

recordException

recordResult

recordSuccess