Package io.github.resilience4j.circuitbreaker

Interface CircuitBreaker

All Known Implementing Classes:
CircuitBreakerStateMachine
public interface CircuitBreaker
A CircuitBreaker instance is thread-safe can be used to decorate multiple requests.

A CircuitBreaker manages the state of a backend system. The CircuitBreaker is implemented via a finite state machine with five states: CLOSED, OPEN, HALF_OPEN, DISABLED AND FORCED_OPEN. The CircuitBreaker does not know anything about the backend's state by itself, but uses the information provided by the decorators via onSuccess(long, java.util.concurrent.TimeUnit) and onError(long, java.util.concurrent.TimeUnit, java.lang.Throwable) events. Before communicating with the backend, the permission to do so must be obtained via the method tryAcquirePermission().

The state of the CircuitBreaker changes from CLOSED to OPEN when the failure rate is greater than or equal to a (configurable) threshold. Then, all access to the backend is rejected for a (configurable) time duration. No further calls are permitted.

After the time duration has elapsed, the CircuitBreaker state changes from OPEN to HALF_OPEN and allows a number of calls to see if the backend is still unavailable or has become available again. If the failure rate is greater than or equal to the configured threshold, the state changes back to OPEN. If the failure rate is below or equal to the threshold, the state changes back to CLOSED.

  • Method Details

    • decorateCheckedSupplier

      static <T> io.github.resilience4j.core.functions.CheckedSupplier<T> decorateCheckedSupplier(CircuitBreaker circuitBreaker, io.github.resilience4j.core.functions.CheckedSupplier<T> supplier)
      Returns a supplier which is decorated by a CircuitBreaker.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      circuitBreaker - the CircuitBreaker
      supplier - the original supplier
      Returns:
      a supplier which is decorated by a CircuitBreaker.

    • decorateCompletionStage

      static <T> Supplier<CompletionStage<T>> decorateCompletionStage(CircuitBreaker circuitBreaker, Supplier<CompletionStage<T>> supplier)
      Returns a supplier which is decorated by a CircuitBreaker.
      Type Parameters:
      T - the type of the returned CompletionStage's result
      Parameters:
      circuitBreaker - the CircuitBreaker
      supplier - the original supplier
      Returns:
      a supplier which is decorated by a CircuitBreaker.

    • decorateCheckedRunnable

      static io.github.resilience4j.core.functions.CheckedRunnable decorateCheckedRunnable(CircuitBreaker circuitBreaker, io.github.resilience4j.core.functions.CheckedRunnable runnable)
      Returns a runnable which is decorated by a CircuitBreaker.
      Parameters:
      circuitBreaker - the CircuitBreaker
      runnable - the original runnable
      Returns:
      a runnable which is decorated by a CircuitBreaker.

    • decorateCallable

      static <T> Callable<T> decorateCallable(CircuitBreaker circuitBreaker, Callable<T> callable)
      Returns a callable which is decorated by a CircuitBreaker.
      Type Parameters:
      T - the result type of callable
      Parameters:
      circuitBreaker - the CircuitBreaker
      callable - the original Callable
      Returns:
      a supplier which is decorated by a CircuitBreaker.

    • decorateSupplier

      static <T> Supplier<T> decorateSupplier(CircuitBreaker circuitBreaker, Supplier<T> supplier)
      Returns a supplier which is decorated by a CircuitBreaker.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      circuitBreaker - the CircuitBreaker
      supplier - the original supplier
      Returns:
      a supplier which is decorated by a CircuitBreaker.

    • decorateConsumer

      static <T> Consumer<T> decorateConsumer(CircuitBreaker circuitBreaker, Consumer<T> consumer)
      Returns a consumer which is decorated by a CircuitBreaker.
      Type Parameters:
      T - the type of the input to the consumer
      Parameters:
      circuitBreaker - the CircuitBreaker
      consumer - the original consumer
      Returns:
      a consumer which is decorated by a CircuitBreaker.

    • decorateCheckedConsumer

      static <T> io.github.resilience4j.core.functions.CheckedConsumer<T> decorateCheckedConsumer(CircuitBreaker circuitBreaker, io.github.resilience4j.core.functions.CheckedConsumer<T> consumer)
      Returns a consumer which is decorated by a CircuitBreaker.
      Type Parameters:
      T - the type of the input to the consumer
      Parameters:
      circuitBreaker - the CircuitBreaker
      consumer - the original consumer
      Returns:
      a consumer which is decorated by a CircuitBreaker.

    • decorateRunnable

      static Runnable decorateRunnable(CircuitBreaker circuitBreaker, Runnable runnable)
      Returns a runnable which is decorated by a CircuitBreaker.
      Parameters:
      circuitBreaker - the CircuitBreaker
      runnable - the original runnable
      Returns:
      a runnable which is decorated by a CircuitBreaker.

    • decorateFunction

      static <T, R> Function<T,R> decorateFunction(CircuitBreaker circuitBreaker, Function<T,R> function)
      Returns a function which is decorated by a CircuitBreaker.
      Type Parameters:
      T - the type of the input to the function
      R - the type of the result of the function
      Parameters:
      circuitBreaker - the CircuitBreaker
      function - the original function
      Returns:
      a function which is decorated by a CircuitBreaker.

    • decorateCheckedFunction

      static <T, R> io.github.resilience4j.core.functions.CheckedFunction<T,R> decorateCheckedFunction(CircuitBreaker circuitBreaker, io.github.resilience4j.core.functions.CheckedFunction<T,R> function)
      Returns a function which is decorated by a CircuitBreaker.
      Type Parameters:
      T - the type of the input to the function
      R - the type of the result of the function
      Parameters:
      circuitBreaker - the CircuitBreaker
      function - the original function
      Returns:
      a function which is decorated by a CircuitBreaker.

    • ofDefaults

      static CircuitBreaker ofDefaults(String name)
      Creates a CircuitBreaker with a default CircuitBreaker configuration.
      Parameters:
      name - the name of the CircuitBreaker
      Returns:
      a CircuitBreaker with a default CircuitBreaker configuration.

    • of

      static CircuitBreaker of(String name, CircuitBreakerConfig circuitBreakerConfig)
      Creates a CircuitBreaker with a custom CircuitBreaker configuration.
      Parameters:
      name - the name of the CircuitBreaker
      circuitBreakerConfig - a custom CircuitBreaker configuration
      Returns:
      a CircuitBreaker with a custom CircuitBreaker configuration.

    • of

      static CircuitBreaker of(String name, CircuitBreakerConfig circuitBreakerConfig, Map<String,String> tags)
      Creates a CircuitBreaker with a custom CircuitBreaker configuration.

      The tags passed will be appended to the tags already configured for the registry. When tags (keys) of the two collide the tags passed with this method will override the tags of the registry.

      Parameters:
      name - the name of the CircuitBreaker
      circuitBreakerConfig - a custom CircuitBreaker configuration
      tags - tags added to the Retry
      Returns:
      a CircuitBreaker with a custom CircuitBreaker configuration.

    • of

      static CircuitBreaker of(String name, Supplier<CircuitBreakerConfig> circuitBreakerConfigSupplier)
      Creates a CircuitBreaker with a custom CircuitBreaker configuration.
      Parameters:
      name - the name of the CircuitBreaker
      circuitBreakerConfigSupplier - a supplier of a custom CircuitBreaker configuration
      Returns:
      a CircuitBreaker with a custom CircuitBreaker configuration.

    • of

      static CircuitBreaker of(String name, Supplier<CircuitBreakerConfig> circuitBreakerConfigSupplier, Map<String,String> tags)
      Creates a CircuitBreaker with a custom CircuitBreaker configuration.

      The tags passed will be appended to the tags already configured for the registry. When tags (keys) of the two collide the tags passed with this method will override the tags of the registry.

      Parameters:
      name - the name of the CircuitBreaker
      circuitBreakerConfigSupplier - a supplier of a custom CircuitBreaker configuration
      tags - tags added to the CircuitBreaker
      Returns:
      a CircuitBreaker with a custom CircuitBreaker configuration.

    • decorateFuture

      static <T> Supplier<Future<T>> decorateFuture(CircuitBreaker circuitBreaker, Supplier<Future<T>> supplier)
      Returns a supplier of type Future which is decorated by a CircuitBreaker. The elapsed time includes Future.get() evaluation time even if the underlying call took less time to return. Any delays in evaluating Future by caller will add towards total time.
      Type Parameters:
      T - the type of the returned Future's result
      Parameters:
      circuitBreaker - the CircuitBreaker
      supplier - the original supplier
      Returns:
      a supplier which is decorated by a CircuitBreaker.

    • tryAcquirePermission

      boolean tryAcquirePermission()
      Acquires a permission to execute a call, only if one is available at the time of invocation. If a call is not permitted, the number of not permitted calls is increased.

      Returns false when the state is OPEN or FORCED_OPEN. Returns true when the state is CLOSED or DISABLED. Returns true when the state is HALF_OPEN and further test calls are allowed. Returns false when the state is HALF_OPEN and the number of test calls has been reached. If the state is HALF_OPEN, the number of allowed test calls is decreased. Important: Make sure to call onSuccess or onError after the call is finished. If the call is cancelled before it is invoked, you have to release the permission again.

      Returns:
      true if a permission was acquired and false otherwise

    • releasePermission

      void releasePermission()
      Releases a permission.

      Should only be used when a permission was acquired but not used. Otherwise use onSuccess(long, TimeUnit) or onError(long, TimeUnit, Throwable) to signal a completed or failed call.

      If the state is HALF_OPEN, the number of allowed test calls is increased by one.

    • acquirePermission

      void acquirePermission()
      Try to obtain a permission to execute a call. If a call is not permitted, the number of not permitted calls is increased.

      Throws a CallNotPermittedException when the state is OPEN or FORCED_OPEN. Returns when the state is CLOSED or DISABLED. Returns when the state is HALF_OPEN and further test calls are allowed. Throws a CallNotPermittedException when the state is HALF_OPEN and the number of test calls has been reached. If the state is HALF_OPEN, the number of allowed test calls is decreased. Important: Make sure to call onSuccess or onError after the call is finished. If the call is cancelled before it is invoked, you have to release the permission again.

      Throws:
      CallNotPermittedException - when CircuitBreaker is OPEN or HALF_OPEN and no further test calls are permitted.

    • onError

      void onError(long duration, TimeUnit durationUnit, Throwable throwable)
      Records a failed call. This method must be invoked when a call failed.
      Parameters:
      duration - The elapsed time duration of the call
      durationUnit - The duration unit
      throwable - The throwable which must be recorded

    • onSuccess

      void onSuccess(long duration, TimeUnit durationUnit)
      Records a successful call. This method must be invoked when a call was successful.
      Parameters:
      duration - The elapsed time duration of the call
      durationUnit - The duration unit

    • onResult

      void onResult(long duration, TimeUnit durationUnit, Object result)
      This method must be invoked when a call returned a result and the result predicate should decide if the call was successful or not.
      Parameters:
      duration - The elapsed time duration of the call
      durationUnit - The duration unit
      result - The result of the protected function

    • reset

      void reset()
      Returns the circuit breaker to its original closed state, losing statistics.

      Should only be used, when you want to fully reset the circuit breaker without creating a new one.

    • transitionToClosedState

      void transitionToClosedState()
      Transitions the state machine to CLOSED state. This call is idempotent and will not have any effect if the state machine is already in CLOSED state.

      Should only be used, when you want to force a state transition. State transition are normally done internally.

    • transitionToOpenState

      void transitionToOpenState()
      Transitions the state machine to OPEN state. This call is idempotent and will not have any effect if the state machine is already in OPEN state.

      Should only be used, when you want to force a state transition. State transition are normally done internally.

    • transitionToOpenStateFor

      void transitionToOpenStateFor(Duration waitDuration)
      Same as transitionToOpenState() but waits in open state for the given amount of time instead of relaying on configurations to determine it.
      Parameters:
      waitDuration - how long should we wait in open state

    • transitionToOpenStateUntil

      void transitionToOpenStateUntil(Instant waitUntil)
      Same as transitionToOpenState() but waits in open state until the given in time instead of relaying on configurations to determine it.
      Parameters:
      waitUntil - how long should we wait in open state

    • transitionToHalfOpenState

      void transitionToHalfOpenState()
      Transitions the state machine to HALF_OPEN state. This call is idempotent and will not have any effect if the state machine is already in HALF_OPEN state.

      Should only be used, when you want to force a state transition. State transition are normally done internally.

    • transitionToDisabledState

      void transitionToDisabledState()
      Transitions the state machine to a DISABLED state, stopping state transition, metrics and event publishing. This call is idempotent and will not have any effect if the state machine is already in DISABLED state.

      Should only be used, when you want to disable the circuit breaker allowing all calls to pass. To recover from this state you must force a new state transition

    • transitionToMetricsOnlyState

      void transitionToMetricsOnlyState()
      Transitions the state machine to METRICS_ONLY state, stopping all state transitions but continues to capture metrics and publish events. This call is idempotent and will not have any effect if the state machine is already in METRICS_ONLY state.

      Should only be used when you want to collect metrics while keeping the circuit breaker disabled, allowing all calls to pass. To recover from this state you must force a new state transition.

    • transitionToForcedOpenState

      void transitionToForcedOpenState()
      Transitions the state machine to a FORCED_OPEN state, stopping state transition, metrics and event publishing. This call is idempotent and will not have any effect if the state machine is already in FORCED_OPEN state.

      Should only be used, when you want to disable the circuit breaker allowing no call to pass. To recover from this state you must force a new state transition

    • getName

      String getName()
      Returns the name of this CircuitBreaker.
      Returns:
      the name of this CircuitBreaker

    • getState

      CircuitBreaker.State getState()
      Returns the state of this CircuitBreaker.
      Returns:
      the state of this CircuitBreaker

    • getCircuitBreakerConfig

      CircuitBreakerConfig getCircuitBreakerConfig()
      Returns the CircuitBreakerConfig of this CircuitBreaker.
      Returns:
      the CircuitBreakerConfig of this CircuitBreaker

    • getMetrics

      CircuitBreaker.Metrics getMetrics()
      Returns the Metrics of this CircuitBreaker.
      Returns:
      the Metrics of this CircuitBreaker

    • getTags

      Map<String,String> getTags()
      Returns an unmodifiable map with tags assigned to this Retry.
      Returns:
      the tags assigned to this Retry in an unmodifiable map

    • getEventPublisher

      CircuitBreaker.EventPublisher getEventPublisher()
      Returns an EventPublisher which can be used to register event consumers.
      Returns:
      an EventPublisher

    • getCurrentTimestamp

      long getCurrentTimestamp()
      Returns the current time with respect to the CircuitBreaker currentTimeFunction. Returns System.nanoTime() by default.
      Returns:
      current timestamp

    • getTimestampUnit

      TimeUnit getTimestampUnit()
      Returns the timeUnit of current timestamp. Default is TimeUnit.NANOSECONDS.
      Returns:
      the timeUnit of current timestamp

    • executeSupplier

      default <T> T executeSupplier(Supplier<T> supplier)
      Decorates and executes the decorated Supplier.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      supplier - the original Supplier
      Returns:
      the result of the decorated Supplier.

    • decorateSupplier

      default <T> Supplier<T> decorateSupplier(Supplier<T> supplier)
      Returns a supplier which is decorated by a CircuitBreaker.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      supplier - the original supplier
      Returns:
      a supplier which is decorated by a CircuitBreaker.

    • executeCallable

      default <T> T executeCallable(Callable<T> callable) throws Exception
      Decorates and executes the decorated Callable.
      Type Parameters:
      T - the result type of callable
      Parameters:
      callable - the original Callable
      Returns:
      the result of the decorated Callable.
      Throws:
      Exception - if unable to compute a result

    • decorateCallable

      default <T> Callable<T> decorateCallable(Callable<T> callable)
      Returns a callable which is decorated by a CircuitBreaker.
      Type Parameters:
      T - the result type of callable
      Parameters:
      callable - the original Callable
      Returns:
      a supplier which is decorated by a CircuitBreaker.

    • executeRunnable

      default void executeRunnable(Runnable runnable)
      Decorates and executes the decorated Runnable.
      Parameters:
      runnable - the original Runnable

    • decorateRunnable

      default Runnable decorateRunnable(Runnable runnable)
      Returns a runnable which is decorated by a CircuitBreaker.
      Parameters:
      runnable - the original runnable
      Returns:
      a runnable which is decorated by a CircuitBreaker.

    • executeCompletionStage

      default <T> CompletionStage<T> executeCompletionStage(Supplier<CompletionStage<T>> supplier)
      Decorates and executes the decorated CompletionStage.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      supplier - the original CompletionStage
      Returns:
      the decorated CompletionStage.

    • decorateCompletionStage

      default <T> Supplier<CompletionStage<T>> decorateCompletionStage(Supplier<CompletionStage<T>> supplier)
      Returns a supplier which is decorated by a CircuitBreaker.
      Type Parameters:
      T - the type of the returned CompletionStage's result
      Parameters:
      supplier - the original supplier
      Returns:
      a supplier which is decorated by a CircuitBreaker.

    • executeCheckedSupplier

      default <T> T executeCheckedSupplier(io.github.resilience4j.core.functions.CheckedSupplier<T> checkedSupplier) throws Throwable
      Decorates and executes the decorated Supplier.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      checkedSupplier - the original Supplier
      Returns:
      the result of the decorated Supplier.
      Throws:
      Throwable - if something goes wrong applying this function to the given arguments

    • decorateCheckedSupplier

      default <T> io.github.resilience4j.core.functions.CheckedSupplier<T> decorateCheckedSupplier(io.github.resilience4j.core.functions.CheckedSupplier<T> checkedSupplier)
      Returns a supplier which is decorated by a CircuitBreaker.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      checkedSupplier - the original supplier
      Returns:
      a supplier which is decorated by a CircuitBreaker.

    • decorateCheckedRunnable

      default io.github.resilience4j.core.functions.CheckedRunnable decorateCheckedRunnable(io.github.resilience4j.core.functions.CheckedRunnable runnable)
      Returns a runnable which is decorated by a CircuitBreaker.
      Parameters:
      runnable - the original runnable
      Returns:
      a runnable which is decorated by a CircuitBreaker.

    • executeCheckedRunnable

      default void executeCheckedRunnable(io.github.resilience4j.core.functions.CheckedRunnable runnable) throws Throwable
      Decorates and executes the decorated Runnable.
      Parameters:
      runnable - the original runnable
      Throws:
      Throwable

    • decorateConsumer

      default <T> Consumer<T> decorateConsumer(Consumer<T> consumer)
      Returns a consumer which is decorated by a CircuitBreaker.
      Type Parameters:
      T - the type of the input to the consumer
      Parameters:
      consumer - the original consumer
      Returns:
      a consumer which is decorated by a CircuitBreaker.

    • decorateCheckedConsumer

      default <T> io.github.resilience4j.core.functions.CheckedConsumer<T> decorateCheckedConsumer(io.github.resilience4j.core.functions.CheckedConsumer<T> consumer)
      Returns a consumer which is decorated by a CircuitBreaker.
      Type Parameters:
      T - the type of the input to the consumer
      Parameters:
      consumer - the original consumer
      Returns:
      a consumer which is decorated by a CircuitBreaker.

    • decorateFuture

      default <T> Supplier<Future<T>> decorateFuture(Supplier<Future<T>> supplier)
      Returns a supplier of type Future which is decorated by a CircuitBreaker. The elapsed time includes Future.get() evaluation time even if the underlying call took less time to return. Any delays in evaluating Future by caller will add towards total time.
      Type Parameters:
      T - the type of the returned CompletionStage's result
      Parameters:
      supplier - the original supplier
      Returns:
      a supplier which is decorated by a CircuitBreaker.