CircuitBreaker (Failsafe 2.3.1 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 that temporarily halts execution when configurable thresholds are exceeded.
A circuit breaker has 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, 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.

Note: CircuitBreaker extends DelayablePolicy and FailurePolicy 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 Circuit that opens after a single failure, closes after a single success, and has a 1 minute delay by default.

Constructors
Constructor and Description
`CircuitBreaker()` Creates a Circuit 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 Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`allowsExecution()` Returns whether the circuit allows execution, possibly triggering a state transition.
`void`	`close()` Closes the circuit.
`Duration`	`getDelay()` Returns the delay before allowing another execution on the circuit.
`long`	`getFailureCount()` Returns the number of failures recorded in the current state when the state is CLOSED or HALF_OPEN.
`Ratio`	`getFailureRatio()` Returns the ratio of failures to successes in the current state when the state is CLOSED or HALF_OPEN.
`Ratio`	`getFailureThreshold()` Gets the ratio of successive failures that must occur when in a closed state in order to open the circuit else `null` if none has been configured.
`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.
`Ratio`	`getSuccessRatio()` Returns the ratio of successes to failures in the current state when the state is CLOSED or HALF_OPEN.
`Ratio`	`getSuccessThreshold()` Gets the ratio of successive successful executions that must occur when in a half-open state in order to close the circuit else `null` if none has been configured.
`Duration`	`getTimeout()` Deprecated. Use `Timeout` instead
`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>`	`withFailureThreshold(int failureThreshold)` Sets the number of successive failures that must occur when in a closed state in order to open the circuit.
`CircuitBreaker<R>`	`withFailureThreshold(int failures, int executions)` Sets the ratio of successive failures that must occur when in a closed state in order to open the circuit.
`CircuitBreaker<R>`	`withSuccessThreshold(int successThreshold)` Sets the number of successive 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 successes, int executions)` Sets the ratio of successive successful executions that must occur when in a half-open state in order to close the circuit.
`CircuitBreaker<R>`	`withTimeout(Duration timeout)` Deprecated. Use `Timeout` instead

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 Circuit 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, possibly triggering a state transition.
  - close
```
public void close()
```
    Closes the circuit.
  - getDelay
```
public Duration getDelay()
```
    Returns the delay before allowing another execution on the circuit. Defaults to 1 minute.
    
    See Also:
    
    withDelay(Duration)
  - 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. The max number of failures is based on the configured failure threshold.
  - getFailureRatio
```
public Ratio getFailureRatio()
```
    Returns the ratio of failures to successes in the current state when the state is CLOSED or HALF_OPEN. When the state is OPEN, returns the ratio recorded during the previous CLOSED state. The ratio is based on the configured failure threshold.
  - 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 configured success threshold.
  - getSuccessRatio
```
public Ratio getSuccessRatio()
```
    Returns the ratio of successes to failures in the current state when the state is CLOSED or HALF_OPEN. When the state is OPEN, returns the ratio recorded during the previous CLOSED state. The ratio is based on the configured success threshold.
  - getFailureThreshold
```
public Ratio getFailureThreshold()
```
    Gets the ratio of successive failures that must occur when in a closed state in order to open the circuit else null if none has been configured.
    
    See Also:
    
    withFailureThreshold(int), withFailureThreshold(int, int)
  - getState
```
public CircuitBreaker.State getState()
```
    Gets the state of the circuit.
  - getSuccessThreshold
```
public Ratio getSuccessThreshold()
```
    Gets the ratio of successive successful executions that must occur when in a half-open state in order to close the circuit else null if none has been configured.
    
    See Also:
    
    withSuccessThreshold(int), withSuccessThreshold(int, int)
  - getTimeout
```
public Duration getTimeout()
```
    Deprecated. Use Timeout instead
    
    Returns timeout for executions else null if none has been configured.
    
    See Also:
    
    withTimeout(Duration)
  - 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)
```
    Sets the number of successive 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.
    
    Throws:
    
    IllegalArgumentException - if failureThresh < 1
  - withFailureThreshold
```
public CircuitBreaker<R> withFailureThreshold(int failures,
                                              int executions)
```
    Sets the ratio of successive failures 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. The circuit will not be opened until at least the given number of executions have taken place.
    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:
    
    failures - The number of failures that must occur in order to open the circuit
    
    executions - The number of executions to measure the failures against
    
    Throws:
    
    IllegalArgumentException - if failures < 1, executions < 1, or failures is > executions
  - withSuccessThreshold
```
public CircuitBreaker<R> withSuccessThreshold(int successThreshold)
```
    Sets the number of successive 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.
    
    Throws:
    
    IllegalArgumentException - if successThreshold < 1
  - withSuccessThreshold
```
public CircuitBreaker<R> withSuccessThreshold(int successes,
                                              int executions)
```
    Sets 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. The circuit will not be closed until at least the given number of executions have taken place.
    
    Parameters:
    
    successes - The number of successful executions that must occur in order to open the circuit
    
    executions - The number of executions to measure the successes against
    
    Throws:
    
    IllegalArgumentException - if successes < 1, executions < 1, or successes is > executions
  - withTimeout
```
public CircuitBreaker<R> withTimeout(Duration timeout)
```
    Deprecated. Use Timeout instead
    
    Sets the timeout for executions. Executions that exceed this timeout are not interrupted, but are recorded as failures once they naturally complete.
    
    Throws:
    
    NullPointerException - if timeout is null
    
    IllegalArgumentException - if timeout <= 0
  - 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

getDelay

getFailureCount

getFailureRatio

getSuccessCount

getSuccessRatio

getFailureThreshold

getState

getSuccessThreshold

getTimeout

halfOpen

isClosed

isHalfOpen

isOpen

onClose

onHalfOpen

onOpen

open

preExecute

recordFailure

recordFailure

recordResult

recordSuccess

toString

withDelay

withFailureThreshold

withFailureThreshold

withSuccessThreshold

withSuccessThreshold

withTimeout

toExecutor