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:
    CircuitBreakerConfig, CircuitBreakerBuilder, CircuitBreakerOpenException
    • Method Detail

      • 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:
        builder()
      • open

        void open()
        Opens the circuit.
      • close

        void close()
        Closes the circuit.
      • halfOpen

        void halfOpen()
        Half-opens 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

        java.time.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​(java.lang.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.