How to Begin

Installation

As an application developer, you don’t have to "install" SmallRye Fault Tolerance in any way. Your chosen runtime, such as Quarkus or WildFly, already integrates SmallRye Fault Tolerance to provide MicroProfile Fault Tolerance. Please refer to the documentation of your selected runtime to understand how to enable MicroProfile Fault Tolerance.

Quarkus

In case of Quarkus, it is enough to add a dependency on io.quarkus:quarkus-smallrye-fault-tolerance.

See the SmallRye Fault Tolerance guide in Quarkus documentation for more.

WildFly

In case of WildFly, the MicroProfile Fault Tolerance subsystem must be enabled. It is not included in the default standalone or standalone-full profiles, but it is included in the standalone-microprofile profile. It is easiest to just start WildFly in this profile.

See the MicroProfile Fault Tolerance chapter in WildFly Admin Guide for more.

If you are a framework developer, interested in integrating SmallRye Fault Tolerance in your framework or runtime, please refer to the Integration section.

Usage

MicroProfile Fault Tolerance is built on top of CDI and interceptors. This lets you guard method calls with selected fault tolerance strategies simply by annotating a CDI bean class or method with one of the fault tolerance annotations. For example:

@ApplicationScoped (1)
public class MyService {
    @Retry (2)
    public String hello() {
        ...
    }
}

1	`@ApplicationScoped` is a bean defining annotation. It makes the `MyService` class a CDI bean.
2	`@Retry` is a fault tolerance annotation.

Here, if the hello method throws an exception, the invocation will be retried several times, until the method returns a value.

The annotation may also be present on a class, in which case it applies to all business method in the class:

package com.example;

@ApplicationScoped
@Retry (1)
public class MyService {
    public String hello() { (2)
        ...
    }
}

1	`@Retry` is a fault tolerance annotation.
2	The `hello()` method will use the retry strategy, because it is defined on the class.

A class-level annotation may be overridden by explicitly annotating a method.

CDI beginners often expect that this will work if you create an instance manually: new MyService(). That is not the case. You have to let the CDI container construct an instance for you and inject it: @Inject MyService service. What you get injected is actually a proxy that implements the additional behaviors.

The fault tolerance strategies present in MicroProfile Fault Tolerance, together with the corresponding annotations, are:

@Asynchronous: offload method execution to another thread
@Bulkhead: limit concurrent invocations
@CircuitBreaker: prevent invocations if previous invocations failed too often
@Fallback: provide alternative result in case of a failure
@Retry: retry several times in case of a failure
@Timeout: fail if the invocation takes too long

SmallRye Fault Tolerance adds some more fault tolerance strategies and annotations:

@ApplyGuard: apply a programmatically-defined guard
@AsynchronousNonBlocking: apply asynchronous fault tolerance without offloading method execution to another thread
@RateLimit: limit rate of method invocations

These are all described in the corresponding how-to and reference guides. The MicroProfile Fault Tolerance features are also described in the specification.

Configuration

The fault tolerance strategies can be configured using annotations, such as:

@ApplicationScoped
public class MyService {
    @Retry(maxRetries = 10, retryOn = IOException.class) (1)
    public String hello() {
        ...
    }
}

1	Retries will only be attempted if the thrown exception was `IOException`. Other exceptions will be rethrown directly. Also, the maximum number of retry attempts is changed to 10 (the default is 3).

This is convenient, but changing such configuration requires recompilation. For that reason, configuration using MicroProfile Config is also possible. For example:

smallrye.faulttolerance."com.example.MyService/hello".retry.max-retries=5 (1)

# alternatively, a specification-defined property can be used
com.example.MyService/hello/Retry/maxRetries=5 (1)

1	Even though the `@Retry` annotation says that `maxRetries` should be 10, this configuration takes precedence. The maximum number of retries will be 5.

Since this example configuration does not modify the retryOn setting, the configuration provided in the annotation still applies.

For more information about configuration, see the Configuration reference guide.