EventCountCircuitBreaker (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3.concurrent, class: EventCountCircuitBreaker

Package org.apache.commons.lang3.concurrent

# Class EventCountCircuitBreaker

java.lang.Object
org.apache.commons.lang3.concurrent.AbstractCircuitBreaker<Integer>
org.apache.commons.lang3.concurrent.EventCountCircuitBreaker

All Implemented Interfaces:
  `CircuitBreaker<Integer>`

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:

- A threshold for the number of events that causes a state transition to open state. If more events are received in the configured check interval, the circuit breaker switches to open state.
- The interval for checks whether the circuit breaker should open. So it is possible to specify something like "The circuit breaker should open if more than 10 errors are encountered in a minute."
- The same parameters can be specified for automatically closing the circuit breaker again, as in "If the number of requests goes down to 100 per minute, the circuit breaker should close itself again". Depending on the use case, it may make sense to use a slightly lower threshold for closing the circuit breaker than for opening it to avoid continuously flipping when the number of events received is close to the threshold.

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:

- This implementation uses non-blocking algorithms to update the internal counter and state. This should be pretty efficient if there is not too much contention.
- This implementation is not intended to operate as a high-precision timer in very short check intervals. It is deliberately kept simple to avoid complex and time-consuming state checks. It should work well in time intervals from a few seconds up to minutes and longer. If the intervals become too short, there might be race conditions causing spurious state transitions.
- The handling of check intervals is a bit simplistic. Therefore, there is no guarantee that the circuit breaker is triggered at a specific point in time; there may be some delay (less than a check interval).

Since:
  3.5

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.commons.lang3.concurrent.AbstractCircuitBreaker

  `AbstractCircuitBreaker.State`

- ## Field Summary

  ### Fields inherited from class org.apache.commons.lang3.concurrent.AbstractCircuitBreaker

  `PROPERTY_NAME, state`

- ## Constructor Summary

  Constructors
  Constructor
  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.

- ## 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`
  `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.

  ### Methods inherited from class org.apache.commons.lang3.concurrent.AbstractCircuitBreaker

  `addChangeListener, changeState, isClosed, isOpen, isOpen, removeChangeListener`

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### EventCountCircuitBreaker

    public EventCountCircuitBreaker(int threshold, long checkInterval, TimeUnit checkUnit)
    Creates a new instance of `EventCountCircuitBreaker` which uses the same parameters for opening and closing checks.
    Parameters:
      `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 again
      `checkInterval` - the check interval for opening or closing the circuit breaker
      `checkUnit` - the `TimeUnit` defining the check interval

  - ### EventCountCircuitBreaker

    public EventCountCircuitBreaker(int openingThreshold, long checkInterval, TimeUnit checkUnit, int closingThreshold)
    Creates a new instance of `EventCountCircuitBreaker` with the same interval for opening and closing checks.
    Parameters:
      `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 opened
      `checkInterval` - the check interval for opening or closing the circuit breaker
      `checkUnit` - the `TimeUnit` defining the check interval
      `closingThreshold` - 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 again

  - ### EventCountCircuitBreaker

    public 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.
    Parameters:
      `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 opened
      `openingInterval` - the interval for opening the circuit breaker
      `openingUnit` - the `TimeUnit` defining the opening interval
      `closingThreshold` - 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 again
      `closingInterval` - the interval for closing the circuit breaker
      `closingUnit` - the `TimeUnit` defining the closing interval

- ## 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.

    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.

    Specified by:
      `checkState` in interface `CircuitBreaker<Integer>`
    Specified by:
      `checkState` in class `AbstractCircuitBreaker<Integer>`
    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.

    A new check interval is started. If too many events are received in this interval, the circuit breaker changes again to state open. If this circuit breaker is already closed, this method has no effect, except that a new check interval is started.

    Specified by:
      `close` in interface `CircuitBreaker<Integer>`
    Overrides:
      `close` in class `AbstractCircuitBreaker<Integer>`

  - ### getClosingInterval

    public long getClosingInterval()
    Returns the interval (in nanoseconds) for checking for the closing threshold.
    Returns:
      the opening check interval

  - ### getClosingThreshold

    public int getClosingThreshold()
    Returns the threshold value 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 again.
    Returns:
      the closing threshold

  - ### getOpeningInterval

    public long getOpeningInterval()
    Returns the interval (in nanoseconds) for checking for the opening threshold.
    Returns:
      the opening check interval

  - ### getOpeningThreshold

    public int getOpeningThreshold()
    Returns the threshold value 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 opened.
    Returns:
      the opening threshold

  - ### incrementAndCheckState

    public boolean incrementAndCheckState()
    Increments the monitored value by 1 and performs a check of the current state of this circuit breaker. This method works like `checkState()`, but the monitored value is incremented before the state check is performed.
    Returns:
      true if the circuit breaker is now closed; false otherwise

  - ### incrementAndCheckState

    public boolean incrementAndCheckState(Integer 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.
    Specified by:
      `incrementAndCheckState` in interface `CircuitBreaker<Integer>`
    Specified by:
      `incrementAndCheckState` in class `AbstractCircuitBreaker<Integer>`
    Parameters:
      `increment` - value to increment in the monitored value of the circuit breaker
    Returns:
      true if the circuit breaker is now closed; false otherwise

  - ### open

    public void open()
    Opens this circuit breaker. Its state is changed to open. Depending on a concrete implementation, it may close itself again if the monitored subsystem becomes available. If this circuit breaker is already open, this method has no effect.

    This circuit breaker may close itself again if the number of events received during a check interval goes below the closing threshold. If this circuit breaker is already open, this method has no effect, except that a new check interval is started.

    Specified by:
      `open` in interface `CircuitBreaker<Integer>`
    Overrides:
      `open` in class `AbstractCircuitBreaker<Integer>`