Package io.smallrye.faulttolerance.api

Interface Guard

@Experimental("second attempt at providing programmatic API")
public interface Guard

Allows guarding an action with various fault tolerance strategies: bulkhead, circuit breaker, rate limit, retry. and timeout. Synchronous as well as asynchronous actions may be guarded, asynchronous actions may optionally be offloaded to another thread. This interface doesn't support fallback; for that, use TypedGuard.

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() method 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: 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 Guard object and using a separate Guard object for each action. Using a single Guard 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 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	Guard.Builder	A builder for configuring fault tolerance strategies.

Method Summary

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

Method Details

create

static Guard.Builder create()

Creates a builder for producing a Guard object representing a set of configured fault tolerance strategies. It can be used to execute actions using call() or get().

call

<T> T call(Callable<T> action,
 Class<T> type)
    throws Exception

Calls given action, which returns given type, and guards the call by this configured set of fault tolerance strategies.

The given type is used to determine if the action is synchronous or asynchronous. If the action is synchronous, it is always executed on the same thread that calls this method. If the action is asynchronous, it may be offloaded to another thread depending on how the builder was configured.

Throws:

Exception

call

<T> T call(Callable<T> action,
 jakarta.enterprise.util.TypeLiteral<T> type)
    throws Exception

Calls given action, which returns given type, and guards the call by this configured set of fault tolerance strategies.

The given type is used to determine if the action is synchronous or asynchronous. If the action is synchronous, it is always executed on the same thread that calls this method. If the action is asynchronous, it may be offloaded to another thread depending on how the builder was configured.

Throws:

Exception

get

<T> T get(Supplier<T> action,
 Class<T> type)

Calls given action, which returns given type, and guards the call by this configured set of fault tolerance strategies.

The given type is used to determine if the action is synchronous or asynchronous. If the action is synchronous, it is always executed on the same thread that calls this method. If the action is asynchronous, it may be offloaded to another thread depending on how the builder was configured.

get

<T> T get(Supplier<T> action,
 jakarta.enterprise.util.TypeLiteral<T> type)

Calls given action, which returns given type, and guards the call by this configured set of fault tolerance strategies.

The given type is used to determine if the action is synchronous or asynchronous. If the action is synchronous, it is always executed on the same thread that calls this method. If the action is asynchronous, it may be offloaded to another thread depending on how the builder was configured.

adaptCallable

default <T> Callable<T> adaptCallable(Callable<T> action,
 Class<T> type)

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, type).

See Also:

• call(Callable, Class)

adaptCallable

default <T> Callable<T> adaptCallable(Callable<T> action,
 jakarta.enterprise.util.TypeLiteral<T> type)

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, type).

See Also:

• call(Callable, TypeLiteral)

adaptSupplier

default <T> Supplier<T> adaptSupplier(Supplier<T> action,
 Class<T> type)

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, type).

See Also:

• get(Supplier, Class)

adaptSupplier

default <T> Supplier<T> adaptSupplier(Supplier<T> action,
 jakarta.enterprise.util.TypeLiteral<T> type)

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, type).

See Also:

• get(Supplier, TypeLiteral)