dev.failsafe

Class CircuitBreakerBuilder<R>

java.lang.Object

dev.failsafe.PolicyBuilder<S,C,R>

dev.failsafe.FailurePolicyBuilder<S,C,R>

dev.failsafe.DelayablePolicyBuilder<CircuitBreakerBuilder<R>,CircuitBreakerConfig<R>,R>

dev.failsafe.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.

• By default, any exception is considered a failure and will be handled by the policy. You can override this by specifying your own handle conditions. The default exception handling condition will only be overridden by another condition that handles exceptions such as FailurePolicyBuilder.handle(Class) or FailurePolicyBuilder.handleIf(CheckedBiPredicate). Specifying a condition that only handles results, such as FailurePolicyBuilder.handleResult(Object) or FailurePolicyBuilder.handleResultIf(CheckedPredicate) will not replace the default exception handling condition.
• If multiple handle conditions are specified, any condition that matches an execution result or exception will trigger policy handling.

Note:

• This class extends DelayablePolicyBuilder and FailurePolicyBuilder which offer additional configuration.
• This class is not threadsafe.

See Also:

CircuitBreaker, CircuitBreakerConfig, CircuitBreakerOpenException

Field Summary

Fields inherited from class dev.failsafe.PolicyBuilder

config

Method Summary

Modifier and Type	Method and Description
CircuitBreaker<R>	build() Builds a new CircuitBreaker using the builder's configuration.
CircuitBreakerBuilder<R>	onClose(EventListener<CircuitBreakerStateChangedEvent> listener) Calls the listener when the circuit is closed.
CircuitBreakerBuilder<R>	onHalfOpen(EventListener<CircuitBreakerStateChangedEvent> listener) Calls the listener when the circuit is half-opened.
CircuitBreakerBuilder<R>	onOpen(EventListener<CircuitBreakerStateChangedEvent> listener) Calls the listener when the circuit is opened.
CircuitBreakerBuilder<R>	withDelay(Duration delay) Sets the delay to wait in OPEN state before transitioning to half-open.
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.
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.
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.
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.
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.
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.
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.

Methods inherited from class dev.failsafe.DelayablePolicyBuilder

withDelayFn, withDelayFnOn, withDelayFnWhen

Methods inherited from class dev.failsafe.FailurePolicyBuilder

handle, handle, handle, handleIf, handleIf, handleResult, handleResultIf

Methods inherited from class dev.failsafe.PolicyBuilder

onFailure, onSuccess

Methods inherited from class java.lang.Object

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

Methods inherited from interface dev.failsafe.PolicyListeners

onFailure, onSuccess

Method Detail

build

public CircuitBreaker<R> build()

Builds a new CircuitBreaker using the builder's configuration.

onClose

public CircuitBreakerBuilder<R> onClose(EventListener<CircuitBreakerStateChangedEvent> listener)

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

public CircuitBreakerBuilder<R> onHalfOpen(EventListener<CircuitBreakerStateChangedEvent> listener)

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

public CircuitBreakerBuilder<R> onOpen(EventListener<CircuitBreakerStateChangedEvent> listener)

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 < 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 < 1

See Also:

CircuitBreakerConfig.getFailureThreshold()

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 < 1, failureThresholdingCapacity < 1, or failureThreshold > failureThresholdingCapacity

See Also:

CircuitBreakerConfig.getFailureThreshold(), CircuitBreakerConfig.getFailureExecutionThreshold()

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 < 1 or failureThresholdingPeriod < 10 ms

See Also:

CircuitBreakerConfig.getFailureThreshold(), CircuitBreakerConfig.getFailureThresholdingPeriod()

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 < 1, failureExecutionThreshold < 1, failureThreshold > failureExecutionThreshold, or failureThresholdingPeriod < 10 ms

See Also:

CircuitBreakerConfig.getFailureThreshold(), CircuitBreakerConfig.getFailureExecutionThreshold(), CircuitBreakerConfig.getFailureThresholdingPeriod()

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 < 1 or > 100, failureExecutionThreshold < 1, or failureThresholdingPeriod < 10 ms

See Also:

CircuitBreakerConfig.getFailureRateThreshold(), CircuitBreakerConfig.getFailureExecutionThreshold(), CircuitBreakerConfig.getFailureThresholdingPeriod()

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 < 1

See Also:

CircuitBreakerConfig.getSuccessThreshold()

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 < 1, successThresholdingCapacity < 1, or successThreshold > successThresholdingCapacity

See Also:

CircuitBreakerConfig.getSuccessThreshold(), CircuitBreakerConfig.getSuccessThresholdingCapacity()