Package dev.failsafe

Interface CircuitBreaker<R>

Type Parameters:
R - result type
All Superinterfaces:
Policy<R>
All Known Implementing Classes:
CircuitBreakerImpl

public interface CircuitBreaker<R> extends Policy<R>
A circuit breaker temporarily blocks execution when a configured number of failures are exceeded.

Circuit breakers have three states: closed, open, and half-open. When a circuit breaker is in the closed (initial) state, executions are allowed. If a configurable number of failures occur, optionally over some time period, the circuit breaker transitions to the open state. In the open state a circuit breaker will fail executions with CircuitBreakerOpenException. After a configurable delay, the circuit breaker will transition to a half-open state. In the half-open state a configurable number of trial executions will be allowed, after which the circuit breaker will transition back to closed or open depending on how many were successful.

A circuit breaker can be count based or time based:

  • Count based circuit breakers will transition between states when recent execution results exceed a threshold.
  • Time based circuit breakers will transition between states when recent execution results exceed a threshold within a time period.

A minimum number of executions must be performed in order for a state transition to occur. Time based circuit breakers use a sliding window to aggregate execution results. The window is divided into 10 time slices, each representing 1/10th of the failureThresholdingPeriod. As time progresses, statistics for old time slices are gradually discarded, which smoothes the calculation of success and failure rates.

This class is threadsafe.

See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    The state of the circuit.
  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    Attempts to acquire a permit for the circuit breaker and throws CircuitBreakerOpenException if a permit could not be acquired.
    static <R> CircuitBreakerBuilder<R>
    Creates a CircuitBreakerBuilder that by default will build a count based circuit breaker that opens after a single failure, closes after a single success, and has a 1 minute delay, unless configured otherwise.
    static <R> CircuitBreakerBuilder<R>
    Creates a new CircuitBreakerBuilder that will be based on the config.
    void
    Closes the circuit.
    Returns the CircuitBreakerConfig that the CircuitBreaker was built with.
    int
    Returns the number of executions recorded in the current state when the state is CLOSED or HALF_OPEN.
    long
    Returns the number of failures recorded in the current state when the state is CLOSED or HALF_OPEN.
    int
    The percentage rate of failed executions, from 0 to 100, in the current state when the state is CLOSED or HALF_OPEN.
    When in the OPEN state, returns the remaining delay until the circuit is half-opened and allows another execution, else returns Duration.ZERO.
    Gets the state of the circuit.
    int
    Returns the number of successes recorded in the current state when the state is CLOSED or HALF_OPEN.
    int
    The percentage rate of successful executions, from 0 to 100, in the current state when the state is CLOSED or HALF_OPEN.
    void
    Half-opens the circuit.
    boolean
    Returns whether the circuit is closed.
    boolean
    Returns whether the circuit is half open.
    boolean
    Returns whether the circuit is open.
    static <R> CircuitBreaker<R>
    Creates a count based CircuitBreaker that opens after one failure, half-opens after a one minute delay, and closes after one success.
    void
    Opens the circuit.
    void
    Records an exception as a success or failure based on the failure configuration.
    void
    Records an execution failure.
    void
    recordResult(R result)
    Records an execution result as a success or failure based on the failure configuration.
    void
    Records an execution success.
    boolean
    Tries to acquire a permit to use the circuit breaker and returns whether a permit was acquired.

    Methods inherited from interface dev.failsafe.Policy

    toExecutor
  • Method Details

    • builder

      static <R> CircuitBreakerBuilder<R> builder()
      Creates a CircuitBreakerBuilder that by default will build a count based circuit breaker that opens after a single failure, closes after a single success, and has a 1 minute delay, unless configured otherwise.
      See Also:
    • builder

      static <R> CircuitBreakerBuilder<R> builder(CircuitBreakerConfig<R> config)
      Creates a new CircuitBreakerBuilder that will be based on the config.
    • ofDefaults

      static <R> CircuitBreaker<R> ofDefaults()
      Creates a count based CircuitBreaker that opens after one failure, half-opens after a one minute delay, and closes after one success. To configure additional options on a CircuitBreaker, use builder() instead.
      See Also:
    • getConfig

      CircuitBreakerConfig<R> getConfig()
      Returns the CircuitBreakerConfig that the CircuitBreaker was built with.
      Specified by:
      getConfig in interface Policy<R>
    • acquirePermit

      default void acquirePermit()
      Attempts to acquire a permit for the circuit breaker and throws CircuitBreakerOpenException if a permit could not be acquired. Permission will be automatically released when a result or failure is recorded.
      Throws:
      CircuitBreakerOpenException - if the circuit breaker is in a half-open state and no permits remain according to the configured success or failure thresholding capacity.
      See Also:
    • tryAcquirePermit

      boolean tryAcquirePermit()
      Tries to acquire a permit to use the circuit breaker and returns whether a permit was acquired. Permission will be automatically released when a result or failure is recorded.
      See Also:
    • open

      void open()
      Opens the circuit.
    • close

      void close()
      Closes the circuit.
    • halfOpen

      void halfOpen()
      Half-opens the circuit.
    • getState

      Gets the state of the circuit.
    • getExecutionCount

      int getExecutionCount()
      Returns the number of executions recorded in the current state when the state is CLOSED or HALF_OPEN. When the state is OPEN, returns the executions recorded during the previous CLOSED state.

      For count based thresholding, the max number of executions is limited to the execution threshold. For time based thresholds, the number of executions may vary within the thresholding period.

    • getRemainingDelay

      Duration getRemainingDelay()
      When in the OPEN state, returns the remaining delay until the circuit is half-opened and allows another execution, else returns Duration.ZERO.
    • getFailureCount

      long getFailureCount()
      Returns the number of failures recorded in the current state when the state is CLOSED or HALF_OPEN. When the state is OPEN, returns the failures recorded during the previous CLOSED state.

      For count based thresholds, the max number of failures is based on the failure threshold. For time based thresholds, the number of failures may vary within the failure thresholding period.

    • getFailureRate

      int getFailureRate()
      The percentage rate of failed executions, from 0 to 100, in the current state when the state is CLOSED or HALF_OPEN. When the state is OPEN, returns the rate recorded during the previous CLOSED state.

      The rate is based on the configured failure thresholding capacity.

    • getSuccessCount

      int getSuccessCount()
      Returns the number of successes recorded in the current state when the state is CLOSED or HALF_OPEN. When the state is OPEN, returns the successes recorded during the previous CLOSED state.

      The max number of successes is based on the success threshold.

    • getSuccessRate

      int getSuccessRate()
      The percentage rate of successful executions, from 0 to 100, in the current state when the state is CLOSED or HALF_OPEN. When the state is OPEN, returns the rate recorded during the previous CLOSED state.

      The rate is based on the configured success thresholding capacity.

    • isClosed

      boolean isClosed()
      Returns whether the circuit is closed.
    • isHalfOpen

      boolean isHalfOpen()
      Returns whether the circuit is half open.
    • isOpen

      boolean isOpen()
      Returns whether the circuit is open.
    • recordFailure

      void recordFailure()
      Records an execution failure.
    • recordException

      void recordException(Throwable exception)
      Records an exception as a success or failure based on the failure configuration.
    • recordResult

      void recordResult(R result)
      Records an execution result as a success or failure based on the failure configuration.
    • recordSuccess

      void recordSuccess()
      Records an execution success.