Configuration

The fault tolerance strategies are primarily configured using annotations. This is convenient, but changing such configuration requires recompilation. For that reason, configuration using MicroProfile Config is also possible.

The configuration system of MicroProfile Fault Tolerance, as described in this guide, also applies to annotations defined by SmallRye Fault Tolerance.

Annotation on Method

The annotation may be present on a method:

package com.example;

@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).

To change the maxRetries property using MicroProfile Config, set:

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

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

Annotation on Class

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

package com.example;

@ApplicationScoped
@Retry(maxRetries = 10, retryOn = IOException.class) (1)
public class MyService {
    public String hello() {
        ...
    }
}
1 The hello() method will use the @Retry strategy, as configured in this annotation.

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

The MicroProfile Config configuration property doesn’t include the method name in this case:

smallrye.faulttolerance."com.example.MyService".retry.max-retries=5

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

Attempting to configure some property for a method or a class which does not have the annotation has no effect.

  • If the annotation is present on a method, the configuration property must target the method.

  • If the annotation is present on a class, the configuration property must target the class.

Global Configuration

It is also possible to reconfigure some property for all annotations in the application. For example:

smallrye.faulttolerance.global.retry.max-retries=5

# alternatively, a specification-defined property can be used
Retry/maxRetries=5

All @Retry annotations in the application will be considered to have maxRetries set to 5.

Configuration Priority

The most specific configuration has priority over more general configuration.

For example:

package com.example;

@ApplicationScoped
@Retry(maxRetries = 5)
public class MyService {
    public String simpleHello() {
        ...
    }

    @Retry(maxRetries = 10)
    public String complexHello() {
        ...
    }
}

The following configuration:

smallrye.faulttolerance.global.retry.max-retries=30
smallrye.faulttolerance."com.example.MyService".retry.max-retries=15
smallrye.faulttolerance."com.example.MyService/complexHello".retry.max-retries=20

# alternatively, specification-defined properties can be used
Retry/maxRetries=30
com.example.MyService/Retry/maxRetries=15
com.example.MyService/complexHello/Retry/maxRetries=20

Has the following effects:

  • MyService.complexHello() has maxRetries set to 20.

  • MyService.simpleHello() has maxRetries set to 15.

  • Other @Retry methods in the application have maxRetries set to 30.

Disabling Fault Tolerance

It is possible to disable certain fault tolerance annotation on some method, if the annotation is present on the method:

smallrye.faulttolerance."com.example.MyService/hello".retry.enabled=false

# alternatively, a specification-defined property can be used
com.example.MyService/hello/Retry/enabled=false

Or on some class, if the annotation is present on the class:

smallrye.faulttolerance."com.example.MyService".retry.enabled=5

# alternatively, a specification-defined property can be used
com.example.MyService/Retry/enabled=false

Or globally:

smallrye.faulttolerance.global.retry.enabled=5

# alternatively, a specification-defined property can be used
Retry/enabled=false

It is also possible to disable all fault tolerance completely:

smallrye.faulttolerance.enabled=false

# alternatively, a specification-defined property can be used
MP_Fault_Tolerance_NonFallback_Enabled=false

This will leave only fallbacks enabled, all other annotations will be disabled.

SmallRye Fault Tolerance Configuration Properties

As demonstrated in the examples above, SmallRye Fault Tolerance provides its own configuration properties, in addition to the specification-defined properties. The specification-defined properties can of course be used, but the SmallRye Fault Tolerance configuration properties have higher priority.

The mapping is relatively straightforward:

  • <classname>/<methodname>/<annotation>/<member> moves to smallrye.faulttolerance."<classname>/<methodname>".<annotation>.<member>

  • <classname>/<annotation>/<member> moves to smallrye.faulttolerance."<classname>".<annotation>.<member>

  • <annotation>/<member> moves to smallrye.faulttolerance.global.<annotation>.<member>

All the <annotation> and <member> parts are changed from camel case (BeforeRetry, methodName) to kebab case (before-retry, method-name). Two annotation members are special cased to improve consistency:

  • Retry/durationUnit moves to retry.max-duration-unit, because the value property is called maxDuration (max-duration)

  • Retry/jitterDelayUnit moves to retry.jitter-unit, because the value property is called jitter

Further:

  • MP_Fault_Tolerance_NonFallback_Enabled moves to smallrye.faulttolerance.enabled

  • MP_Fault_Tolerance_Metrics_Enabled moves to smallrye.faulttolerance.metrics.enabled

Links

Configuration is described in detail in the MicroProfile Fault Tolerance specification.