Class ThresholdCircuitBreaker

java.lang.Object

org.apache.commons.lang3.concurrent.AbstractCircuitBreaker<Long>

org.apache.commons.lang3.concurrent.ThresholdCircuitBreaker

All Implemented Interfaces:

CircuitBreaker<Long>

public class ThresholdCircuitBreaker
extends AbstractCircuitBreaker<Long>

A simple implementation of the Circuit Breaker pattern that opens if the requested increment amount is greater than a given threshold.

It contains an internal counter that starts in zero, and each call increments the counter by a given amount. If the threshold is zero, the circuit breaker will be in a permanent open state.

An example of use case could be a memory circuit breaker.

long threshold = 10L;
ThresholdCircuitBreaker breaker = new ThresholdCircuitBreaker(10L);
...
public void handleRequest(Request request) {
    long memoryUsed = estimateMemoryUsage(request);
    if (breaker.incrementAndCheckState(memoryUsed)) {
        // actually handle this request
    } else {
        // do something else, e.g. send an error code
    }
}

#Thread safe#

Since:

3.5

Nested Class Summary

Nested classes/interfaces inherited from class AbstractCircuitBreaker

AbstractCircuitBreaker.State

Modifier and Type	Class	Description
protected static enum	AbstractCircuitBreaker.State	Enumerates the different states of a circuit breaker.

Field Summary

Fields inherited from class AbstractCircuitBreaker

PROPERTY_NAME, state

Modifier and Type	Field	Description
static final String	PROPERTY_NAME	The name of the open property as it is passed to registered change listeners.
protected final AtomicReference<AbstractCircuitBreaker.State>	state	The current state of this circuit breaker.

Constructor Summary

Constructors

Constructor	Description
ThresholdCircuitBreaker(long threshold)	Creates a new instance of ThresholdCircuitBreaker and initializes the threshold.

Method Summary

Modifier and Type	Method	Description
boolean	checkState()	Checks the state of this circuit breaker and changes it if necessary.
void	close()	Closes this circuit breaker.
long	getThreshold()	Gets the threshold.
boolean	incrementAndCheckState(Long increment)	Increments the monitored value and performs a check of the current state of this circuit breaker.

Methods inherited from class AbstractCircuitBreaker

addChangeListener, changeState, isClosed, isOpen, isOpen, open, removeChangeListener

Modifier and Type	Method	Description
void	addChangeListener(PropertyChangeListener listener)	Adds a change listener to this circuit breaker.
protected void	changeState(AbstractCircuitBreaker.State newState)	Changes the internal state of this circuit breaker.
boolean	isClosed()	Tests the current closed state of this circuit breaker.
boolean	isOpen()	Tests the current open state of this circuit breaker.
protected static boolean	isOpen(AbstractCircuitBreaker.State state)	Tests whether the given state represents an open circuit breaker.
void	open()	Opens this circuit breaker.
void	removeChangeListener(PropertyChangeListener listener)	Removes the specified change listener from this circuit breaker.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ThresholdCircuitBreaker

public ThresholdCircuitBreaker(long threshold)

Creates a new instance of ThresholdCircuitBreaker and initializes the threshold.

Parameters:

threshold - The threshold.

Method Details

checkState

public boolean checkState()

Checks the state of this circuit breaker and changes it if necessary. The return value indicates whether the circuit breaker is now in state closed; a value of true typically means that the current operation can continue.

Specified by:

checkState in interface CircuitBreaker<Long>

Specified by:

checkState in class AbstractCircuitBreaker<Long>

Returns:

true if the circuit breaker is now closed; false otherwise.

close

public void close()

Closes this circuit breaker. Its state is changed to closed. If this circuit breaker is already closed, this method has no effect.

Resets the internal counter back to its initial value (zero).

Specified by:

close in interface CircuitBreaker<Long>

Overrides:

close in class AbstractCircuitBreaker<Long>

getThreshold

public long getThreshold()

Gets the threshold.

Returns:

The threshold

incrementAndCheckState

public boolean incrementAndCheckState(Long increment)

Increments the monitored value and performs a check of the current state of this circuit breaker. This method works like CircuitBreaker.checkState(), but the monitored value is incremented before the state check is performed.

If the threshold is zero, the circuit breaker will be in a permanent open state.

The internal counter is a protective counter and only moves toward the threshold: negative increments are rejected, and an increment that would overflow Long.MAX_VALUE saturates the counter at Long.MAX_VALUE and opens the circuit breaker instead of silently wrapping negative (which would disable the trip condition).

Specified by:

incrementAndCheckState in interface CircuitBreaker<Long>

Specified by:

incrementAndCheckState in class AbstractCircuitBreaker<Long>

Parameters:

increment - value to increment in the monitored value of the circuit breaker

Returns:

true if the circuit breaker is now closed; false otherwise

Throws:

IllegalArgumentException - Thrown if the increment is negative.