Package io.smallrye.faulttolerance.api

Interface TypedGuard<T>

Type Parameters:
T - type of value of the guarded action
@Experimental("second attempt at providing programmatic API") public interface TypedGuard<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.

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

The create(Class) methods return a builder that allows configuring the supported 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.

Note that bulkheads, circuit breakers and rate limits are stateful, so there's a big difference between guarding multiple actions using the same TypedGuard object and using a separate TypedGuard object for each action. Using a single TypedGuard 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.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    TypedGuard.Builder<T>
    A builder for configuring fault tolerance strategies.

  • Method Summary

    Modifier and Type
    Method
    Description
    default Callable<T>
    adaptCallable(Callable<T> action)
    Adapts given action to an action guarded by this configured set of fault tolerance strategies.
    default Supplier<T>
    adaptSupplier(Supplier<T> action)
    Adapts given action to an action guarded by this configured set of fault tolerance strategies.
    T
    call(Callable<T> action)
    Calls given action and guards the call by this configured set of fault tolerance strategies.
    static <T> TypedGuard.Builder<T>
    create(jakarta.enterprise.util.TypeLiteral<T> type)
    Creates a builder for producing a TypedGuard object representing a set of configured fault tolerance strategies that guard given type.
    static <T> TypedGuard.Builder<T>
    create(Class<T> type)
    Creates a builder for producing a TypedGuard object representing a set of configured fault tolerance strategies that guard given type.
    T
    get(Supplier<T> action)
    Calls given action and guards the call by this configured set of fault tolerance strategies.

  • Method Details

    • create

      static <T> TypedGuard.Builder<T> create(Class<T> type)
      Creates a builder for producing a TypedGuard object representing a set of configured fault tolerance strategies that guard given type. It can be used to execute actions using call(Callable) or get(Supplier).

      The given type is also used to determine if the guarded actions are synchronous or asynchronous. Casting to another type is not possible.

    • create

      static <T> TypedGuard.Builder<T> create(jakarta.enterprise.util.TypeLiteral<T> type)
      Creates a builder for producing a TypedGuard object representing a set of configured fault tolerance strategies that guard given type. It can be used to execute actions using call() or get().

      The given type is also used to determine if the guarded actions are synchronous or asynchronous.

    • 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 TypedGuard instance was created using a synchronous type, the action is synchronous and is always executed on the same thread that calls this method. If this TypedGuard instance was created using an asynchronous type, the action is asynchronous and may be offloaded to another thread depending on how the builder was configured.

      Throws:
      Exception

    • get

      T get(Supplier<T> action)
      Calls given action and guards the call by this configured set of fault tolerance strategies.

      If this TypedGuard instance was created using a synchronous type, the action is synchronous and is always executed on the same thread that calls this method. If this TypedGuard instance was created using an asynchronous type, 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: