public class EventCountCircuitBreaker extends AbstractCircuitBreaker<Integer>
A simple implementation of the Circuit Breaker pattern that counts specific events.
A circuit breaker can be used to protect an application against unreliable
services or unexpected load. A newly created EventCountCircuitBreaker object is
initially in state closed meaning that no problem has been detected. When the
application encounters specific events (like errors or service timeouts), it tells the
circuit breaker to increment an internal counter. If the number of events reported in a
specific time interval exceeds a configurable threshold, the circuit breaker changes
into state open. This means that there is a problem with the associated sub
system; the application should no longer call it, but give it some time to settle down.
The circuit breaker can be configured to switch back to closed state after a
certain time frame if the number of events received goes below a threshold.
When a EventCountCircuitBreaker object is constructed the following parameters
can be provided:
This class supports the following typical use cases:
Protecting against load peaks
Imagine you have a server which can handle a certain number of requests per minute.
Suddenly, the number of requests increases significantly - maybe because a connected
partner system is going mad or due to a denial of service attack. A
EventCountCircuitBreaker can be configured to stop the application from
processing requests when a sudden peak load is detected and to start request processing
again when things calm down. The following code fragment shows a typical example of
such a scenario. Here the EventCountCircuitBreaker allows up to 1000 requests
per minute before it interferes. When the load goes down again to 800 requests per
second it switches back to state closed:
EventCountCircuitBreaker breaker = new EventCountCircuitBreaker(1000, 1, TimeUnit.MINUTE, 800);
...
public void handleRequest(Request request) {
if (breaker.incrementAndCheckState()) {
// actually handle this request
} else {
// do something else, e.g. send an error code
}
}
Deal with an unreliable service
In this scenario, an application uses an external service which may fail from time to time. If there are too many errors, the service is considered down and should not be called for a while. This can be achieved using the following pattern - in this concrete example we accept up to 5 errors in 2 minutes; if this limit is reached, the service is given a rest time of 10 minutes:
EventCountCircuitBreaker breaker = new EventCountCircuitBreaker(5, 2, TimeUnit.MINUTE, 5, 10, TimeUnit.MINUTE);
...
public void handleRequest(Request request) {
if (breaker.checkState()) {
try {
service.doSomething();
} catch (ServiceException ex) {
breaker.incrementAndCheckState();
}
} else {
// return an error code, use an alternative service, etc.
}
}
In addition to automatic state transitions, the state of a circuit breaker can be
changed manually using the methods open() and close(). It is also
possible to register PropertyChangeListener objects that get notified whenever
a state transition occurs. This is useful, for instance to directly react on a freshly
detected error condition.
Implementation notes:
AbstractCircuitBreaker.StatePROPERTY_NAME, state| Constructor and Description |
|---|
EventCountCircuitBreaker(int threshold,
long checkInterval,
TimeUnit checkUnit)
Creates a new instance of
EventCountCircuitBreaker which uses the same parameters for
opening and closing checks. |
EventCountCircuitBreaker(int openingThreshold,
long checkInterval,
TimeUnit checkUnit,
int closingThreshold)
Creates a new instance of
EventCountCircuitBreaker with the same interval for opening
and closing checks. |
EventCountCircuitBreaker(int openingThreshold,
long openingInterval,
TimeUnit openingUnit,
int closingThreshold,
long closingInterval,
TimeUnit closingUnit)
Creates a new instance of
EventCountCircuitBreaker and initializes all properties for
opening and closing it based on threshold values for events occurring in specific
intervals. |
| Modifier and Type | Method and Description |
|---|---|
boolean |
checkState()
Checks the state of this circuit breaker and changes it if necessary.
|
void |
close()
Closes this circuit breaker.
|
long |
getClosingInterval()
Returns the interval (in nanoseconds) for checking for the closing threshold.
|
int |
getClosingThreshold()
Returns the threshold value for closing the circuit breaker.
|
long |
getOpeningInterval()
Returns the interval (in nanoseconds) for checking for the opening threshold.
|
int |
getOpeningThreshold()
Returns the threshold value for opening the circuit breaker.
|
boolean |
incrementAndCheckState()
Increments the monitored value by 1 and performs a check of the current state of this
circuit breaker.
|
boolean |
incrementAndCheckState(Integer increment)
Increments the monitored value and performs a check of the current state of this
circuit breaker.
|
void |
open()
Opens this circuit breaker.
|
addChangeListener, changeState, isClosed, isOpen, isOpen, removeChangeListenerpublic EventCountCircuitBreaker(int openingThreshold, long openingInterval, TimeUnit openingUnit, int closingThreshold, long closingInterval, TimeUnit closingUnit)
EventCountCircuitBreaker and initializes all properties for
opening and closing it based on threshold values for events occurring in specific
intervals.openingThreshold - the threshold for opening the circuit breaker; if this
number of events is received in the time span determined by the opening interval,
the circuit breaker is openedopeningInterval - the interval for opening the circuit breakeropeningUnit - the TimeUnit defining the opening intervalclosingThreshold - the threshold for closing the circuit breaker; if the
number of events received in the time span determined by the closing interval goes
below this threshold, the circuit breaker is closed againclosingInterval - the interval for closing the circuit breakerclosingUnit - the TimeUnit defining the closing intervalpublic EventCountCircuitBreaker(int openingThreshold, long checkInterval, TimeUnit checkUnit, int closingThreshold)
EventCountCircuitBreaker with the same interval for opening
and closing checks.openingThreshold - the threshold for opening the circuit breaker; if this
number of events is received in the time span determined by the check interval, the
circuit breaker is openedcheckInterval - the check interval for opening or closing the circuit breakercheckUnit - the TimeUnit defining the check intervalclosingThreshold - the threshold for closing the circuit breaker; if the
number of events received in the time span determined by the check interval goes
below this threshold, the circuit breaker is closed againpublic EventCountCircuitBreaker(int threshold, long checkInterval, TimeUnit checkUnit)
EventCountCircuitBreaker which uses the same parameters for
opening and closing checks.threshold - the threshold for changing the status of the circuit breaker; if
the number of events received in a check interval is greater than this value, the
circuit breaker is opened; if it is lower than this value, it is closed againcheckInterval - the check interval for opening or closing the circuit breakercheckUnit - the TimeUnit defining the check intervalpublic int getOpeningThreshold()
public long getOpeningInterval()
public int getClosingThreshold()
public long getClosingInterval()
public boolean checkState()
CLOSED; a value
of true typically means that the current operation can continue. This implementation checks the internal event counter against the
threshold values and the check intervals. This may cause a state change of this
circuit breaker.checkState in interface CircuitBreaker<Integer>checkState in class AbstractCircuitBreaker<Integer>public boolean incrementAndCheckState(Integer increment) throws CircuitBreakingException
CircuitBreaker.checkState(), but the monitored
value is incremented before the state check is performed.incrementAndCheckState in interface CircuitBreaker<Integer>incrementAndCheckState in class AbstractCircuitBreaker<Integer>increment - value to increment in the monitored value of the circuit breakerCircuitBreakingExceptionpublic boolean incrementAndCheckState()
checkState(), but the monitored
value is incremented before the state check is performed.public void open()
open in interface CircuitBreaker<Integer>open in class AbstractCircuitBreaker<Integer>public void close()
close in interface CircuitBreaker<Integer>close in class AbstractCircuitBreaker<Integer>Copyright © 2001–2016 The Apache Software Foundation. All rights reserved.