An implementation of the MicroProfile LRA specification. MicroProfile LRA provides an annotation-based API that enables loosely coupled services to coordinate long running activities in such a way as to guarantee a globally consistent outcome without the need to take long duration locks on data.
-
JDK 17 or later
-
Maven (version 3.9.x recommended or use the included Maven Wrapper ./mvnw)
Use the Maven Wrapper to build:
./mvnw clean installAlternatively, use the build.sh script which configures sensible defaults:
./build.sh clean installTo skip tests during the build:
./mvnw clean install -DskipTestsTo apply code formatting (enabled by default via the format profile):
./mvnw clean package -DskipTests| Module | Description |
|---|---|
|
Shared functionality common to both the coordinator and clients |
|
LRA client library for communicating with the coordinator |
|
Core LRA coordinator implementation — manages long running action lifecycle, state, and recovery |
|
WAR packaging of the coordinator for deployment on application servers |
|
JAX-RS integration including filters, context providers, and request/response handling |
|
Proxy API module for LRA proxy functionality |
|
Arquillian test framework extension for deploying and testing LRA in managed containers |
|
Integration tests — see test/README.adoc for details |
The coordinator URL path differs by runtime:
| Runtime | Coordinator URL |
|---|---|
WildFly WAR or subsystem |
|
Container (Quarkus) |
The simplest way to run the coordinator built from this branch. Build first, then deploy the WAR to any WildFly instance:
./mvnw clean install -DskipTests
export JBOSS_HOME=/path/to/wildfly
$JBOSS_HOME/bin/standalone.sh -c standalone.xml &
$JBOSS_HOME/bin/jboss-cli.sh -c \
"deploy --force coordinator-war/target/lra-coordinator.war"The download profile downloads WildFly, replaces all LRA module jars with the locally built SNAPSHOTs, and configures the LRA coordinator subsystem — all in one step:
./mvnw clean install -DskipTests
mvn process-test-classes -Pdownload -f test/pom.xml -N
export JBOSS_HOME=target/wildfly/wildfly-$(mvn help:evaluate \
-Dexpression=version.wildfly -q -DforceStdout -f test/pom.xml)
$JBOSS_HOME/bin/standalone.sh -c standalone-microprofile.xmlPre-built images are published at quay.io/jbosstm/lra-coordinator.
Tags follow the pattern <narayana-version>-<quarkus-version>. Use latest for the most recent release.
# Preferred — full network access so the coordinator can reach participant services
podman run --network host quay.io/jbosstm/lra-coordinator:latest
# Or with explicit port forwarding (limits outbound connectivity)
podman run -p 8080:8080 quay.io/jbosstm/lra-coordinator:latestThe coordinator is then available at http://localhost:8080/lra-coordinator.
The quarkus-narayana-lra extension makes a Quarkus service an LRA participant. It does not run a coordinator itself — add it to your participant application and point it at whichever coordinator is running:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-narayana-lra</artifactId>
</dependency># application.properties — adjust the URL to match the coordinator runtime
# WildFly: http://coordinator-host:8080/lra-coordinator/lra-coordinator
# Quarkus/container: http://coordinator-host:8080/lra-coordinator
quarkus.lra.coordinator-url=http://localhost:8080/lra-coordinatorUsing SNAPSHOT Narayana artifacts
quarkus-narayana-lra bundles its own narayana-lra version. To replace it with the SNAPSHOT from this repo, exclude the bundled jar and declare the local one:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-narayana-lra</artifactId>
<exclusions>
<exclusion>
<groupId>org.jboss.narayana.lra</groupId>
<artifactId>narayana-lra</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.jboss.narayana.lra</groupId>
<artifactId>narayana-lra</artifactId>
<version>${project.version}</version>
</dependency>Requires ./mvnw clean install -DskipTests first so the SNAPSHOT is in the local Maven repository.
Integration tests use the Maven Failsafe Plugin and Arquillian to spin up separate JVMs for the coordinator, participant, and test client.
To run all integration tests with a provisioned WildFly instance:
mvn clean verify -Parq,provisionTo run a single test:
mvn clean verify -Parq,provision -pl :lra-test-basic -Dit.test=FailedLRAITTo run against an existing WildFly installation:
export JBOSS_HOME=/path/to/wildfly
mvn clean verify -ParqFor more details on test configuration, profiles, and debugging options, see test/README.adoc.
The LRA coordinator implements MicroProfile Fault Tolerance strategies:
-
Bulkhead: Limits concurrent execution so that failures in one area cannot overload the whole system.
Fault tolerance variables (Bulkhead value and waitingTaskQueue) can be configured using the classname/annotation/parameter format in the microprofile-config.properties file.
See the Eclipse Fault Tolerance documentation for details.
The coordinator exposes a REST API. For details on API versioning, version negotiation via the Narayana-LRA-API-version header, and how to generate the OpenAPI schema, see API.adoc.
To generate the OpenAPI schema:
cd coordinator
mvn process-classes -Popenapi-schema| Profile | Description |
|---|---|
|
Runs integration tests using Arquillian with WildFly |
|
Provisions a WildFly Galleon instance for testing |
|
Downloads a WildFly zip distribution for testing |
|
Tests against the WildFly built-in LRA coordinator subsystem |
|
Enables documentation, source, and javadoc packaging |
|
Enables JaCoCo code coverage reporting |
|
Enables JVM debugging on port 8787 |
|
Runs SpotBugs static analysis |
|
Generates the OpenAPI schema for the coordinator REST API |
Additional documentation is available in the docs/ directory. To generate the HTML documentation:
cd docs
mvn clean generate-resources
# Output: docs/target/html/This project is licensed under the Apache License 2.0.