ThresholdCircuitBreaker
Date: 2017-02-08

org.apache.commons.lang3.concurrent

## Class ThresholdCircuitBreaker

- java.lang.Object
- - org.apache.commons.lang3.concurrent.AbstractCircuitBreaker<java.lang.Long>
  - - org.apache.commons.lang3.concurrent.ThresholdCircuitBreaker

- All Implemented Interfaces:
    CircuitBreaker<java.lang.Long>

      public class ThresholdCircuitBreaker
      extends AbstractCircuitBreaker<java.lang.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 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 and Description
    `ThresholdCircuitBreaker(long threshold)` Creates a new instance of `ThresholdCircuitBreaker` and initializes the threshold.

  - ### Method Summary

    Methods
    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` | `getThreshold()` Gets the threshold.
    `boolean` | `incrementAndCheckState(java.lang.Long increment)` Increments the monitored value and performs a check of the current state of this circuit breaker.

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

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

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

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

- - ### Constructor Detail

    - #### ThresholdCircuitBreaker

          public ThresholdCircuitBreaker(long threshold)

      Creates a new instance of `ThresholdCircuitBreaker` and initializes the threshold.

      Parameters:
        `threshold` - the threshold.

  - ### Method Detail

    - #### getThreshold

          public long getThreshold()

      Gets the threshold.
      Returns:
        the threshold

    - #### checkState

          public boolean checkState()
                             throws CircuitBreakingException

      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<java.lang.Long>`
      Specified by:
        `checkState` in class `AbstractCircuitBreaker<java.lang.Long>`
      Returns:
        true if the circuit breaker is now closed; false otherwise
      Throws:
        `CircuitBreakingException`

    - #### 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<java.lang.Long>`
      Overrides:
        `close` in class `AbstractCircuitBreaker<java.lang.Long>`

    - #### incrementAndCheckState

          public boolean incrementAndCheckState(java.lang.Long increment)
                                         throws CircuitBreakingException

      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.

      Specified by:
        `incrementAndCheckState` in interface `CircuitBreaker<java.lang.Long>`
      Specified by:
        `incrementAndCheckState` in class `AbstractCircuitBreaker<java.lang.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:
        `CircuitBreakingException`