Package dev.failsafe

Class CircuitBreakerBuilder<R>

Type Parameters:
R - result type
All Implemented Interfaces:
PolicyListeners<CircuitBreakerBuilder<R>,R>

public class CircuitBreakerBuilder<R> extends DelayablePolicyBuilder<CircuitBreakerBuilder<R>,CircuitBreakerConfig<R>,R> implements PolicyListeners<CircuitBreakerBuilder<R>,R>
Builds CircuitBreaker instances.

Note:

See Also:
  • Constructor Details

    • CircuitBreakerBuilder

      CircuitBreakerBuilder()
    • CircuitBreakerBuilder

      CircuitBreakerBuilder(CircuitBreakerConfig<R> config)
  • Method Details

    • build

      public CircuitBreaker<R> build()
      Builds a new CircuitBreaker using the builder's configuration.
    • onClose

      Calls the listener when the circuit is closed.

      Note: Any exceptions that are thrown from within the listener are ignored.

      Throws:
      NullPointerException - if listener is null
    • onHalfOpen

      Calls the listener when the circuit is half-opened.

      Note: Any exceptions that are thrown within the listener are ignored.

      Throws:
      NullPointerException - if listener is null
    • onOpen

      Calls the listener when the circuit is opened.

      Note: Any exceptions that are thrown within the listener are ignored.

      Throws:
      NullPointerException - if listener is null
    • withDelay

      public CircuitBreakerBuilder<R> withDelay(Duration delay)
      Sets the delay to wait in OPEN state before transitioning to half-open.
      Overrides:
      withDelay in class DelayablePolicyBuilder<CircuitBreakerBuilder<R>,CircuitBreakerConfig<R>,R>
      Throws:
      NullPointerException - if delay is null
      IllegalArgumentException - if delay invalid input: '<' 0
    • withFailureThreshold

      public CircuitBreakerBuilder<R> withFailureThreshold(int failureThreshold)
      Configures count based failure thresholding by setting the number of consecutive failures that must occur when in a CLOSED state in order to open the circuit.

      If a success threshold is not configured, the failureThreshold will also be used when the circuit breaker is in a HALF_OPEN state to determine whether to transition back to OPEN or CLOSED.

      Parameters:
      failureThreshold - The number of consecutive failures that must occur in order to open the circuit
      Throws:
      IllegalArgumentException - if failureThreshold invalid input: '<' 1
      See Also:
    • withFailureThreshold

      public CircuitBreakerBuilder<R> withFailureThreshold(int failureThreshold, int failureThresholdingCapacity)
      Configures count based failure thresholding by setting the ratio of failures to executions that must occur when in a CLOSED state in order to open the circuit. For example: 5, 10 would open the circuit if 5 out of the last 10 executions result in a failure.

      If a success threshold is not configured, the failureThreshold and failureThresholdingCapacity will also be used when the circuit breaker is in a HALF_OPEN state to determine whether to transition back to OPEN or CLOSED.

      Parameters:
      failureThreshold - The number of failures that must occur in order to open the circuit
      failureThresholdingCapacity - The capacity for storing execution results when performing failure thresholding
      Throws:
      IllegalArgumentException - if failureThreshold invalid input: '<' 1, failureThresholdingCapacity invalid input: '<' 1, or failureThreshold > failureThresholdingCapacity
      See Also:
    • withFailureThreshold

      public CircuitBreakerBuilder<R> withFailureThreshold(int failureThreshold, Duration failureThresholdingPeriod)
      Configures time based failure thresholding by setting the number of failures that must occur within the failureThresholdingPeriod when in a CLOSED state in order to open the circuit.

      If a success threshold is not configured, the failureThreshold will also be used when the circuit breaker is in a HALF_OPEN state to determine whether to transition back to OPEN or CLOSED.

      Parameters:
      failureThreshold - The number of failures that must occur within the failureThresholdingPeriod in order to open the circuit
      failureThresholdingPeriod - The period during which failures are compared to the failureThreshold
      Throws:
      NullPointerException - if failureThresholdingPeriod is null
      IllegalArgumentException - if failureThreshold invalid input: '<' 1 or failureThresholdingPeriod invalid input: '<' 10 ms
      See Also:
    • withFailureThreshold

      public CircuitBreakerBuilder<R> withFailureThreshold(int failureThreshold, int failureExecutionThreshold, Duration failureThresholdingPeriod)
      Configures time based failure thresholding by setting the number of failures that must occur within the failureThresholdingPeriod when in a CLOSED state in order to open the circuit. The number of executions must also exceed the failureExecutionThreshold within the failureThresholdingPeriod when in the CLOSED state before the circuit can be opened.

      If a success threshold is not configured, the failureThreshold will also be used when the circuit breaker is in a HALF_OPEN state to determine whether to transition back to OPEN or CLOSED.

      Parameters:
      failureThreshold - The number of failures that must occur within the failureThresholdingPeriod in order to open the circuit
      failureExecutionThreshold - The minimum number of executions that must occur within the failureThresholdingPeriod when in the CLOSED state before the circuit can be opened
      failureThresholdingPeriod - The period during which failures are compared to the failureThreshold
      Throws:
      NullPointerException - if failureThresholdingPeriod is null
      IllegalArgumentException - if failureThreshold invalid input: '<' 1, failureExecutionThreshold invalid input: '<' 1, failureThreshold > failureExecutionThreshold, or failureThresholdingPeriod invalid input: '<' 10 ms
      See Also:
    • withFailureRateThreshold

      public CircuitBreakerBuilder<R> withFailureRateThreshold(int failureRateThreshold, int failureExecutionThreshold, Duration failureThresholdingPeriod)
      Configures time based failure rate thresholding by setting the percentage rate of failures, from 1 to 100, that must occur within the rolling failureThresholdingPeriod when in a CLOSED state in order to open the circuit. The number of executions must also exceed the failureExecutionThreshold within the failureThresholdingPeriod before the circuit can be opened.

      If a success threshold is not configured, the failureExecutionThreshold will also be used when the circuit breaker is in a HALF_OPEN state to determine whether to transition back to open or closed.

      Parameters:
      failureRateThreshold - The percentage rate of failures, from 1 to 100, that must occur in order to open the circuit
      failureExecutionThreshold - The minimum number of executions that must occur within the failureThresholdingPeriod when in the CLOSED state before the circuit can be opened, or in the HALF_OPEN state before it can be re-opened or closed
      failureThresholdingPeriod - The period during which failures are compared to the failureThreshold
      Throws:
      NullPointerException - if failureThresholdingPeriod is null
      IllegalArgumentException - if failureRateThreshold invalid input: '<' 1 or > 100, failureExecutionThreshold invalid input: '<' 1, or failureThresholdingPeriod invalid input: '<' 10 ms
      See Also:
    • assertFailureExecutionThreshold

      private void assertFailureExecutionThreshold(int failureExecutionThreshold)
    • assertFailureThresholdingPeriod

      private void assertFailureThresholdingPeriod(Duration failureThresholdingPeriod)
    • withSuccessThreshold

      public CircuitBreakerBuilder<R> withSuccessThreshold(int successThreshold)
      Configures count based success thresholding by setting the number of consecutive successful executions that must occur when in a HALF_OPEN state in order to close the circuit, else the circuit is re-opened when a failure occurs.
      Parameters:
      successThreshold - The number of consecutive successful executions that must occur in order to open the circuit
      Throws:
      IllegalArgumentException - if successThreshold invalid input: '<' 1
      See Also:
    • withSuccessThreshold

      public CircuitBreakerBuilder<R> withSuccessThreshold(int successThreshold, int successThresholdingCapacity)
      Configures count based success thresholding by setting the ratio of successful executions that must occur when in a HALF_OPEN state in order to close the circuit. For example: 5, 10 would close the circuit if 5 out of the last 10 executions were successful.
      Parameters:
      successThreshold - The number of successful executions that must occur in order to open the circuit
      successThresholdingCapacity - The capacity for storing execution results when performing success thresholding
      Throws:
      IllegalArgumentException - if successThreshold invalid input: '<' 1, successThresholdingCapacity invalid input: '<' 1, or successThreshold > successThresholdingCapacity
      See Also: