/*
    * Licensed to the Apache Software Foundation (ASF) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * The ASF licenses this file to You under the Apache License, Version 2.0
    * (the "License"); you may not use this file except in compliance with
    * the License.  You may obtain a copy of the License at
    *
    *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package org.apache.commons.lang3.concurrent;
  
  import java.beans.PropertyChangeListener;
  import java.util.EnumMap;
  import java.util.Map;
  import java.util.concurrent.TimeUnit;
  import java.util.concurrent.atomic.AtomicReference;
  
  /**
   * A simple implementation of the <a
   * href="https://martinfowler.com/bliki/CircuitBreaker.html">Circuit Breaker</a> pattern
   * that counts specific events.
   *
   * <p>
   * A <em>circuit breaker</em> can be used to protect an application against unreliable
   * services or unexpected load. A newly created {@link EventCountCircuitBreaker} object is
   * initially in state <em>closed</em> 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 <em>open</em>. 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 <em>closed</em> state after a
   * certain time frame if the number of events received goes below a threshold.
   * </p>
   * <p>
   * When a {@link EventCountCircuitBreaker} object is constructed the following parameters
   * can be provided:
   * </p>
   * <ul>
   * <li>A threshold for the number of events that causes a state transition to
   * <em>open</em> state. If more events are received in the configured check interval, the
   * circuit breaker switches to <em>open</em> state.</li>
   * <li>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."</li>
   * <li>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.</li>
   * </ul>
   * <p>
   * This class supports the following typical use cases:
   * </p>
   * <p>
   * <strong>Protecting against load peaks</strong>
   * </p>
   * <p>
   * 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
   * {@link 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 {@link 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 <em>closed</em>:
   * </p>
   *
   * <pre>
   * 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
   *     }
   * }
   * </pre>
   * <p>
   * <strong>Deal with an unreliable service</strong>
   * </p>
   * <p>
   * 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:
   * </p>
   *
   * <pre>
  * 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.
  *     }
  * }
  * </pre>
  * <p>
  * In addition to automatic state transitions, the state of a circuit breaker can be
  * changed manually using the methods {@link #open()} and {@link #close()}. It is also
  * possible to register {@link PropertyChangeListener} objects that get notified whenever
  * a state transition occurs. This is useful, for instance to directly react on a freshly
  * detected error condition.
  * </p>
  * <p>
  * <em>Implementation notes:</em>
  * </p>
  * <ul>
  * <li>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.</li>
  * <li>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.</li>
  * <li>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).</li>
  * </ul>
  * @since 3.5
  */
 public class EventCountCircuitBreaker extends AbstractCircuitBreaker<Integer> {
 
     /**
      * An internally used data class holding information about the checks performed by
      * this class. Basically, the number of received events and the start time of the
      * current check interval are stored.
      */
     private static final class CheckIntervalData {
         /** The counter for events. */
         private final int eventCount;
 
         /** The start time of the current check interval. */
         private final long checkIntervalStart;
 
         /**
          * Creates a new instance of {@link CheckIntervalData}.
          *
          * @param count the current count value
          * @param intervalStart the start time of the check interval
          */
         CheckIntervalData(final int count, final long intervalStart) {
             eventCount = count;
             checkIntervalStart = intervalStart;
         }
 
         /**
          * Returns the start time of the current check interval.
          *
          * @return the check interval start time
          */
         public long getCheckIntervalStart() {
             return checkIntervalStart;
         }
 
         /**
          * Returns the event counter.
          *
          * @return the number of received events
          */
         public int getEventCount() {
             return eventCount;
         }
 
         /**
          * Returns a new instance of {@link CheckIntervalData} with the event counter
          * incremented by the given delta. If the delta is 0, this object is returned.
          *
          * @param delta the delta
          * @return the updated instance
          */
         public CheckIntervalData increment(final int delta) {
             return delta == 0 ? this : new CheckIntervalData(getEventCount() + delta,
                     getCheckIntervalStart());
         }
     }
 
     /**
      * Internally used class for executing check logic based on the current state of the
      * circuit breaker. Having this logic extracted into special classes avoids complex
      * if-then-else cascades.
      */
     private abstract static class StateStrategy {
         /**
          * Obtains the check interval to applied for the represented state from the given
          * {@link CircuitBreaker}.
          *
          * @param breaker the {@link CircuitBreaker}
          * @return the check interval to be applied
          */
         protected abstract long fetchCheckInterval(EventCountCircuitBreaker breaker);
 
         /**
          * Returns a flag whether the end of the current check interval is reached.
          *
          * @param breaker the {@link CircuitBreaker}
          * @param currentData the current state object
          * @param now the current time
          * @return a flag whether the end of the current check interval is reached
          */
         public boolean isCheckIntervalFinished(final EventCountCircuitBreaker breaker,
                 final CheckIntervalData currentData, final long now) {
             return now - currentData.getCheckIntervalStart() > fetchCheckInterval(breaker);
         }
 
         /**
          * Checks whether the specified {@link CheckIntervalData} objects indicate that a
          * state transition should occur. Here the logic which checks for thresholds
          * depending on the current state is implemented.
          *
          * @param breaker the {@link CircuitBreaker}
          * @param currentData the current {@link CheckIntervalData} object
          * @param nextData the updated {@link CheckIntervalData} object
          * @return a flag whether a state transition should be performed
          */
         public abstract boolean isStateTransition(EventCountCircuitBreaker breaker,
                 CheckIntervalData currentData, CheckIntervalData nextData);
     }
 
     /**
      * A specialized {@link StateStrategy} implementation for the state closed.
      */
     private static final class StateStrategyClosed extends StateStrategy {
 
         /**
          * {@inheritDoc}
          */
         @Override
         protected long fetchCheckInterval(final EventCountCircuitBreaker breaker) {
             return breaker.getOpeningInterval();
         }
 
         /**
          * {@inheritDoc}
          */
         @Override
         public boolean isStateTransition(final EventCountCircuitBreaker breaker,
                 final CheckIntervalData currentData, final CheckIntervalData nextData) {
             return nextData.getEventCount() > breaker.getOpeningThreshold();
         }
     }
 
     /**
      * A specialized {@link StateStrategy} implementation for the state open.
      */
     private static final class StateStrategyOpen extends StateStrategy {
         /**
          * {@inheritDoc}
          */
         @Override
         protected long fetchCheckInterval(final EventCountCircuitBreaker breaker) {
             return breaker.getClosingInterval();
         }
 
         /**
          * {@inheritDoc}
          */
         @Override
         public boolean isStateTransition(final EventCountCircuitBreaker breaker,
                 final CheckIntervalData currentData, final CheckIntervalData nextData) {
             return nextData.getCheckIntervalStart() != currentData
                     .getCheckIntervalStart()
                     && currentData.getEventCount() < breaker.getClosingThreshold();
         }
     }
 
     /** A map for accessing the strategy objects for the different states. */
     private static final Map<State, StateStrategy> STRATEGY_MAP = createStrategyMap();
 
     /**
      * Creates the map with strategy objects. It allows access for a strategy for a given
      * state.
      *
      * @return the strategy map
      */
     private static Map<State, StateStrategy> createStrategyMap() {
         final Map<State, StateStrategy> map = new EnumMap<>(State.class);
         map.put(State.CLOSED, new StateStrategyClosed());
         map.put(State.OPEN, new StateStrategyOpen());
         return map;
     }
 
     /**
      * Returns the {@link StateStrategy} object responsible for the given state.
      *
      * @param state the state
      * @return the corresponding {@link StateStrategy}
      * @throws CircuitBreakingException if the strategy cannot be resolved
      */
     private static StateStrategy stateStrategy(final State state) {
         return STRATEGY_MAP.get(state);
     }
 
     /** Stores information about the current check interval. */
     private final AtomicReference<CheckIntervalData> checkIntervalData;
 
     /** The threshold for opening the circuit breaker. */
     private final int openingThreshold;
 
     /** The time interval for opening the circuit breaker. */
     private final long openingInterval;
 
     /** The threshold for closing the circuit breaker. */
     private final int closingThreshold;
 
     /** The time interval for closing the circuit breaker. */
     private final long closingInterval;
 
     /**
      * Creates a new instance of {@link EventCountCircuitBreaker} which uses the same parameters for
      * opening and closing checks.
      *
      * @param 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
      * @param checkInterval the check interval for opening or closing the circuit breaker
      * @param checkUnit the {@link TimeUnit} defining the check interval
      */
     public EventCountCircuitBreaker(final int threshold, final long checkInterval, final TimeUnit checkUnit) {
         this(threshold, checkInterval, checkUnit, threshold);
     }
 
     /**
      * Creates a new instance of {@link EventCountCircuitBreaker} with the same interval for opening
      * and closing checks.
      *
      * @param 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
      * @param checkInterval the check interval for opening or closing the circuit breaker
      * @param checkUnit the {@link TimeUnit} defining the check interval
      * @param 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
      */
     public EventCountCircuitBreaker(final int openingThreshold, final long checkInterval, final TimeUnit checkUnit,
                                     final int closingThreshold) {
         this(openingThreshold, checkInterval, checkUnit, closingThreshold, checkInterval,
                 checkUnit);
     }
 
     /**
      * Creates a new instance of {@link EventCountCircuitBreaker} and initializes all properties for
      * opening and closing it based on threshold values for events occurring in specific
      * intervals.
      *
      * @param 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
      * @param openingInterval the interval for opening the circuit breaker
      * @param openingUnit the {@link TimeUnit} defining the opening interval
      * @param 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
      * @param closingInterval the interval for closing the circuit breaker
      * @param closingUnit the {@link TimeUnit} defining the closing interval
      */
     public EventCountCircuitBreaker(final int openingThreshold, final long openingInterval,
                                     final TimeUnit openingUnit, final int closingThreshold, final long closingInterval,
                                     final TimeUnit closingUnit) {
         checkIntervalData = new AtomicReference<>(new CheckIntervalData(0, 0));
         this.openingThreshold = openingThreshold;
         this.openingInterval = openingUnit.toNanos(openingInterval);
         this.closingThreshold = closingThreshold;
         this.closingInterval = closingUnit.toNanos(closingInterval);
     }
 
     /**
      * Changes the state of this circuit breaker and also initializes a new
      * {@link CheckIntervalData} object.
      *
      * @param newState the new state to be set
      */
     private void changeStateAndStartNewCheckInterval(final State newState) {
         changeState(newState);
         checkIntervalData.set(new CheckIntervalData(0, nanoTime()));
     }
 
     /**
      * {@inheritDoc}
      * <p>
      * 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.
      * </p>
      */
     @Override
     public boolean checkState() {
         return performStateCheck(0);
     }
 
     /**
      * {@inheritDoc}
      * <p>
      * 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.
      * </p>
      */
     @Override
     public void close() {
         super.close();
         checkIntervalData.set(new CheckIntervalData(0, nanoTime()));
     }
 
     /**
      * Returns the interval (in nanoseconds) for checking for the closing threshold.
      *
      * @return the opening check interval
      */
     public long getClosingInterval() {
         return closingInterval;
     }
 
     /**
      * 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.
      *
      * @return the closing threshold
      */
     public int getClosingThreshold() {
         return closingThreshold;
     }
 
     /**
      * Returns the interval (in nanoseconds) for checking for the opening threshold.
      *
      * @return the opening check interval
      */
     public long getOpeningInterval() {
         return openingInterval;
     }
 
     /**
      * 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.
      *
      * @return the opening threshold
      */
     public int getOpeningThreshold() {
         return openingThreshold;
     }
 
     /**
      * Increments the monitored value by <strong>1</strong> and performs a check of the current state of this
      * circuit breaker. This method works like {@link #checkState()}, but the monitored
      * value is incremented before the state check is performed.
      *
      * @return <strong>true</strong> if the circuit breaker is now closed;
      * <strong>false</strong> otherwise
      */
     public boolean incrementAndCheckState() {
         return incrementAndCheckState(1);
     }
 
     /**
      * {@inheritDoc}
      */
     @Override
     public boolean incrementAndCheckState(final Integer increment) {
         return performStateCheck(increment);
     }
 
     /**
      * Returns the current time in nanoseconds. This method is used to obtain the current
      * time. This is needed to calculate the check intervals correctly.
      *
      * @return the current time in nanoseconds
      */
     long nanoTime() {
         return System.nanoTime();
     }
 
     /**
      * Calculates the next {@link CheckIntervalData} object based on the current data and
      * the current state. The next data object takes the counter increment and the current
      * time into account.
      *
      * @param increment the increment for the internal counter
      * @param currentData the current check data object
      * @param currentState the current state of the circuit breaker
      * @param time the current time
      * @return the updated {@link CheckIntervalData} object
      */
     private CheckIntervalData nextCheckIntervalData(final int increment,
             final CheckIntervalData currentData, final State currentState, final long time) {
         final CheckIntervalData nextData;
         if (stateStrategy(currentState).isCheckIntervalFinished(this, currentData, time)) {
             nextData = new CheckIntervalData(increment, time);
         } else {
             nextData = currentData.increment(increment);
         }
         return nextData;
     }
 
     /**
      * {@inheritDoc}
      * <p>
      * 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.
      * </p>
      */
     @Override
     public void open() {
         super.open();
         checkIntervalData.set(new CheckIntervalData(0, nanoTime()));
     }
 
     /**
      * Actually checks the state of this circuit breaker and executes a state transition
      * if necessary.
      *
      * @param increment the increment for the internal counter
      * @return a flag whether the circuit breaker is now closed
      */
     private boolean performStateCheck(final int increment) {
         CheckIntervalData currentData;
         CheckIntervalData nextData;
         State currentState;
 
         do {
             final long time = nanoTime();
             currentState = state.get();
             currentData = checkIntervalData.get();
             nextData = nextCheckIntervalData(increment, currentData, currentState, time);
         } while (!updateCheckIntervalData(currentData, nextData));
 
         // This might cause a race condition if other changes happen in between!
         // Refer to the header comment!
         if (stateStrategy(currentState).isStateTransition(this, currentData, nextData)) {
             currentState = currentState.oppositeState();
             changeStateAndStartNewCheckInterval(currentState);
         }
         return !isOpen(currentState);
     }
 
     /**
      * Updates the {@link CheckIntervalData} object. The current data object is replaced
      * by the one modified by the last check. The return value indicates whether this was
      * successful. If it is <strong>false</strong>, another thread interfered, and the
      * whole operation has to be redone.
      *
      * @param currentData the current check data object
      * @param nextData the replacing check data object
      * @return a flag whether the update was successful
      */
     private boolean updateCheckIntervalData(final CheckIntervalData currentData,
             final CheckIntervalData nextData) {
         return currentData == nextData
                 || checkIntervalData.compareAndSet(currentData, nextData);
     }
 
 }