io.vertx.circuitbreaker

## Interface CircuitBreaker

-     public interface CircuitBreaker

  An implementation of the circuit breaker pattern for Vert.x
  Author:
    Clement Escoffier

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `CircuitBreaker` | `close()` Closes the circuit breaker.
    `CircuitBreaker` | `closeHandler(Handler<Void> handler)` Sets a `Handler` invoked when the circuit breaker state switches to close.
    `static CircuitBreaker` | `create(String name, Vertx vertx)` Creates a new instance of `CircuitBreaker`, with default options.
    `static CircuitBreaker` | `create(String name, Vertx vertx, CircuitBreakerOptions options)` Creates a new instance of `CircuitBreaker`.
    `<T> Future<T>` | `execute(Handler<Future<T>> command)` Same as `executeWithFallback(Handler, Function)` but using the circuit breaker default fallback.
    `<T> CircuitBreaker` | `executeAndReport(Future<T> resultFuture, Handler<Future<T>> command)` Same as `executeAndReportWithFallback(Future, Handler, Function)` but using the circuit breaker default fallback.
    `<T> CircuitBreaker` | `executeAndReportWithFallback(Future<T> resultFuture, Handler<Future<T>> command, java.util.function.Function<Throwable,T> fallback)` Executes the given operation with the circuit breaker control.
    `default <T> void` | `executeCommand(Handler<Future<T>> command, Handler<AsyncResult<T>> handler)` Same as `executeWithFallback(Handler, Function)` but using the circuit breaker default fallback.
    `default <T> void` | `executeCommandWithFallback(Handler<Future<T>> command, java.util.function.Function<Throwable,T> fallback, Handler<AsyncResult<T>> handler)` Same as `executeWithFallback(Handler, Function)` but using a callback.
    `<T> Future<T>` | `executeWithFallback(Handler<Future<T>> command, java.util.function.Function<Throwable,T> fallback)` Executes the given operation with the circuit breaker control.
    `long` | `failureCount()`
    `<T> CircuitBreaker` | `fallback(java.util.function.Function<Throwable,T> handler)` Sets a default `Function` invoked when the bridge is open to handle the "request", or on failure if `CircuitBreakerOptions.isFallbackOnFailure()` is enabled.
    `CircuitBreaker` | `halfOpenHandler(Handler<Void> handler)` Sets a `Handler` invoked when the circuit breaker state switches to half-open.
    `String` | `name()`
    `CircuitBreaker` | `open()` Explicitly opens the circuit.
    `CircuitBreaker` | `openHandler(Handler<Void> handler)` Sets a `Handler` invoked when the circuit breaker state switches to open.
    `CircuitBreaker` | `reset()` Resets the circuit breaker state (number of failure set to 0 and state set to closed).
    `CircuitBreakerState` | `state()`

- - ### Method Detail

    - #### create

          static CircuitBreaker create(String name,
                                       Vertx vertx,
                                       CircuitBreakerOptions options)

      Creates a new instance of `CircuitBreaker`.
      Parameters:
        `name` - the name
        `vertx` - the Vert.x instance
        `options` - the configuration option
      Returns:
        the created instance

    - #### create

          static CircuitBreaker create(String name,
                                       Vertx vertx)

      Creates a new instance of `CircuitBreaker`, with default options.
      Parameters:
        `name` - the name
        `vertx` - the Vert.x instance
      Returns:
        the created instance

    - #### close

          CircuitBreaker close()

      Closes the circuit breaker. It stops sending events on its state on the event bus. This method is not related to the `close` state of the circuit breaker. To set the circuit breaker in the `close` state, use `reset()`.

    - #### openHandler

          CircuitBreaker openHandler(Handler<Void> handler)

      Sets a `Handler` invoked when the circuit breaker state switches to open.
      Parameters:
        `handler` - the handler, must not be `null`
      Returns:
        the current `CircuitBreaker`

    - #### halfOpenHandler

          CircuitBreaker halfOpenHandler(Handler<Void> handler)

      Sets a `Handler` invoked when the circuit breaker state switches to half-open.
      Parameters:
        `handler` - the handler, must not be `null`
      Returns:
        the current `CircuitBreaker`

    - #### closeHandler

          CircuitBreaker closeHandler(Handler<Void> handler)

      Sets a `Handler` invoked when the circuit breaker state switches to close.
      Parameters:
        `handler` - the handler, must not be `null`
      Returns:
        the current `CircuitBreaker`

    - #### executeWithFallback

          <T> Future<T> executeWithFallback(Handler<Future<T>> command,
                                            java.util.function.Function<Throwable,T> fallback)

      Executes the given operation with the circuit breaker control. The operation is generally calling an external system. The operation receives a `Future` object as parameter and must call `Future.complete(Object)` when the operation has terminated successfully. The operation must also call `Future.fail(Throwable)` in case of failure.

      The operation is not invoked if the circuit breaker is open, and the given fallback is called immediately. The circuit breaker also monitor the completion of the operation before a configure timeout. The operation is considered as failed if it does not terminate in time.

      This method returns a `Future` object to retrieve the status and result of the operation, with the status being a success or a failure. If the fallback is called, the returned future is successfully completed with the value returned from the fallback. If the fallback throws an exception, the returned future is marked as failed.

      Type Parameters:
        `T` - the type of result
      Parameters:
        `command` - the operation
        `fallback` - the fallback function. It gets an exception as parameter and returns the fallback result
      Returns:
        a future object completed when the operation or its fallback completes

    - #### executeCommandWithFallback

          default <T> void executeCommandWithFallback(Handler<Future<T>> command,
                                                      java.util.function.Function<Throwable,T> fallback,
                                                      Handler<AsyncResult<T>> handler)

      Same as `executeWithFallback(Handler, Function)` but using a callback.
      Type Parameters:
        `T` - the type of result
      Parameters:
        `command` - the operation
        `fallback` - the fallback
        `handler` - the completion handler receiving either the operation result or the fallback result. The parameter is an `AsyncResult` because if the fallback is not called, the error is passed to the handler.

    - #### execute

          <T> Future<T> execute(Handler<Future<T>> command)

      Same as `executeWithFallback(Handler, Function)` but using the circuit breaker default fallback.
      Type Parameters:
        `T` - the type of result
      Parameters:
        `command` - the operation
      Returns:
        a future object completed when the operation or its fallback completes

    - #### executeCommand

          default <T> void executeCommand(Handler<Future<T>> command,
                                          Handler<AsyncResult<T>> handler)

      Same as `executeWithFallback(Handler, Function)` but using the circuit breaker default fallback.
      Type Parameters:
        `T` - the type of result
      Parameters:
        `command` - the operation

    - #### executeAndReport

          <T> CircuitBreaker executeAndReport(Future<T> resultFuture,
                                              Handler<Future<T>> command)

      Same as `executeAndReportWithFallback(Future, Handler, Function)` but using the circuit breaker default fallback.
      Type Parameters:
        `T` - the type of result
      Parameters:
        `resultFuture` - the future on which the operation result is reported
        `command` - the operation
      Returns:
        the current `CircuitBreaker`

    - #### executeAndReportWithFallback

          <T> CircuitBreaker executeAndReportWithFallback(Future<T> resultFuture,
                                                          Handler<Future<T>> command,
                                                          java.util.function.Function<Throwable,T> fallback)

      Executes the given operation with the circuit breaker control. The operation is generally calling an external system. The operation receives a `Future` object as parameter and must call `Future.complete(Object)` when the operation has terminated successfully. The operation must also call `Future.fail(Throwable)` in case of failure.

      The operation is not invoked if the circuit breaker is open, and the given fallback is called immediately. The circuit breaker also monitor the completion of the operation before a configure timeout. The operation is considered as failed if it does not terminate in time.

      Unlike `executeWithFallback(Handler, Function)`, this method does return a `Future` object, but let the caller pass a `Future` object on which the result is reported. If the fallback is called, the future is successfully completed with the value returned by the fallback function. If the fallback throws an exception, the future is marked as failed.

      Type Parameters:
        `T` - the type of result
      Parameters:
        `resultFuture` - the future on which the operation result is reported
        `command` - the operation
        `fallback` - the fallback function. It gets an exception as parameter and returns the fallback result
      Returns:
        the current `CircuitBreaker`

    - #### fallback

          <T> CircuitBreaker fallback(java.util.function.Function<Throwable,T> handler)

      Sets a default `Function` invoked when the bridge is open to handle the "request", or on failure if `CircuitBreakerOptions.isFallbackOnFailure()` is enabled.

      The function gets the exception as parameter and returns the fallback result.

      Parameters:
        `handler` - the handler
      Returns:
        the current `CircuitBreaker`

    - #### reset

          CircuitBreaker reset()

      Resets the circuit breaker state (number of failure set to 0 and state set to closed).
      Returns:
        the current `CircuitBreaker`

    - #### open

          CircuitBreaker open()

      Explicitly opens the circuit.
      Returns:
        the current `CircuitBreaker`

    - #### state

          CircuitBreakerState state()

      Returns:
        the current state.

    - #### failureCount

          long failureCount()

      Returns:
        the current number of failures.

    - #### name

          String name()

      Returns:
        the name of the circuit breaker.

Copyright © 2017. All rights reserved.