Package io.smallrye.faulttolerance.api

Interface FaultTolerance<T>

Type Parameters:
T - type of value of the guarded action
@Experimental("first attempt at providing programmatic API") public interface FaultTolerance<T>
Allows guarding an action with various fault tolerance strategies: bulkhead, circuit breaker, fallback, rate limit, retry, and timeout. Synchronous as well as asynchronous actions may be guarded, asynchronous actions may optionally be offloaded to another thread. The only supported type for asynchronous actions is CompletionStage.

An instance of this interface represents a configured set of fault tolerance strategies. It can be used to guard a Callable, Supplier or Runnable invocation, or adapt an unguarded Callable, Supplier or Runnable to a guarded one.

The create* and createAsync* methods return a builder that allows configuring all fault tolerance strategies. Order of builder method invocations does not matter, the fault tolerance strategies are always applied in a predefined order: fallback > retry > circuit breaker > rate limit > timeout > bulkhead > thread offload > guarded action.

Two styles of usage are possible. The createCallable(Callable) and createAsyncCallable(Callable) methods return a builder that, at the end, returns a Callable. This is convenient in case you only want to guard a single action (which is possibly invoked multiple times). Similar methods exist for the Supplier and Runnable types.

The create() and createAsync() methods return a builder that, at the end, returns a FaultTolerance instance, which is useful when you need to guard multiple actions with the same set of fault tolerance strategies. Note that bulkheads, circuit breakers and rate limits are stateful, so there's a big difference between guarding multiple actions using the same FaultTolerance object and using a separate FaultTolerance object for each action. Using a single FaultTolerance instance to guard multiple actions means that a single bulkhead, circuit breaker and/or rate limit will be shared among all those actions.

This API is essentially a programmatic equivalent to the declarative, annotation-based API of MicroProfile Fault Tolerance and SmallRye Fault Tolerance. It shares the set of fault tolerance strategies, their invocation order and behavior, their configuration properties, etc. Notable differences are:

  • asynchronous actions of type Future are not supported;
  • the fallback, circuit breaker and retry strategies always inspect the cause chain of exceptions, following the behavior of SmallRye Fault Tolerance in the non-compatible mode.

  • Method Details

    • circuitBreakerMaintenance

      static CircuitBreakerMaintenance circuitBreakerMaintenance()
      Returns a CircuitBreakerMaintenance instance that provides maintenance access to existing circuit breakers.

    • createCallable

      static <T> FaultTolerance.Builder<T,Callable<T>> createCallable(Callable<T> action)
      Returns a builder that, at the end, returns a Callable guarding the given action. The action is synchronous and is always executed on the original thread.

    • createSupplier

      static <T> FaultTolerance.Builder<T,Supplier<T>> createSupplier(Supplier<T> action)
      Returns a builder that, at the end, returns a Supplier guarding the given action. The action is synchronous and is always executed on the original thread.

    • createRunnable

      static FaultTolerance.Builder<Void,Runnable> createRunnable(Runnable action)
      Returns a builder that, at the end, returns a Runnable guarding the given action. The action is synchronous and is always executed on the original thread.

    • create

      static <T> FaultTolerance.Builder<T,FaultTolerance<T>> create()
      Returns a builder that, at the end, returns a FaultTolerance object representing a set of configured fault tolerance strategies. It can be used to execute synchronous actions using call(Callable), get(Supplier) or run(Runnable).

      This method usually has to be called with an explicitly provided type argument. For example: FaultTolerance.&lt;String>create().

    • createAsyncCallable

      static <T> FaultTolerance.Builder<CompletionStage<T>,Callable<CompletionStage<T>>> createAsyncCallable(Callable<CompletionStage<T>> action)
      Returns a builder that, at the end, returns a Callable guarding the given action. The action is asynchronous and may be offloaded to another thread.

    • createAsyncSupplier

      static <T> FaultTolerance.Builder<CompletionStage<T>,Supplier<CompletionStage<T>>> createAsyncSupplier(Supplier<CompletionStage<T>> action)
      Returns a builder that, at the end, returns a Supplier guarding the given action. The action is asynchronous and may be offloaded to another thread.

    • createAsyncRunnable

      static FaultTolerance.Builder<CompletionStage<Void>,Runnable> createAsyncRunnable(Runnable action)
      Returns a builder that, at the end, returns a Runnable guarding the given action. The action is asynchronous and may be offloaded to another thread.

    • createAsync

      static <T> FaultTolerance.Builder<CompletionStage<T>,FaultTolerance<CompletionStage<T>>> createAsync()
      Returns a builder that, at the end, returns a FaultTolerance object representing a set of configured fault tolerance strategies. It can be used to execute asynchronous actions using call(Callable), get(Supplier) or run(Runnable).

      This method usually has to be called with an explicitly provided type argument. For example: FaultTolerance.&lt;String>createAsync().

    • call

      T call(Callable<T> action) throws Exception
      Calls given action and guards the call by this configured set of fault tolerance strategies. If this FaultTolerance instance was created using create(), the action is synchronous and is always executed on the same thread that calls this method. If this FaultTolerance instance was created using createAsync(), the action is asynchronous and may be offloaded to another thread depending on how the builder was configured.
      Throws:
      Exception

    • get

      default T get(Supplier<T> action)
      Calls given action and guards the call by this configured set of fault tolerance strategies. If this FaultTolerance instance was created using create*, the action is synchronous and is always executed on the same thread that calls this method. If this FaultTolerance instance was created using createAsync*, the action is asynchronous and may be offloaded to another thread depending on how the builder was configured.

    • run

      default void run(Runnable action)
      Calls given action and guards the call by this configured set of fault tolerance strategies. If this FaultTolerance instance was created using create(), the action is synchronous and is always executed on the same thread that calls this method. If this FaultTolerance instance was created using createAsync(), the action is asynchronous and may be offloaded to another thread depending on how the builder was configured.

    • adaptCallable

      default Callable<T> adaptCallable(Callable<T> action)
      Adapts given action to an action guarded by this configured set of fault tolerance strategies. Useful when the action has to be called multiple times.

      Equivalent to () -> call(action).

      See Also:

    • adaptSupplier

      default Supplier<T> adaptSupplier(Supplier<T> action)
      Adapts given action to an action guarded by this configured set of fault tolerance strategies. Useful when the action has to be called multiple times.

      Equivalent to () -> get(action).

      See Also:

    • adaptRunnable

      default Runnable adaptRunnable(Runnable action)
      Adapts given action to an action guarded by this configured set of fault tolerance strategies. Useful when the action has to be called multiple times.

      Equivalent to () -> run(action).

      See Also:

    • cast

      <U> FaultTolerance<U> cast()
      Casts this FaultTolerance object so that it guards actions of a different type. Since the type of the action is only used in fallback, this is usually safe; if this FaultTolerance object contains a fallback, this method throws an exception.

      Note that this method may only be used to cast synchronous FaultTolerance. If this FaultTolerance object guards asynchronous actions, this method throws an exception.

      Type Parameters:
      U - type of value of the guarded action

    • castAsync

      <U> FaultTolerance<U> castAsync(Class<?> asyncType)
      Casts this FaultTolerance object so that it guards actions of a different type. Since the type of the action is only used in fallback, this is usually safe; if this FaultTolerance object contains a fallback, this method throws an exception.

      Note that this method may only be used to cast asynchronous FaultTolerance of given type (such as CompletionStage or Uni). If this FaultTolerance object guards synchronous actions or asynchronous actions of different type, this method throws an exception.

      Type Parameters:
      U - type of value of the guarded action
      Parameters:
      asyncType - the asynchronous type, such as CompletionStage or Uni