CircuitBreaker (Failsafe 2.4.4 API)

java.lang.Object
- net.jodah.failsafe.PolicyListeners<S,R>
- - net.jodah.failsafe.FailurePolicy<S,R>
  - - net.jodah.failsafe.DelayablePolicy<CircuitBreaker<R>,R>
    - - net.jodah.failsafe.CircuitBreaker<R>

Type Parameters:

R - result type

All Implemented Interfaces:

Policy<R>
```
public class CircuitBreaker<R>
extends DelayablePolicy<CircuitBreaker<R>,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. A count based circuit breaker will transition between states when recent execution results exceed a threshold. A time based circuit breaker 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.

Note: CircuitBreaker extends DelayablePolicy, FailurePolicy, and PolicyListeners which offer additional configuration.

See Also:

CircuitBreakerOpenException

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class CircuitBreaker.State
The state of the circuit.

Nested Classes
Modifier and Type	Class and Description
`static class`	`CircuitBreaker.State` The state of the circuit.

Constructor Summary

Constructors
Constructor and Description
`CircuitBreaker()` Creates a count based circuit breaker that opens after a `single failure`, closes after a `single success`, and has a 1 minute `delay` by default.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`allowsExecution()` Returns whether the circuit allows execution and triggers a state transition if a threshold has been exceeded.
`void`	`close()` Closes the circuit.
`Duration`	`getDelay()` Returns the delay before allowing another execution on the circuit.
`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`	`getFailureExecutionThreshold()` Used with time based thresholding.
`int`	`getFailureRate()` The percentage rate of failed executions, from 0 to 100, in the current state when the state is CLOSED or HALF_OPEN.
`int`	`getFailureRateThreshold()` Used with time based thresholding.
`int`	`getFailureThreshold()` Gets the number of successive failures that must occur within the `failure thresholding capacity` when in a CLOSED or HALF_OPEN state in order to open the circuit.
`int`	`getFailureThresholdingCapacity()` Returns the rolling capacity for storing execution results when performing failure thresholding in the CLOSED or HALF_OPEN states.
`Duration`	`getFailureThresholdingPeriod()` Used with time based thresholding.
`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.
`int`	`getSuccessThreshold()` Gets the number of successive successes that must occur within the `success thresholding capacity` when in a HALF_OPEN state in order to open the circuit.
`int`	`getSuccessThresholdingCapacity()` Returns the rolling capacity for storing execution results when performing success thresholding in the HALF_OPEN state.
`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.
`CircuitBreaker<R>`	`onClose(CheckedRunnable runnable)` Calls the `runnable` when the circuit is closed.
`CircuitBreaker<R>`	`onHalfOpen(CheckedRunnable runnable)` Calls the `runnable` when the circuit is half-opened.
`CircuitBreaker<R>`	`onOpen(CheckedRunnable runnable)` Calls the `runnable` when the circuit is opened.
`void`	`open()` Opens the circuit.
`void`	`preExecute()` Records an execution that is about to take place by incrementing the internal executions count.
`void`	`recordFailure()` Records an execution failure.
`void`	`recordFailure(Throwable failure)` Records an execution `failure` as a success or failure based on the failure configuration as determined by `#isFailure(R, Throwable)`.
`void`	`recordResult(R result)` Records an execution `result` as a success or failure based on the failure configuration as determined by `#isFailure(R, Throwable)`.
`void`	`recordSuccess()` Records an execution success.
`PolicyExecutor`	`toExecutor(AbstractExecution execution)` Returns an `PolicyExecutor` capable of performing an execution in the context of a Policy and handling results according to the Policy.
`String`	`toString()`
`CircuitBreaker<R>`	`withDelay(Duration delay)` Sets the `delay` to wait in OPEN state before transitioning to half-open.
`CircuitBreaker<R>`	`withFailureRateThreshold(int failureRateThreshold, int failureExecutionThreshold, Duration failureThresholdingPeriod)` Configures time based failure rate thresholding by setting the percentage rate of failures, from 1 to 100, that must occur within the rolling `failureThresholdingPeriod` when in a CLOSED state in order to open the circuit.
`CircuitBreaker<R>`	`withFailureThreshold(int failureThreshold)` Configures count based failure thresholding by setting the number of consecutive failures that must occur when in a CLOSED state in order to open the circuit.
`CircuitBreaker<R>`	`withFailureThreshold(int failureThreshold, Duration failureThresholdingPeriod)` Configures time based failure thresholding by setting the number of failures that must occur within the `failureThresholdingPeriod` when in a CLOSED state in order to open the circuit.
`CircuitBreaker<R>`	`withFailureThreshold(int failureThreshold, int failureThresholdingCapacity)` Configures count based failure thresholding by setting the ratio of successive failures to executions that must occur when in a CLOSED state in order to open the circuit.
`CircuitBreaker<R>`	`withFailureThreshold(int failureThreshold, int failureExecutionThreshold, Duration failureThresholdingPeriod)` Configures time based failure thresholding by setting the number of failures that must occur within the `failureThresholdingPeriod` when in a CLOSED state in order to open the circuit.
`CircuitBreaker<R>`	`withSuccessThreshold(int successThreshold)` Configures count based success thresholding by setting the number of consecutive successful executions that must occur when in a HALF_OPEN state in order to close the circuit, else the circuit is re-opened when a failure occurs.
`CircuitBreaker<R>`	`withSuccessThreshold(int successThreshold, int successThresholdingCapacity)` Configures count based success thresholding by setting the ratio of successive successful executions that must occur when in a HALF_OPEN state in order to close the circuit.

Methods inherited from class net.jodah.failsafe.DelayablePolicy
computeDelay, getDelayFn, withDelay, withDelayOn, withDelayWhen

Methods inherited from class net.jodah.failsafe.FailurePolicy
handle, handle, handle, handleIf, handleIf, handleResult, handleResultIf, isFailure

Methods inherited from class net.jodah.failsafe.PolicyListeners
onFailure, onSuccess

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - CircuitBreaker
```
public CircuitBreaker()
```
    Creates a count based circuit breaker that opens after a single failure, closes after a single success, and has a 1 minute delay by default.
- Method Detail
  - allowsExecution
```
public boolean allowsExecution()
```
    Returns whether the circuit allows execution and triggers a state transition if a threshold has been exceeded.
  - close
```
public void close()
```
    Closes the circuit.
  - getState
```
public CircuitBreaker.State getState()
```
    Gets the state of the circuit.
  - getDelay
```
public Duration getDelay()
```
    Returns the delay before allowing another execution on the circuit. Defaults to 1 minute.
    
    See Also:
    
    withDelay(Duration), getRemainingDelay()
  - getExecutionCount
```
public 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
```
public 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
```
public 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.
  - getFailureThresholdingCapacity
```
public int getFailureThresholdingCapacity()
```
    Returns the rolling capacity for storing execution results when performing failure thresholding in the CLOSED or HALF_OPEN states. 1 by default. Only the most recent executions that fit within this capacity contribute to thresholding decisions.
    
    See Also:
    
    withFailureThreshold(int), withFailureThreshold(int, int)
  - getFailureThresholdingPeriod
```
public Duration getFailureThresholdingPeriod()
```
    Used with time based thresholding. Returns the rolling time period during which failure thresholding is performed when in the CLOSED state, else null if time based failure thresholding is not configured. Only the most recent executions that occurred within this rolling time period contribute to thresholding decisions.
    
    See Also:
    
    withFailureThreshold(int, Duration), withFailureThreshold(int, int, Duration), withFailureRateThreshold(int, int, Duration)
  - getFailureExecutionThreshold
```
public int getFailureExecutionThreshold()
```
    Used with time based thresholding. Returns the minimum number of executions that must be recorded in the CLOSED state before the breaker can be opened. For failure rate thresholding this also determines the minimum number of executions that must be recorded in the HALF_OPEN state. Returns 0 by default.
    
    See Also:
    
    withFailureThreshold(int, int, Duration), withFailureRateThreshold(int, int, Duration)
  - getFailureRate
```
public 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.
  - getFailureRateThreshold
```
public int getFailureRateThreshold()
```
    Used with time based thresholding. Returns percentage rate of failures, from 1 to 100, that must occur when in a CLOSED or HALF_OPEN state in order to open the circuit, else 0 if failure rate thresholding is not configured.
    
    See Also:
    
    withFailureRateThreshold(int, int, Duration)
  - getFailureThreshold
```
public int getFailureThreshold()
```
    Gets the number of successive failures that must occur within the failure thresholding capacity when in a CLOSED or HALF_OPEN state in order to open the circuit. Returns 1 by default.
    
    See Also:
    
    withFailureThreshold(int), withFailureThreshold(int, int)
  - getSuccessCount
```
public 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.
  - getSuccessThresholdingCapacity
```
public int getSuccessThresholdingCapacity()
```
    Returns the rolling capacity for storing execution results when performing success thresholding in the HALF_OPEN state. Only the most recent executions that fit within this capacity contribute to thresholding decisions.
    
    See Also:
    
    withSuccessThreshold(int), withSuccessThreshold(int, int)
  - getSuccessRate
```
public 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.
  - getSuccessThreshold
```
public int getSuccessThreshold()
```
    Gets the number of successive successes that must occur within the success thresholding capacity when in a HALF_OPEN state in order to open the circuit. Returns 0 by default, in which case the failure threshold is used instead.
    
    See Also:
    
    withSuccessThreshold(int), withSuccessThreshold(int, int)
  - halfOpen
```
public void halfOpen()
```
    Half-opens the circuit.
  - isClosed
```
public boolean isClosed()
```
    Returns whether the circuit is closed.
  - isHalfOpen
```
public boolean isHalfOpen()
```
    Returns whether the circuit is half open.
  - isOpen
```
public boolean isOpen()
```
    Returns whether the circuit is open.
  - onClose
```
public CircuitBreaker<R> onClose(CheckedRunnable runnable)
```
    Calls the runnable when the circuit is closed.
    Note: Any exceptions that are thrown from within the runnable are ignored.
  - onHalfOpen
```
public CircuitBreaker<R> onHalfOpen(CheckedRunnable runnable)
```
    Calls the runnable when the circuit is half-opened.
    Note: Any exceptions that are thrown within the runnable are ignored.
  - onOpen
```
public CircuitBreaker<R> onOpen(CheckedRunnable runnable)
```
    Calls the runnable when the circuit is opened.
    Note: Any exceptions that are thrown within the runnable are ignored.
  - open
```
public void open()
```
    Opens the circuit.
  - preExecute
```
public void preExecute()
```
    Records an execution that is about to take place by incrementing the internal executions count. Required for standalone CircuitBreaker usage.
  - recordFailure
```
public void recordFailure()
```
    Records an execution failure.
  - recordFailure
```
public void recordFailure(Throwable failure)
```
    Records an execution failure as a success or failure based on the failure configuration as determined by #isFailure(R, Throwable).
    
    See Also:
    
    #isFailure(R, Throwable)
  - recordResult
```
public void recordResult(R result)
```
    Records an execution result as a success or failure based on the failure configuration as determined by #isFailure(R, Throwable).
    
    See Also:
    
    #isFailure(R, Throwable)
  - recordSuccess
```
public void recordSuccess()
```
    Records an execution success.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - withDelay
```
public CircuitBreaker<R> withDelay(Duration delay)
```
    Sets the delay to wait in OPEN state before transitioning to half-open.
    
    Throws:
    
    NullPointerException - if delay is null
    
    IllegalArgumentException - if delay < 0
  - withFailureThreshold
```
public CircuitBreaker<R> withFailureThreshold(int failureThreshold)
```
    Configures count based failure thresholding by setting the number of consecutive failures that must occur when in a CLOSED state in order to open the circuit.
    If a success threshold is not configured, the failureThreshold will also be used when the circuit breaker is in a HALF_OPEN state to determine whether to transition back to OPEN or CLOSED.
    
    Parameters:
    
    failureThreshold - The number of consecutive failures that must occur in order to open the circuit
    
    Throws:
    
    IllegalArgumentException - if failureThreshold < 1
    
    See Also:
    
    getFailureThreshold()
  - withFailureThreshold
```
public CircuitBreaker<R> withFailureThreshold(int failureThreshold,
                                              int failureThresholdingCapacity)
```
    Configures count based failure thresholding by setting the ratio of successive failures to executions that must occur when in a CLOSED state in order to open the circuit. For example: 5, 10 would open the circuit if 5 out of the last 10 executions result in a failure.
    If a success threshold is not configured, the failureThreshold and failureThresholdingCapacity will also be used when the circuit breaker is in a HALF_OPEN state to determine whether to transition back to OPEN or CLOSED.
    
    Parameters:
    
    failureThreshold - The number of failures that must occur in order to open the circuit
    
    failureThresholdingCapacity - The capacity for storing execution results when performing failure thresholding
    
    Throws:
    
    IllegalArgumentException - if failureThreshold < 1, failureThresholdingCapacity < 1, or failureThreshold > failureThresholdingCapacity
    
    See Also:
    
    getFailureThreshold(), getFailureExecutionThreshold()
  - withFailureThreshold
```
public CircuitBreaker<R> withFailureThreshold(int failureThreshold,
                                              Duration failureThresholdingPeriod)
```
    Configures time based failure thresholding by setting the number of failures that must occur within the failureThresholdingPeriod when in a CLOSED state in order to open the circuit.
    If a success threshold is not configured, the failureThreshold will also be used when the circuit breaker is in a HALF_OPEN state to determine whether to transition back to OPEN or CLOSED.
    
    Parameters:
    
    failureThreshold - The number of failures that must occur within the failureThresholdingPeriod in order to open the circuit
    
    failureThresholdingPeriod - The period during which failures are compared to the failureThreshold
    
    Throws:
    
    NullPointerException - if failureThresholdingPeriod is null
    
    IllegalArgumentException - if failureThreshold < 1 or failureThresholdingPeriod < 10 ms
    
    See Also:
    
    getFailureThreshold(), getFailureThresholdingPeriod()
  - withFailureThreshold
```
public CircuitBreaker<R> withFailureThreshold(int failureThreshold,
                                              int failureExecutionThreshold,
                                              Duration failureThresholdingPeriod)
```
    Configures time based failure thresholding by setting the number of failures that must occur within the failureThresholdingPeriod when in a CLOSED state in order to open the circuit. The number of executions must also exceed the failureExecutionThreshold within the failureThresholdingPeriod when in the CLOSED state before the circuit can be opened.
    If a success threshold is not configured, the failureThreshold will also be used when the circuit breaker is in a HALF_OPEN state to determine whether to transition back to OPEN or CLOSED.
    
    Parameters:
    
    failureThreshold - The number of failures that must occur within the failureThresholdingPeriod in order to open the circuit
    
    failureExecutionThreshold - The minimum number of executions that must occur within the failureThresholdingPeriod when in the CLOSED state before the circuit can be opened
    
    failureThresholdingPeriod - The period during which failures are compared to the failureThreshold
    
    Throws:
    
    NullPointerException - if failureThresholdingPeriod is null
    
    IllegalArgumentException - if failureThreshold < 1, failureExecutionThreshold < 1, failureThreshold > failureExecutionThreshold, or failureThresholdingPeriod < 10 ms
    
    See Also:
    
    getFailureThreshold(), getFailureExecutionThreshold(), getFailureThresholdingPeriod()
  - withFailureRateThreshold
```
public CircuitBreaker<R> withFailureRateThreshold(int failureRateThreshold,
                                                  int failureExecutionThreshold,
                                                  Duration failureThresholdingPeriod)
```
    Configures time based failure rate thresholding by setting the percentage rate of failures, from 1 to 100, that must occur within the rolling failureThresholdingPeriod when in a CLOSED state in order to open the circuit. The number of executions must also exceed the failureExecutionThreshold within the failureThresholdingPeriod before the circuit can be opened.
    If a success threshold is not configured, the failureExecutionThreshold will also be used when the circuit breaker is in a HALF_OPEN state to determine whether to transition back to open or closed.
    
    Parameters:
    
    failureRateThreshold - The percentage rate of failures, from 1 to 100, that must occur in order to open the circuit
    
    failureExecutionThreshold - The minimum number of executions that must occur within the failureThresholdingPeriod when in the CLOSED state before the circuit can be opened, or in the HALF_OPEN state before it can be re-opened or closed
    
    failureThresholdingPeriod - The period during which failures are compared to the failureThreshold
    
    Throws:
    
    NullPointerException - if failureThresholdingPeriod is null
    
    IllegalArgumentException - if failureRateThreshold < 1 or > 100, failureExecutionThreshold < 1, or failureThresholdingPeriod < 10 ms
    
    See Also:
    
    getFailureRateThreshold(), getFailureExecutionThreshold(), getFailureThresholdingPeriod()
  - withSuccessThreshold
```
public CircuitBreaker<R> withSuccessThreshold(int successThreshold)
```
    Configures count based success thresholding by setting the number of consecutive successful executions that must occur when in a HALF_OPEN state in order to close the circuit, else the circuit is re-opened when a failure occurs.
    
    Parameters:
    
    successThreshold - The number of consecutive successful executions that must occur in order to open the circuit
    
    Throws:
    
    IllegalArgumentException - if successThreshold < 1
    
    See Also:
    
    getSuccessThreshold()
  - withSuccessThreshold
```
public CircuitBreaker<R> withSuccessThreshold(int successThreshold,
                                              int successThresholdingCapacity)
```
    Configures count based success thresholding by setting the ratio of successive successful executions that must occur when in a HALF_OPEN state in order to close the circuit. For example: 5, 10 would close the circuit if 5 out of the last 10 executions were successful.
    
    Parameters:
    
    successThreshold - The number of successful executions that must occur in order to open the circuit
    
    successThresholdingCapacity - The capacity for storing execution results when performing success thresholding
    
    Throws:
    
    IllegalArgumentException - if successThreshold < 1, successThresholdingCapacity < 1, or successThreshold > successThresholdingCapacity
    
    See Also:
    
    getSuccessThreshold(), getSuccessThresholdingCapacity()
  - toExecutor
```
public PolicyExecutor toExecutor(AbstractExecution execution)
```
    Description copied from interface: Policy
    
    Returns an PolicyExecutor capable of performing an execution in the context of a Policy and handling results according to the Policy.

Class CircuitBreaker<R>

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class net.jodah.failsafe.DelayablePolicy

Methods inherited from class net.jodah.failsafe.FailurePolicy

Methods inherited from class net.jodah.failsafe.PolicyListeners

Methods inherited from class java.lang.Object

Constructor Detail

CircuitBreaker

Method Detail

allowsExecution

close

getState

getDelay

getExecutionCount

getRemainingDelay

getFailureCount

getFailureThresholdingCapacity

getFailureThresholdingPeriod

getFailureExecutionThreshold

getFailureRate

getFailureRateThreshold

getFailureThreshold

getSuccessCount

getSuccessThresholdingCapacity

getSuccessRate

getSuccessThreshold

halfOpen

isClosed

isHalfOpen

isOpen

onClose

onHalfOpen

onOpen

open

preExecute

recordFailure

recordFailure

recordResult

recordSuccess

toString

withDelay

withFailureThreshold

withFailureThreshold

withFailureThreshold

withFailureThreshold

withFailureRateThreshold

withSuccessThreshold

withSuccessThreshold

toExecutor