Eclipse MicroProfile Fault Tolerance API

Since 4.1.2.181; 5.181 

Provided version of the API: MicroProfile Fault Tolerance 3.0

Background

The Fault Tolerance API was created to help separate execution logic from execution. The execution can be configured with a number of fault tolerance policies.

A full overview for the reasoning behind the API can be found in the README for the source code repository.

Additions to the Fault Tolerance Spec

In addition to the functionality detailed in the spec, the following is also implemented in Payara Server Community and Payara Micro Community:

Configurable Executor Services

The managed and scheduled managed executor pool can be configured via the set-fault-tolerance-configuration asadmin command.

The executor service is used to execute methods annotated with @Asynchronous, whereas the scheduled executor service is used by the CircuitBreaker and Timeout interceptors for their timeout operations (scheduling the circuit breaker to be set to half open, and just timing out respectively).

Alternative @Asynchronous Annotations

Since 5.192 the Payara specific configuration property MP_Fault_Tolerance_Alternative_Asynchronous_Annotations can be used to specify a comma separated list of fully qualified class names of those annotations that should have the same effect as FT’s @Asynchronous. These annotations do not have to be interceptor bindings.

For example:

MP_Fault_Tolerance_Alternative_Asynchronous_Annotations=javax.ejb.Asynchronous

Annotation Priority

Prior to 5.192 the order that the fault tolerance annotations are invoked is as follows:

  • Fallback (SPECIAL CASE - you’ll ONLY get here if there is an exception kicking off the asynchronous thread)

  • Asynchronous

  • Fallback

  • Retry

  • Bulkhead

  • CircuitBreaker

  • Timeout

Since the asynchronous annotation is invoked first, if it’s combined with any other fault tolerance annotations they will be processed on the asynchronous thread.

Since 5.192 interactions between annotations are handled as described by the 2.0 specification effectively nesting computation in the following way (skipping handling for annotations not present):

  1. Asynchronous

  2. Fallback

  3. Retry

  4. Circuit Breaker

  5. Timeout

  6. Bulkhead

  7. (calling annotated method; might be wrapped by other interceptors)

As specified the interceptor priority can be changed using the property mp.fault.tolerance.interceptor.priority affecting all annotations including alternative ones.

Fault Tolerance Configuration

Fault Tolerance can be configured by using Admin Console or Asadmin commands.

Since 5.183 

Using the Admin Console

To configure the Fault Tolerance in the Admin Console, go to Configuration → [instance-configuration (like server-config)] → MicroProfile → Fault Tolerance:

Set Fault Tolerance Configuration

Using Asadmin Commands

On Payara Platform 5.2021.1, it is a known issue that the set-fault-tolerance-configuration command is broken and it can’t be used to configure user-defined executor to run the fault tolerance execution. To work around this issue, use the following set command to configure managed executor pool: asadmin set configs.config.server-config.microprofile-fault-tolerance-configuration.managed-executor-service and similar use the following command to configure scheduled managed executor pool: asadmin set configs.config.server-config.microprofile-fault-tolerance-configuration..managed-scheduled-executor-service. Finally, a server restart is required for the commands to take effect.

set-fault-tolerance-configuration

Usage
asadmin>set-fault-tolerance-configuration
  [--managedexecutorservicename=managedexecutorservicename]
  [--managedscheduledexecutorservicename=managedscheduledexecutorservicename]
  [--target=server-config]
Aim

Provides a way to set the configuration of the fault tolerance service of the targetted config.

Command Options
Since Payara Platform 5.2021.1, the options asyncmaxpoolsize and delaymaxpoolsize has been deprecated as they are no longer applicable because the default managed executor pools are being used.
Option Description Default Mandatory

managedexecutorservicename

The Logical JNDI name of the Managed Executor Service to look up. Changes to this configuration require a restart of the server to take effect.

java:comp/DefaultManagedExecutorService

no

managedscheduledexecutorservicename

The Logical JNDI name of the Managed Scheduled Executor Service to look up. Changes to this configuration require a restart of the server to take effect.

java:comp/DefaultManagedScheduledExecutorService

no

asyncmaxpoolsize

The maximum size of the thread pool used to run asynchronous execution. The dedicated executor will create threads dynamically on rising demand and dispose idle threads on falling demand. Changes to this configuration take effect without restart.

1000

no

delaymaxpoolsize

The maximum size of the executor used to schedule delays and detect timeouts as part of the Fault Tolerance execution. The dedicated executor is likely to use up to this number of threads. Changes to this configuration require a restart of the server to take effect.

20

no

target

The target Payara config to apply the change to

server (the DAS)

no
Example
asadmin> set-fault-tolerance-configuration --managedexecutorservicename=java:comp/DefaultManagedExecutorService --target instance1

get-fault-tolerance-configuration

Usage

asadmin> get-fault-tolerance-configuration [--target=server-config]

Aim

Returns the current configuration options for the Fault Tolerance service on the targetted config.

Command Options
Option Description Default Mandatory

target

The config to get the fault tolerance configuration for.

server-config

no
Example
asadmin> get-fault-tolerance-configuration --target=instance1