R
- result typepublic class CircuitBreaker<R> extends DelayablePolicy<CircuitBreaker<R>,R>
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
, FailurePolicy
, and PolicyListeners
which offer
additional configuration.
CircuitBreakerOpenException
Modifier and Type | Class and Description |
---|---|
static class |
CircuitBreaker.State
The state of the circuit.
|
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.
|
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. |
Duration |
getRemainingDelay()
When in the open state, returns the remaining delay until the circuit is half-closed 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.
|
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 consecutive 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 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 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 |
computeDelay, getDelayFn, withDelay, withDelayOn, withDelayWhen
handle, handle, handle, handleIf, handleIf, handleResult, handleResultIf, isFailure
onFailure, onSuccess
public CircuitBreaker()
public boolean allowsExecution()
public void close()
public Duration getDelay()
withDelay(Duration)
,
getRemainingDelay()
public Duration getRemainingDelay()
Duration.ZERO
.public long getFailureCount()
failure threshold
.public Ratio getFailureRatio()
failure threshold
.public int getSuccessCount()
success threshold
.public Ratio getSuccessRatio()
success threshold
.public Ratio getFailureThreshold()
null
if none has been configured.public CircuitBreaker.State getState()
public Ratio getSuccessThreshold()
null
if none has been configured.public Duration getTimeout()
Timeout
insteadnull
if none has been configured.withTimeout(Duration)
public void halfOpen()
public boolean isClosed()
public boolean isHalfOpen()
public boolean isOpen()
public CircuitBreaker<R> onClose(CheckedRunnable runnable)
runnable
when the circuit is closed.
Note: Any exceptions that are thrown from within the runnable
are ignored.
public CircuitBreaker<R> onHalfOpen(CheckedRunnable runnable)
runnable
when the circuit is half-opened.
Note: Any exceptions that are thrown within the runnable
are ignored.
public CircuitBreaker<R> onOpen(CheckedRunnable runnable)
runnable
when the circuit is opened.
Note: Any exceptions that are thrown within the runnable
are ignored.
public void open()
public void preExecute()
public void recordFailure()
public void recordFailure(Throwable failure)
failure
as a success or failure based on the failure configuration as determined by
#isFailure(R, Throwable)
.#isFailure(R, Throwable)
public void recordResult(R result)
result
as a success or failure based on the failure configuration as determined by
#isFailure(R, Throwable)
.#isFailure(R, Throwable)
public void recordSuccess()
public CircuitBreaker<R> withDelay(Duration delay)
delay
to wait in open state before transitioning to half-open.NullPointerException
- if delay
is nullIllegalArgumentException
- if delay
< 0public CircuitBreaker<R> withFailureThreshold(int failureThreshold)
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.
IllegalArgumentException
- if failureThreshold
< 1public CircuitBreaker<R> withFailureThreshold(int failures, int executions)
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.
failures
- The number of failures that must occur in order to open the circuitexecutions
- The number of executions to measure the failures
againstIllegalArgumentException
- if failures
< 1, executions
< 1, or failures
is > executions
public CircuitBreaker<R> withSuccessThreshold(int successThreshold)
IllegalArgumentException
- if successThreshold
< 1public CircuitBreaker<R> withSuccessThreshold(int successes, int executions)
executions
have taken place.successes
- The number of successful executions that must occur in order to open the circuitexecutions
- The number of executions to measure the successes
againstIllegalArgumentException
- if successes
< 1, executions
< 1, or successes
is > executions
public CircuitBreaker<R> withTimeout(Duration timeout)
Timeout
insteadtimeout
for executions. Executions that exceed this timeout are not interrupted, but are recorded
as failures once they naturally complete.NullPointerException
- if timeout
is nullIllegalArgumentException
- if timeout
<= 0public PolicyExecutor toExecutor(AbstractExecution execution)
Policy
PolicyExecutor
capable of performing an execution in the context of a Policy and handling
results according to the Policy.Copyright © 2020. All rights reserved.