Narayana LRA

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.

Table of Contents

• Prerequisites
• Building the Project
• Project Modules
• Running Integration Tests
• MicroProfile Fault Tolerance
• REST API
• Maven Profiles
• Documentation
• Further Reading
• License

Prerequisites

• JDK 17 or later

• Maven (version 3.9.x recommended or use the included Maven Wrapper ./mvnw)

Building the Project

Use the Maven Wrapper to build:

./mvnw clean install

Alternatively, use the build.sh script which configures sensible defaults:

./build.sh clean install

To skip tests during the build:

./mvnw clean install -DskipTests

To apply code formatting (enabled by default via the format profile):

./mvnw clean package -DskipTests

Project Modules

Module	Description
service-base	Shared functionality common to both the coordinator and clients
client	LRA client library for communicating with the coordinator
coordinator	Core LRA coordinator implementation — manages long running action lifecycle, state, and recovery
coordinator-war	WAR packaging of the coordinator for deployment on application servers
jaxrs	JAX-RS integration including filters, context providers, and request/response handling
proxy	Proxy API module for LRA proxy functionality
arquillian-extension	Arquillian test framework extension for deploying and testing LRA in managed containers
test	Integration tests — see test/README.adoc for details

Running Integration Tests

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,provision

To run a single test:

mvn clean verify -Parq,provision -pl :lra-test-basic -Dit.test=FailedLRAIT

To run against an existing WildFly installation:

export JBOSS_HOME=/path/to/wildfly
mvn clean verify -Parq

For more details on test configuration, profiles, and debugging options, see test/README.adoc.

MicroProfile Fault Tolerance

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.

REST API

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

Maven Profiles

Profile	Description
arq	Runs integration tests using Arquillian with WildFly
provision	Provisions a WildFly Galleon instance for testing
download	Downloads a WildFly zip distribution for testing
coordinator.wildfly.subsystem	Tests against the WildFly built-in LRA coordinator subsystem
release	Enables documentation, source, and javadoc packaging
codeCoverage	Enables JaCoCo code coverage reporting
debug	Enables JVM debugging on port 8787
findbugs	Runs SpotBugs static analysis
openapi-schema	Generates the OpenAPI schema for the coordinator REST API

Documentation

Additional documentation is available in the docs/ directory. To generate the HTML documentation:

cd docs
mvn clean generate-resources
# Output: docs/target/html/

Further Reading

• MicroProfile LRA Specification

• Narayana LRA Documentation

• REST API Versioning

• Contributing Guide

• Code of Conduct

License

This project is licensed under the Apache License 2.0.