DEV Community: Nicolas DUMINIL

Spring AI or LangChain4j? One App, Three Stacks, One Test

Nicolas DUMINIL — Wed, 11 Nov 2026 12:33:52 +0000

Java has quietly become a credible place to build AI applications. That raises a practical question for anyone starting out: which framework do you reach for, Spring AI or LangChain4j, and does it matter whether you run
it on Spring Boot or on Quarkus?

The consistent way to answer is not a feature table. It is to build the same thing on each stack and read the difference. This article does exactly that for the smallest useful AI application: one HTTP endpoint that forwards a question to a model and returns its answer. We build it three times, in Spring AI, in LangChain4j on Spring Boot, and in LangChain4j on Quarkus, and then hold all three to a single shared test.

One interface, three implementations

Everything starts from one framework-neutral contract, a plain Java interface that knows nothing about any AI library:

public interface QuestionAnsweringService {
  Answer askQuestion(Question question);
}

Question and Answer are simple records. Each stack provides only its own implementation of this interface, and nothing framework-specific leaks into the shared code. So the only thing that varies between the three is how each one talks to the model.

Spring AI: a fluent ChatClient

@Service
public class SpringAiQuestionAnsweringService implements QuestionAnsweringService {

  private final ChatClient chatClient;

  public SpringAiQuestionAnsweringService(ChatClient.Builder chatClientBuilder) {
    this.chatClient = chatClientBuilder.build();
  }

  @Override
  public Answer askQuestion(Question question) {
    var answerText = chatClient.prompt()
      .user(question.question())
      .call()
      .content();
    return new Answer(answerText);
  }
}

Spring AI hands you a ChatClient.Builder, auto-configured from your properties, and a fluent API: prompt(), user(), call(), content(). The model, its base URL and its options are all configuration, not code.

LangChain4j: a plain ChatModel, and the same code on two runtimes

On Spring Boot:

@Service
public class LangChain4jQuestionAnsweringService implements QuestionAnsweringService {

  private final ChatModel chatModel;

  public LangChain4jQuestionAnsweringService(ChatModel chatModel) {
    this.chatModel = chatModel;
  }

  @Override
  public Answer askQuestion(Question question) {
    return new Answer(chatModel.chat(question.question()));
  }
}

LangChain4j hands you a ChatModel and a single method, chat(). There is no builder to call: the model is injected ready to use.

Now the Quarkus version:

@ApplicationScoped
public class LangChain4jQuestionAnsweringService implements QuestionAnsweringService {

  private final ChatModel chatModel;

  public LangChain4jQuestionAnsweringService(ChatModel chatModel) {
    this.chatModel = chatModel;
  }

  @Override
  public Answer askQuestion(Question question) {
    return new Answer(chatModel.chat(question.question()));
  }
}

Look closely. The body is identical to the Spring Boot version. The only difference is the annotation: @ApplicationScoped (CDI) instead of @Service (Spring). Same library, same ChatModel, same chat() call. The runtime changes, the code does not. That is precisely why it is worth running LangChain4j on both: it isolates what the framework costs from what the runtime costs.

One test to compare them all

Three implementations are only comparable if they are held to the same standard. Each stack's integration test extends one abstract test that talks to the running application over HTTP:

public abstract class AbstractQuestionAnsweringIT {

  protected abstract URI baseUri();

  @Test
  @DisplayName("answers a factual question")
  protected void answersAFactualQuestion() {
    ask()
      .body(new Question("What is the capital of France? Answer with the city name only."))
      .when()
      .post("/ask")
      .then()
      .statusCode(200)
      .body("answer", not(blankOrNullString()))
      .body("answer", containsStringIgnoringCase("paris"));
  }

  // ... plus: rejects a blank question (400), rejects a malformed payload (400)

  private RequestSpecification ask() {
    return given().baseUri(baseUri().toString()).contentType(ContentType.JSON);
  }
}

Two things matter here. First, the suite talks HTTP with REST Assured, never an in-process API, so the same test class can hold a Spring Boot application and a Quarkus application to the same standard: a subclass supplies only its base URI. Second, the assertion is semantic, not exact-string. It checks that the answer contains "paris", case-insensitively, because LLM output is non-deterministic even at temperature zero. Asserting on a literal completion would make the test lie.

The tests run against a local model in an Ollama container, started with Testcontainers, so there is no API key, no per-run cost, and the whole comparison is reproducible in CI.

What the comparison reveals

The three stacks are not the same size and do not start at the same speed. Counting only non-blank, non-comment lines of production Java:

	Spring AI	LangChain4j / Boot	LangChain4j / Quarkus
Production Java (LOC)	48	47	39
Files in `src/main/java`	3	3	2
Resolved runtime jars	106	49	142
Startup, JVM mode	1.74 s	2.69 s	0.66 s

The startup figures are medians of a handful of runs on a single machine, with the Ollama container already up so that only application boot is inside the window: they are indicative, not benchmarks. And the jar counts do not mean Quarkus is three times heavier than LangChain4j on Boot; it simply splits its runtime into many small artifacts. A fair comparison shows that Spring AI brings 106 jars while LangChain4j brings only 49 on the same runtime.
That's because Spring AI brings a JSON-schema generator, a tokenizer and Reactor along with it, none of which this use case touches.

Even hedged this way, the shape is clear: Quarkus produces the smallest module and starts fastest, Spring AI is compact in code but carries the most dependencies of the two libraries on Spring Boot (106 jars to LangChain4j's 49), and LangChain4j on Boot sits close to Spring AI, the same three files with a few extra jars for its starter.

Qualitatively, the differences are small but relevant:

Spring AI leads with a fluent, builder-based ChatClient, and configuration drives the model.
LangChain4j leads with a single ChatModel.chat() call, and the injected model is the whole surface.
Between Spring Boot and Quarkus, the LangChain4j code is identical except for the dependency-injection annotation, which tells you the runtime is the variable, not the library.

None of this is a verdict. The interesting output of a comparison like this is not a winner, it is the diff, and the diff is what tells you which framework fits the way your team already thinks.

Where this goes next

This is the smallest use case. The same method, build once per stack and grade with one shared test, carries all the way up: retrieval-augmented generation, conversational memory, tool calling, the Model Context Protocol, observability, security, and agents. Each one adds a capability and shows where the three stacks converge and where they diverge.

If you want the full treatment, it is the subject of my book, Java AI Frameworks, available on Leanpub with a free sample of the first two chapters, and on Amazon:

Using Anthropic evaluation to check Claude Code plugin efficiency

Nicolas DUMINIL — Tue, 10 Nov 2026 12:38:04 +0000

Context

A Claude Code skill is a Markdown document that the assistant loads when a task matches its description. A collection of skills, agents and hooks can be packaged as a plugin and distributed through a marketplace. Since the summer of 2026, my development environment has
relied on such a plugin for Java work, consisting in a set of: Spring Boot, Quarkus, Apache Camel and Jakarta EE agents and skills. This collection started as a small set of artifacts but, little by little, I extended it such that, after several months, it contained 43 files and 17,338 lines.

This raised a precise question: were the stack conventions provided by this plugin really contributing anything of measurable to the final outcome or could the model,by its intrinsic general knowledge, infer the same result, with much fewer tokens ?

This article describes how the question was answered thanks to the Anthropic evaluation tool, and what the measurements revealed about the skills and about the evaluation method itself.

A criterion for useful skill content

A skill contributes when it changes what the model produces. Four kinds of content satisfy that criterion:

Personal or team conventions, which the model has no means to infer.
Facts more recent than the model's training data, such as new versions and renamed artifacts.
Non-obvious pitfalls and the decisions that avoid them.
Corrections to guidance that is wrong elsewhere, including in upstream plugins.

Textbook material, such as the definition of an Enterprise Integration Pattern or the meaning of an HTTP status code, belongs to what the model already knows. Trying to provide this same knowledge in skills consumes between 5,000 and 8,000 tokens each time a skill loads. Additionally, the given skill might be outdated. For example, my files still referenced Spring Boot 3.2.1 months after the move to
Spring Boot 4.

Restructuring before measuring

The first step was to collect all the loose folders in ~/.claude, defining agents, skills and hooks, to remove the duplicates and to consolidate them in stand-alone plugins. The result is a marketplace named simplex-software that lists five plugins:

Plugin	Activation
`spring-boot-template`	per project
`quarkus-template`	per project
`java-extras`	user scope, every session
`camel`	per project
`jakarta-ee`	per project

The stack plugins take precedence on every conflict. java-extras holds personal rules, cross stack decisions, operational notes and a UserPromptSubmit hook that reminds the model, on every prompt, which skills apply to the detected stack. Activation per project
keeps stacks material out of the sessions that don't use them.

The measurement method

Claude Code provides claude plugin eval, an open source evaluation tool allowing you to test the pertinence of your skills, agents and plugins. For example, you might want to evaluate the efficiency of a given Claude Code plugin. In order to do that you need to define "test cases", that are execution scenarios that specify an input prompt, the required context or tools, and the logic or criteria for
determining success.

A case is a directory with a prompt and a set of graders. The harness runs each case with the plugin and without it, several times per arm, and reports the score difference. A case whose score difference stays near zero identifies a plugin which doesn't contribute much to the content, as the model is already able to produce the same result without it. Such a plugin has to be ablated because its skills add only tokens and nothing else.

Instead of creating new files in the project, each case asked Claude to provide the requested code and configuration directly in its answer. Therefore, they don't require a prepared sample project, write permission, etc. The graders examined the text of the answer. Each case combined three kinds of graders:

Regular expressions for the specific facts the skill claims. These cost nothing.
A judge model, Claude Haiku by default with three votes, for the overall correctness.
A tool_used grader that checks whether Claude invoked the skill through the Skilltool. It shows whether the plugin arm actually loaded the skill. It is excluded from the score, because the arm without the plugin has no skill to invoke and would fail it in every run, which would inflate the difference.

A case for the Camel plugin illustrates the format. The prompt file:

---
name: quarkus-route-test
tags: [camel, quarkus]
max_turns: 8
allowed_tools: [Skill, Read, Glob, Grep]
---

Quarkus 3 project using Camel Quarkus. A RouteBuilder defines route id `process-route` from `direct:process` to `kafka:processed-orders`. Write a test that verifies one message reaches the Kafka endpoint without a real Kafka broker being used for that endpoint. Include the Maven test dependencies.

Its regular expression grader, graders/test-artifact.md:

---
type: regex
pattern: "camel-quarkus-junit(?!5)"
match: contains
---

Uses camel-quarkus-junit, the successor of the deprecated camel-quarkus-junit5.

Its judge grader, graders/judge.md, whose body is the criterion the judge model applies to the answer:

---
type: llm
---

Pass only if ALL hold:
- test dependency is org.apache.camel.quarkus:camel-quarkus-junit (not camel-quarkus-junit5)
- test extends CamelQuarkusTestSupport, overrides isUseAdviceWith() to return true, advises route "process-route" (mockEndpoints / mockEndpointsAndSkip) and then starts the context
- does not use @MockEndpoints (not available in Camel Quarkus)
- no Thread.sleep

Its skill indicator, graders/skill-fired.md, which passes when Claude loads a skill whose name contains camel:

---
type: tool_used
tool: Skill
input_match: "camel"
---

Indicator only: the plugin skill was loaded.

The command runs every case of a plugin, three runs per arm, with a cost ceiling:

claude plugin eval . -j 3 --no-publish --max-cost-usd 5

First results

Ten cases covered the three own plugins. The table reports the mean score with the plugin, without it, and the difference. Two scores are corrected for grader defects described in the next section.

Plugin	Case	With	Without	Difference
camel	Camel Quarkus route test	1.00	0.33	+0.67
camel	Spring Boot route unit test	1.00	0.33	+0.67
camel	Spring Boot Kafka integration test	1.00	0.92	+0.08
jakarta-ee	integration test on WildFly	0.89	0.33	+0.56
jakarta-ee	pom setup	equal	equal	0
jakarta-ee	resource, service and injection	equal	equal	0
java-extras	CircleCI with Testcontainers	1.00	0.33	+0.67
java-extras	graceful shutdown on Kubernetes	1.00	0.50	+0.50
java-extras	Spring Boot to Quarkus migration	1.00	0.89	+0.11
java-extras	Reactor to Mutiny translation	0.56	0.67	about 0

The cases with a large difference show that the plugin had a consistent contribution to the final result. In the case of Camel, for example, without the plugin the model estimated the Maven artifact version as 4.18.0, whereas the skill states 4.23.0, built on Spring Boot 4.1.1. It also selected the test artifacts
camel-test-spring-junit6 instead of camel-quarkus-junit with the skill. For CircleCI it chose a plain Docker executor, which offers no Docker daemon to Testcontainers. For graceful shutdown it omitted the arithmetic that relates the preStop delay, the application shutdown timeout and terminationGracePeriodSeconds.

The cases with a difference near zero show the opposite pattern. The Reactor to Mutiny cheat sheet, the Jakarta EE pom and the CDI constructor injection rules describe knowledge the model already applies correctly. Reading the answers confirmed it: both arms produced the same code.

Trimming, and the regression the evaluation caught

The trimming pass removed the content with a difference near zero and reduced the rest to facts, decisions and pitfalls. The Reactor to Mutiny section disappeared. The Spring Boot to Quarkus table kept only the rows where a mistake is likely, the Jakarta EE setup became a short list of facts and The Camel Kafka test skeleton became one sentence.

The second run, performed after the trimming, confirmed that every case with a large difference kept a score of 1.00 with the plugin. Only the migration from Spring Boot to Quarkus case declined from 1.00 to 0.78 but part of the decline came from judge noise. However, a part was genuine: the shortened table row stated that the Quarkus @Transactional annotation has no readOnly attribute, which determined the model to mistakenly remove the read only behavior of the original method. Without the skill, the model preserved it through a read only Hibernate session.

The corrected rule prescribes that the intended behavior should be achieved via a read only Session with FlushMode.MANUAL, or a org.hibernate.readOnly query hint. A third run of that case, judged by Claude Sonnet with a criterion that checks the read only behavior, passed six runs out of six. The episode is the strongest argument for the evaluation: a detail that appeared harmless changed the generated code, and only the measurement detected it.

Final state and cost

Measure	Before	After
Agent and skill files	43	6
Lines of agent and skill content	17,338	638
Tokens added to every session	about 2,100	about 520, plus about 150 for each optional plugin enabled in the project
Evaluation cases	none	6, each with a measured difference

The complete exercise, including the exploratory run, both full runs and the verification run, cost about 20 US dollars in model usage. A full run of the remaining suite costs about 6 dollars and takes about five minutes with three parallel runs.

Lessons

The useful content of a skill is narrow: versions, renamed artifacts, corrections and non-obvious conventions. Explanations of well known frameworks contribute nothing measurable.
An evaluation with and without the plugin is inexpensive and decisive. It replaces a debate about relevance with a number per case.
Graders require the same scrutiny as the skills and a small judge model is inconsistent on long answers.
A reduction of content is a change like any other and deserves a regression test. The readOnly episode demonstrates it.

Limitations

Each arm ran three times, which indicates a direction rather than a statistically established effect. The results describe one model at one date. Here, our Camel plugin pinned the 4.23 version which a later model may know without assistance. This is precisely why the suite should run again after each model change. The cases reflect one developer's projects, and the personal rules in house-rules were deliberately left out of the evaluation, since the model has no means of guessing them.

Time-Based One-Time Passwords with HashiCorp Vault and Quarkus

Nicolas DUMINIL — Fri, 30 Oct 2026 16:51:22 +0000

Abstract

This article examines how the Time-Based One-Time Password algorithm (TOTP) can be delegated to the TOTP secrets engine of HashiCorp Vault and consumed by a Quarkus application. It first recalls the theoretical foundations of TOTP and the purpose of Vault. It then describes the use cases of the reference implementation with a UML diagram, analyses the Vault configuration and its bootstrap script, comments on the Java code and its integration tests, and finally presents the deployment topology defined by Docker Compose.

1. What is TOTP and what problem does it solve?

1.1 The weakness of the static password

The static password is the oldest and most widely deployed authentication mechanism in computing. It is also among the most fragile. A password is a shared secret that never changes unless its owner decides otherwise, which in practice means rarely. Once it is captured by phishing, keylogging, database leakage or simple observation over the shoulder, it remains valid for an indefinite period, and the legitimate owner usually has no indication that it has been compromised. The problem is aggravated by the well documented human tendency to reuse the same password across many services, so that the compromise of a modest forum may lead to the
compromise of a bank account. One could say that the static password is a key that its owner copies generously and then leaves under a great number of doormats.

Strictly speaking, the defect does not reside in the password as such but in the fact that it is frequently the only proof of identity required. Whoever holds the password is, from the point of view of the system, the legitimate user, and a single theft is therefore sufficient to usurp an identity.

1.2 Multi-factor authentication

The classical remedy does not consist in abolishing the password, which remains convenient,inexpensive and universally understood, but in depriving it of its exclusive status. The user is required to present several proofs belonging to distinct categories, called authentication factors, which are commonly classified as follows:

something the user knows, such as a password or a PIN;
something the user possesses, such as a smartphone or a hardware token;
something the user is, such as a fingerprint.

The strength of the approach lies in the independence of these categories. The techniques that capture a password, such as phishing or the leakage of a database, do not provide the attacker with a physical device, and the theft of a device does not reveal what its owner knows.

The Time-Based One-Time Password algorithm (TOTP) is a widely adopted means of implementing the second category. At the moment of enrollment, the server generates a random secret, called the
seed, and transmits it once to the user, generally as a QR code scanned with an authenticator application installed on a smartphone. From then on, the application and the server each derive from this seed and from the current time a short numeric code, typically of six digits, which changes every thirty seconds. To authenticate, the user submits the code currently displayed together with the password, and the server accepts it only if it matches the code computed on its side. The possession of the device holding the seed thus becomes a necessary condition for authentication, so that the knowledge of the password alone is no longer sufficient. The mathematical details of this computation are the subject of section 1.3.

When a password is combined with TOTP, an attacker must consequently succeed in two attacks of a different nature against the same person:

obtaining the password, which is usually achieved remotely and on a large scale, by means of a fraudulent login page (phishing), a keylogger installed on the workstation, or the reuse of credentials published after the leakage of another service's database (credential stuffing);
obtaining the seed or the device that holds it, which requires either the physical theft of an unlocked smartphone, the installation of malware on that particular smartphone, or the interception of the QR code during the brief moment of enrollment.

The first attack can be conducted against millions of victims at once from the other side of the world, whereas the second must generally be directed at one specific person and one specific device. Combining them is considerably more difficult than succeeding in either one, and this difference of scale is the essence of the protection. It also explains why TOTP is preferable to codes sent by SMS, whose second factor can be diverted remotely by persuading a mobile operator to transfer the victim's number to a new SIM card (SIM swapping). The password thus ceases to be the weak point of the system and becomes merely one of its two locks. Section 1.3 mentions the notable exception of real-time phishing, in which a single fraudulent page collects both the password and a fresh code and relays them immediately.

It may be observed, not without some irony, that the code produced by the device is itself a kind of password. It differs from the static one, however, in every property that made the latter fragile, since it is generated rather than chosen, changes every thirty seconds, cannot be reused and is never memorized, let alone copied under a doormat.

1.3 The algorithm

TOTP is specified by RFC 6238 and is a direct extension of the HMAC-Based One-Time Password algorithm (HOTP) defined in RFC 4226. HOTP computes a short numeric code from a shared secret K and a counter C according to the following steps:

compute HMAC-SHA1(K, C), which yields a 20 byte value;
apply the so-called dynamic truncation, which uses the four lowest bits of the last byte as an offset in order to extract 31 bits from the HMAC value;
reduce the resulting integer modulo 10^d, where d is the number of digits, usually 6.

The difficulty of HOTP lies in the synchronization of the counter between the client and the server. TOTP removes this difficulty in an elegant manner by replacing the counter with a value that both parties already share without any communication, namely the current time. The counter becomes

T = floor((CurrentUnixTime - T0) / X)

where T0 is the origin of time (usually the Unix epoch) and X is the time step, 30 seconds
by default. The one-time password is then simply HOTP(K, T).

The consequences of this construction are noteworthy:

each code is valid only during a short time window, so that an intercepted code rapidly loses any value for an attacker;
the device that generates the codes needs no network connection, since it only needs the seed and a reasonably accurate clock;
the seed is transmitted only once, at enrolment time, usually through a QR code encoding an otpauth:// URI;
the server must tolerate a small clock drift, which is achieved by also accepting the codes of the adjacent time steps (the so-called skew).

TOTP does not eliminate every threat. A real-time phishing proxy may still relay a fresh code within its validity window, and the seed itself must be protected with the utmost care on the server side. This last point is precisely the reason for introducing Vault into the picture.

2. What is HashiCorp Vault and what is it used for?

HashiCorp Vault is a secrets management system. Its purpose is to store, generate, distribute and revoke sensitive material such as passwords, API keys, certificates and encryption keys, so that this material does not end up scattered across configuration files, environment variables and source code repositories. Every access to Vault is authenticated by a token or by an authentication method, is authorised by policies expressed in the HashiCorp Configuration Language (HCL), and may be recorded by an audit device.

Vault organizes its functionalities in pluggable components called secrets engines, each of them mounted at a path of a virtual file system. Among the most frequently used engines are the following:

the key/value engine, which stores arbitrary static secrets;
the database engine, which generates short-lived database credentials on demand;
the PKI engine, which acts as a certification authority;
the transit engine, which offers encryption as a service;
the TOTP engine, which is the subject of this article.

The TOTP engine can play two roles. In the role of a generator, Vault creates the seed, returns a QR code that the user scans with an authenticator application, and later validates the codes submitted by the user. In the role of a provider, Vault receives an existing seed and generates codes on behalf of a client. The present project uses the first role. Its essential benefit is that the seed never leaves Vault after enrollment, and that the application never stores it,
never sees it again and therefore cannot leak it. An application that knows nothing can reveal nothing, which is a principle of security that is far older than computing and has been practised with great success by generations of discreet butlers.

A security-minded reader will notice an apparent paradox. The seed is protected by Vault, but Vault itself requires a secret to be opened. This is solved by the seal mechanism. At startup, the Vault storage is encrypted and Vault is said to be sealed. It must be unsealed by providing a number of key shares produced by Shamir's secret sharing algorithm before it can serve any request. Section 4 shows how this procedure is automated, in a deliberately simplified form,for local development.

3. Use cases

The following diagram presents the actors of the system and the use cases in which they participate, together with their pre-conditions and post-conditions.

The PlantUML source of this diagram is available in diagrams/use-case.puml.

The operator intervenes only once, by starting the stack, after which the bootstrap is fully automated. The end user performs the enrollment and then the authentication, whereas the authenticator application and Vault participate as secondary actors. It is worth noting that the authenticator application and Vault never communicate with each other. They are like two correspondents who agreed on a secret at their only meeting and who, from that day on, prove their acquaintance merely by consulting their watches.

4. Vault configuration

The Vault configuration consists of three files located in the vault/config directory, which is mounted read-only in the containers.

4.1 The server configuration in `vault.hcl`

storage "file" {
  path = "/vault/file"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = 1
}

api_addr      = "http://0.0.0.0:8200"
disable_mlock = true
ui            = true

The storage stanza selects the file storage back-end, which persists the encrypted data of Vault in the /vault/file directory. This directory is backed by the Docker volume vault-file, so that the registered TOTP keys survive the restarts of the container. This
choice is deliberate. Vault also offers a development mode, as does the Quarkus Dev Services mechanism, but both are kept entirely in memory and forget everything when stopped. Such amnesia is acceptable in a test but rather inconvenient for a user who has just scanned a QR code and who would discover at the next restart that the application has no recollection of the enrollment.

The listener stanza opens a TCP listener on all network interfaces on port 8200. The tls_disable directive switches off TLS, which simplifies local development and which would be an unforgivable sin in any other context.

The api_addr parameter defines the address advertised by the server to its clients, in particular for request forwarding in a cluster. With a single node its role is modest.

The disable_mlock parameter prevents Vault from calling the mlock system call, whose purpose is to forbid the operating system to swap memory pages containing secrets to disk. Since containers generally lack the IPC_LOCK capability, this protection is disabled here. In a production deployment it should be kept enabled and the capability should be granted.

Finally, ui = true activates the web interface, available at http://localhost:8200/ui, which is convenient for inspecting the state of the server.

4.2 The access policy in `totp-policy.hcl`

path "totp/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

Vault applies a deny by default model. A token can perform only the operations explicitly granted by the policies attached to it. The totp-policy policy grants the application the capabilities create, read, update, delete and list on every path below totp/, and nothing else. The application can therefore create keys (totp/keys/<name>), generate codes and validate them (totp/code/<name>), but it can neither read the key/value secrets of other
teams nor alter the configuration of Vault. This is a direct application of the principle of least privilege. A more restrictive policy is conceivable, for example by removing delete and list if the application never needs them, and the reader is invited to apply such pruning in a real deployment.

4.3 The bootstrap script `init.sh`

The script is executed by the one-shot container vault-init. Its main property is idempotence, in other words it can be executed any number of times and always leads to the same final state. It proceeds in six stages.

Waiting for the server.

until vault status 2>&1 | grep -qE 'Initialized|Sealed'; do
  sleep 1
done

The depends_on clause of Docker Compose only guarantees that the vault container has been started, not that the Vault process is ready to answer. The script therefore polls the vault status command until its output contains the expected fields. One may observe that the command returns a non-zero exit code when Vault is sealed, which is why the script examines the output rather than the exit code.

Initialisation.

if [ ! -s /init/init.json ]; then
  vault operator init -key-shares=1 -key-threshold=1 -format=json > /init/init.json
fi

The initialization creates the master encryption key, splits it into key shares and produces the initial root token. It is performed only once, when the file /init/init.json does not exist or is empty. In production, the master key is typically divided into five shares with a threshold of three, entrusted to different persons who are expected never to travel on the same aircraft. Here, one share and a threshold of one are sufficient, and the result is stored in clear in the vault-init volume. The script comment explicitly warns that this arrangement is acceptable only for local development.

Unsealing.

UNSEAL_KEY=$(jq -r '.unseal_keys_b64[0]' /init/init.json)
ROOT_TOKEN=$(jq -r '.root_token' /init/init.json)

if vault status -format=json | jq -e '.sealed == true' >/dev/null; then
  vault operator unseal "$UNSEAL_KEY" >/dev/null
fi

With the file storage, Vault is sealed again after each restart. The script extracts the unseal key and the root token with jq, which is installed on the fly by the container entry point, and unseals the server only if it is actually sealed.

Enabling the TOTP engine.

export VAULT_TOKEN="$ROOT_TOKEN"

if ! vault secrets list -format=json | jq -e 'has("totp/")' >/dev/null; then
  vault secrets enable totp
fi

Authenticated with the root token, the script mounts the TOTP secrets engine at its default path totp/, unless it is already mounted.

Writing the policy.

vault policy write totp-policy /vault/config/totp-policy.hcl

This command is naturally idempotent, since writing an identical policy twice leaves it unchanged, and it also guarantees that any modification of the HCL file is taken into account at the next start.

Creating the application token.

if ! vault token lookup dev-app-token >/dev/null 2>&1; then
  vault token create -id="dev-app-token" -policy="totp-policy" \
    -orphan -no-default-policy -period="8760h" -display-name="vault-auth" >/dev/null
fi

This last stage deserves a closer look, since each option carries a precise meaning:

-id="dev-app-token" imposes a known token value, so that the application can be configured statically, which is convenient for development and strongly discouraged elsewhere;
-policy="totp-policy" attaches the least-privilege policy described above;
-no-default-policy removes the default policy, which would otherwise grant a few additional capabilities, such as looking up the token itself;
-orphan detaches the token from its parent, the root token, so that a revocation of the latter does not revoke the application token in cascade;
-period="8760h" makes the token periodic, which means that it has no maximum lifetime and remains valid as long as it is renewed at least once a year;
-display-name="vault-auth" gives the token a readable name in the audit logs.

The application thus receives a token that can do exactly what it needs and nothing more,
which is the ideal relationship between a software component and its privileges, and which
is, regrettably, far less frequent in practice than in textbooks.

5. The application code

The vault-auth module is a Quarkus 3.37 application built with Quarkus REST and the Quarkiverse quarkus-vault extension. Its configuration, in application.properties, is minimal, as shown below.

quarkus.vault.devservices.enabled=false
quarkus.vault.url=http://localhost:8200
quarkus.vault.authentication.client-token=dev-app-token

The Dev Services are disabled for the reason given in section 4.1. The URL and the token designate the Vault server started by Docker Compose and are overridden by the environment variables QUARKUS_VAULT_URL and QUARKUS_VAULT_AUTHENTICATION_CLIENT_TOKEN when the application runs in its own container.

5.1 The service `TotpService`

@ApplicationScoped
public class TotpService
{
  private VaultTOTPSecretEngine vaultTOTPSecretEngine;

  public TotpService(VaultTOTPSecretEngine vaultTOTPSecretEngine)
  {
    this.vaultTOTPSecretEngine = vaultTOTPSecretEngine;
  }

  public Optional<KeyDefinition> getTotpKeyDefinition(String username)
  {
    CreateKeyParameters params = new CreateKeyParameters("totp-test", username);
    params.setExported(true);
    return vaultTOTPSecretEngine.createKey(username, params);
  }

  public boolean validateCode(String username, String code)
  {
    return vaultTOTPSecretEngine.validateCode(username, code);
  }
}

The class is an application scoped CDI bean, which means that a single instance is shared by all requests. Its only dependency, VaultTOTPSecretEngine, is supplied by the quarkus-vault extension and is injected through the constructor, which makes the dependency explicit and the class easy to instantiate in isolation.

The method getTotpKeyDefinition() creates a TOTP key in Vault. The two-argument constructor of CreateKeyParameters sets the issuer (totp-test), which the authenticator application displays as the name of the service, and the account name, here the user name. This constructor also sets the generate flag to true, which places Vault in its generator role. Vault therefore creates the seed itself instead of expecting one from the caller. The call to setExported(true) asks Vault to return the provisioning material, namely the otpauth:// URL and the QR code as a Base64 encoded PNG image. The key is stored under the path totp/keys/<username>, so that each user owns a distinct key, and a new registration under the same name replaces the previous key.

The period, the algorithm and the number of digits are deliberately left to their default values,namely 30 seconds, SHA1 and 6 digits. This apparent lack of ambition is the result of experience. During the development of the project, the period was initially set to one minute.
The QR code correctly announced a period of 60 seconds, the authenticator application accepted it without any objection, and every single code was then rejected. The explanation is that Google Authenticator ignores the period, algorithm and digits parameters of the URI and always uses the standard values. The application thus faithfully produced codes for a clock that ticked twice as often as the one of Vault. The comment in the source code preserves this lesson for posterity, and the author recommends it to any reader tempted by originality in this domain.

The method validateCode() delegates the verification to Vault, which recomputes the expected code for the current time step and its neighbors and compares it with the submitted one. Vault also records the codes already used and rejects a second submission of the same code within its validity window, which protects the application against replay attacks at no cost. The method returns a simple boolean, and the application never manipulates the seed.

5.2 The resource `TotpApi`

@Path("/totp")
public class TotpApi
{
  @Inject
  TotpService totpService;

  @GET
  public Response testTotp(@HeaderParam("X-User") String username,
                           @HeaderParam("X-TOTP-Code") String code)
  {
    return totpService.validateCode(username, code) ? Response.ok("Access granted").build() :
      Response.status(Response.Status.UNAUTHORIZED).entity("Invalid TOTP code").build();
  }

  @GET
  @Path("/register/{username}")
  @Produces(MediaType.TEXT_HTML)
  public String register(@PathParam("username") String username)
  {
    return totpService.getTotpKeyDefinition(username)
      .map(key -> """
        <!DOCTYPE html>
        <html>
            <head><title>Scan QR Code</title></head>
            <body>
                <h2>Scan this QR code with Google Authenticator</h2>
                <img src="data:image/png;base64,%s" alt="TOTP QR Code"/>
            </body>
        </html>
        """.formatted(key.getBarcode()))
      .orElse("Failed to generate TOTP key");
  }
}

The class is a Jakarta REST resource bound to the path /totp and exposes two endpoints.

The endpoint GET /totp/register/{username} performs the enrollment. It obtains the key definition from the service and, if it is present, inserts the Base64 encoded image returned by getBarcode() into a small HTML page by means of a Java text block and the formatted()
method. The image is embedded as a data: URI, so that the browser can display it without any additional request. If the key definition is absent, a short failure message is returned.

The endpoint GET /totp performs the authentication. The user name and the code are read from the custom headers X-User and X-TOTP-Code. A valid code produces the status 200 and the body Access granted, whereas an invalid one produces the status 401 and the body
Invalid TOTP code.

The reader should keep in mind that this resource is a demonstration and not an authentication service ready for production. The registration endpoint is not protected, so that anybody who knows a user name may replace the key of that user, and the absence of a header is not handled specifically. In a real system, enrollment would occur only after a first authentication, for example by password, and the successful validation of the code would lead to the issuance of a session or of a token, typically through the Quarkus OIDC or JWT extensions. These additions are left as an exercise, according to the venerable academic tradition which consists in calling "exercise" what the author did not have the time to write.

5.3 The integration tests

In accordance with the conventions of the project, the tests are integration tests executed against a real Vault server rather than unit tests based on mocks. Two classes are involved.

VaultTestResource implements the QuarkusTestResourceLifecycleManager interface, which allows Quarkus to start an external resource before the application and to stop it afterwards.

@Override
public Map<String, String> start()
{
  vault = new VaultContainer<>(IMAGE)
    .withVaultToken(ROOT_TOKEN)
    .withInitCommand("secrets enable totp");
  vault.start();
  return Map.of(
    "quarkus.vault.devservices.enabled", "false",
    "quarkus.vault.url", vault.getHttpHostAddress(),
    "quarkus.vault.authentication.client-token", ROOT_TOKEN);
}

The method starts a Testcontainers VaultContainer based on the image hashicorp/vault:1.18, which is the same version as in Docker Compose. The method asCompatibleSubstituteFor("vault")informs Testcontainers that the official HashiCorp image may be used in place of the historical vault image it expects. The container runs in Vault development mode with the root token root, and the init command mounts the TOTP engine. The returned map overrides the application configuration, so that the application under test connects to this ephemeral server on its randomly mapped port instead of the persistent one. Here, the ephemeral nature that was a defect
in section 4.1 becomes a virtue, since each test run starts from a perfectly clean state.

TotpApiTest is annotated with @QuarkusTest, which starts the complete application, and with @WithTestResource(VaultTestResource.class), which attaches the resource described above. It contains three test cases written with REST Assured:

registerReturnsQrCode() is a positive test which calls /totp/register/alice and verifies that the response has the status 200 and contains an embedded PNG image;
validCodeGrantsAccess() is a positive test which registers bob, then asks Vault itself to generate the current code by means of generateCode("bob"), and verifies that submitting this code yields the status 200 and the message Access granted;
invalidCodeIsRejected() is a negative test which registers carol, submits the code 000000 and verifies the status 401 and the message Invalid TOTP code.

The second test is particularly instructive. Since no smartphone could reasonably be attached to the build server, the test injects VaultTOTPSecretEngine and lets Vault play the role of the authenticator application. This is possible because the key was created in generator mode, in which Vault is able to compute the current code for its own keys. The third test relies on the fact that 000000 is a valid code with a probability of one in a million for any given time step. Should this test ever fail, the author recommends not correcting it but rather buying a lottery ticket on the same day.

The tests are executed by mvn -pl vault-auth -am test on any workstation with a running Docker daemon, and by the CircleCI pipeline, which uses a machine executor precisely so that
Testcontainers has access to a Docker engine.

6. Deployment

The file docker-compose.yml defines three services, two named volumes and one bind mount. The following diagram represents this topology.

The PlantUML source of this diagram is available in diagrams/deployment.puml.

The service vault runs the Vault server with the configuration of section 4.1. It publishes port 8200 on the host, stores its encrypted data in the volume vault-file and is restarted automatically unless it is explicitly stopped.

The service vault-init uses the same image, runs as root in order to be able to install jq and to write in its volume, executes the script init.sh and then terminates. Its restart policy is no, which is the expected behavior of a one-shot task. Its volume vault-init keeps the file init.json between executions, which is what makes the automatic unsealing possible after a restart.

The service vault-auth runs the Quarkus application, whose image is produced by the Quarkus container image extension during the Maven build. The pull_policy: never clause indicates that the image must exist locally and must not be searched for in a registry. The application starts only once vault-init has completed successfully, which guarantees that Vault is unsealed, that the TOTP engine is mounted and that the token dev-app-token exists at the moment of the first request. Inside the Compose network, the application reaches Vault by its service name, vault, through the environment variable QUARKUS_VAULT_URL.

The whole stack is started by the following commands.

mvn -pl vault-auth -am package -Dquarkus.container-image.build
docker compose up -d

After that, the user opens http://localhost:8080/totp/register/<username>, scans the QR code and checks a code with

curl -H "X-User: <username>" -H "X-TOTP-Code: <code>" http://localhost:8080/totp

The command docker compose down -v removes the volumes and returns the system to its original state of blissful ignorance.

7. Conclusion

This project shows that the implementation of a second authentication factor based on TOTP requires remarkably little application code once the cryptographic responsibilities are delegated to Vault. The Quarkus application contains two short classes and never stores a seed. Vault generates the keys, produces the QR codes, validates the codes and prevents their reuse, while the policy and the periodic orphan token restrict the application to the strict minimum. The integration tests, executed against a real Vault container, give a high degree of confidence in this collaboration without resorting to mocks.

The simplifications adopted for local development, namely the single unseal share stored in clear, the disabled TLS, the fixed token value and the unprotected registration endpoint, must of course be removed before any production use. With this reservation, the approach offers a sound basis on which an authentication service may be built, and the author hopes that the reader, having reached this conclusion without falling asleep, will consider this a valid proof of presence, comparable in rigor to a six digit code.

Distributed Transactions in Enterprise Applications: From X/Open to MicroProfile LRA

Nicolas DUMINIL — Thu, 22 Oct 2026 14:25:11 +0000

Abstract

The problem of making several independent systems agree on a single outcome is
older than most of the technology used to solve it. Historically, one of the
first protocols able to provide this synchronization was 2PC (two-phase commit)
that the application servers era made an ordinary feature of enterprise development.
Later lightweight frameworks, service-oriented and microservices architectures
have made the same guarantee considerably harder to obtain.

This article follows that problem from its formalization in the X/Open Distributed
Transaction Processing to the present situation. It then examines two working
implementations of an identical use case, one using XA and two-phase commit, the
other using the saga pattern, as specified by MicroProfile LRA, and compares them
on evidence rather than on preference. The accompanying source code is available
in the quarkus-distributed-tx
repository, where both implementations expose the same REST contract and are
exercised by the same test suite.

1. Origins: X/Open, and the Formalization of 2PC

The 2PC protocol is older than the standard that made it famous. Its
essential shape appears in the database literature of the late 1970s, notably in
the work of Jim Gray on the recovery and consistency properties of database
operating systems. The problem it addresses is easy to state and difficult to
solve: several parties must all either perform or decline an action. And they
must do that despite the possibility that any of them, including the party
conducting the negotiation, may fail at any moment.

As its name states, the protocol proceeds in two phases. In the first, the
coordinator asks every participant whether it is able to commit. A participant
that answers affirmatively cannot retract itself. It must have
written enough durable state to guarantee that it can still commit even after
a crash. In the second phase, the coordinator informs the participants of the
collective decision, which is affirmative only if every vote was affirmative.

In early '90s, the X/Open consortium decided to contribute by formalizing a reference
model named DTP (Distributed Transaction Processing). This model identified
three roles namely the application program, the transaction manager and the
resource manager. The following two interfaces have been defined:

the TX (Transaction Demarcation) interface governs how an application demarcates a transaction;
the XA (eXtended Architecture) interface defines how the transaction manager drives the resource manager through the phases of the commit.

Once the XA specifications existed, a transaction manager written by one
vendor could coordinate a database written by another, and the industry acquired
a genuinely portable mechanism for distributed atomicity.

Let's note a property of the XA specifications that will become important
later. Between the moment a participant votes to commit and the moment it learns
the collective decision, it is blocked. It holds its locks, it cannot proceed,
and it cannot unilaterally decide. If the coordinator fails during this interval,
the participant waits. Skeen and others demonstrated in the early '80s that this
blocking behavior is not an artifact of a careless design but a logical consequence
of the quorum-based model which tolerates partitions only by blocking whenever no
quorum can be assembled. In 1985, Fischer, Lynch and Paterson published the article
Impossibility of Distributed Consensus with One Faulty Process which establishes
that deterministic consensus cannot be guaranteed in an asynchronous system in
which even one process may fail.

Because of this vulnerability 2PC was considered in the beginning a flawed protocol
that needed improvements. It took some time and experience to understand that,
on the opposite, it's an exact trade-off between perfect atomicity and availability.

2. Several Decades of Service

It would be reasonable to expect that a protocol with a documented blocking
failure mode and a known vulnerability would have been superseded. It has not
been. 2PC remains the most widely deployed mechanism for distributed atomicity
in enterprise systems, and it is likely to remain so for some time.

The explanation is that the failure mode is rare and the guarantee is absolute.
Within a single data center, coordinating two databases and a message broker
across a reliable local network, with a transaction manager whose recovery log is
on durable storage, the vulnerable interval is measured in milliseconds and the
recovery procedure is automatic. Financial institutions, telecommunications
operators and government systems adopted the protocol because the alternative was
to write compensation logic by hand for every business operation. Additionally,
software architects and developers are more confident in a protocol than in a
promise that reconciliation will probably catch any discrepancies.

Another important point to notice is that 2PC places complexity in the
infrastructure field, written once, by specialists, and consumed through a single
annotation. Every other alternative examined in this article moves that work into
application code, where it must be written again for each operation, by
developers whose principal expertise is the business domain rather than
distributed systems. This is a real cost and it is frequently underestimated.

3. OTS, JTS and JTA

The X/Open model assumed a particular shape: an application, a transaction
manager and some resource managers, generally within reach of one another. What
it did not address is the case that the OO (object-oriented) paradigm made
central the concept of transactions spanning objects that reside in different
processes, on different machines, supplied by different vendors, and invoked
remotely as though they were local.

The OMG (Object Management Group), the consortium behind CORBA, answered this in the
mid-1990s with the OTS (Object Transaction Service), adopted as one of the
CORBAservices. OTS described the roles of a distributed transaction in CORBA's
IDL (Interface Definition Language). The protocol underneath had not changed,
the same resources, participants and quorum, in Gray's sense, were at work and
no new algorithms have been proposed. OTS only specified how the 2PC participants
might be distributed objects. And it settled the question that X/Open had left
thin, namely how two transaction managers, from different vendors, should
interoperate.

OTS didn't displace XA but complemented it. The boundary to the resources, like
databases or message brokers, remained what it had been, OTS typically only fronted
resource managers driven over XA. Anything that OTS added sat above that
boundary, between the managers themselves.

The Jakarta EE platform, formerly Java EE and even formerly J2EE, absorbed this
model with considerable thoroughness. The JTA (Java Transaction API) specifications
defined the interface through which applications and application servers demarcate
transactions. JTS (Java Transaction Service) brought OTS into Java. It required
a transaction manager to implement that specification in its Java-mapped form,
to propagate transaction context between managers as OTS prescribed, and to
present JTA to the layer above. JTS was therefore not an alternative design but
OTS in Java, with a JTA façade.

The distinction between JTA and JTS is worth mentioning as the two are habitually
confused, usually as "JTA is the interface and JTS the implementation". That is
not quite it, since both are specifications. JTA is what an application programmer
sees: UserTransaction, TransactionManager, and the interfaces by which resources
are enlisted. JTS specifies what provides the guarantee underneath, including the
propagation of transaction context between processes and the interoperability of
transaction managers from different vendors.

For the application developer, the effect was remarkable and is easily forgotten
now. A method annotated for container-managed transactions would, upon invoking a
remote component, carry its transaction context to that component, enlist the
remote resources, and commit or roll back the entire assembly atomically. The
programmer wrote business logic. The container arranged consensus. This was one
of the genuinely impressive achievements of the enterprise Java period which
worked reliably across products from competing vendors and it is
somewhat unfair that it is now remembered as an old labyrinthine system.

4. CORBA and IIOP as the Transport of Context

The transaction context propagation just described required a mechanism, and the
mechanism was CORBA. Transaction context traveled between application servers
as part of the IIOP (Internet Inter-ORB Protocol), in the form of a service
context attached to the remote invocation. OTS defined how that context was
represented and how transaction managers should interoperate. IIOP carried it.

This arrangement was possible because the transport understood transactions.
A remote call was not merely a message but an invocation within a transactional
context, and the infrastructure at both ends recognized it as such. Enlistment
of the remote resource was automatic because the protocol carried the information
required to perform it.

The costs were substantial. CORBA was complex, its interoperability was achieved
by considerable effort and its programming model demanded interface definitions
and generated stubs. As the industry moved towards HTTP and simpler representations,
these costs became decisive. But it is important to record that the price of the
simplicity was HTTP lack of capacity to carry transactional semantics.

5. The Decline of Heavyweight Servers and the Rise of Lighter Frameworks

The reasons for the decline of the traditional application server are well
documented and only tangentially concerned with transactions. Deployment units
grew large and start-up times grew long at exactly the moment when elastic
infrastructure began to reward the opposite. Container images preferred a single
process to a shared runtime hosting many applications. The operational model of
the application server, in which several applications share a managed container
administered by a specialist team, was displaced by one in which each service
carries its own runtime and is administered by the team that wrote it.

Spring Boot, released in 2014, demonstrated that an embedded server and
convention-based configuration could deliver most of the productivity of the
enterprise stack with a fraction of its ceremony. Quarkus, which followed in 2019,
went further by moving substantial work from run time to build time, producing
start-up characteristics that make Java a plausible choice for serverless and
elastically scaled deployments.

Jakarta EE itself, transferred to the Eclipse Foundation in 2017 and subsequently
renamed, continues to evolve, and both Spring Boot and Quarkus rely on
substantial parts of its specifications. The change is therefore less a
repudiation of the enterprise Java model than a redistribution of it. The
specifications survived, the monolithic container that implemented them did not.

6. What the Lighter Frameworks Lost

Two changes occurred simultaneously. The first is architectural. The microservice
architecture style holds that each service should own its data, and that no other
service should reach into that data directly. This principle is incompatible with
2PC across services which requires the coordinator to be connected to
the resource managers. A coordinator that must not touch another service's
resources cannot enlist them.

The second is a matter of transport. HTTP does not propagate transaction context.
It doesn't provide an equivalent of the IIOP service context. A REST call is an
independent interaction whose relationship to the caller's transaction is not
represented anywhere, unless the application arranges to represent it.

The consequence, which is regularly misunderstood in practice, is that
annotating a method as transactional and then invoking a remote service from
within it produces no distributed transaction of any kind.
If the local transaction rolls back, the remote effect stands. If
the local transaction commits, nothing establishes that the remote one did, and
a remote call that returned no answer may have applied its change or may not,
leaving the caller no basis on which to decide. The divergence does not even
require the remote service to fail. The arrangement has the
appearance of a distributed transaction and none of the substance, which is the
least desirable of the available outcomes, since it fails while presenting the
appearance of success.

7. The Saga Pattern, and the Ease of Implementing It Incorrectly

The saga was described by Garcia-Molina and Salem in 1987, in a paper concerned
with long-lived transactions within a single database. Their observation was that
a transaction holding locks for a long period is destructive to concurrency, and
that certain long transactions may be decomposed into a sequence of shorter ones,
each of which commits independently, with a compensating transaction defined for
each step. If the sequence cannot be completed, the compensations for the
completed steps are executed in reverse order.

The saga doesn't provide isolation. This is not a defect of a particular
implementation but by definition. Intermediate states are visible to other
observers, because each step has genuinely committed. In exchange, no participant
holds a lock while waiting for a distant coordinator, and each service retains
authority over its own data.

The naive implementation, which is very common, executes each step and defines its
compensation as the arithmetic inverse. Let's consider the example of a money transfer
service, like the one presented in the associated project. A debit is compensated
by a credit of the same amount. This is wrong in two distinct ways.

The first defect is the visible intermediate state. Between the debit and its
compensation, the balance is genuinely reduced. Any concurrent observer, including
another saga evaluating whether sufficient funds exist, will read that reduced
value and may act upon information that is about to be invalidated.

The second defect is that the compensating action can itself fail. A credit is
an operation like any other, subject to validation, to constraints, and to the
account having been closed in the interval. A saga whose compensation fails is in
a worse condition than one that never began, since it has performed part of an
operation and it cannot undo it. The system requires human intervention, and the
humans require an explanation.

The remedy, illustrated in Section 10, is to arrange matters so that no
compensating write is required. If the first step reserves rather than acts, then
compensation releases the reservation, and a release cannot fail for business
reasons because it removes an obligation rather than creating one.

8. MicroProfile LRA

MicroProfile LRA, where LRA denotes Long Running Action, specifies a saga
coordination protocol for services communicating over HTTP. It is best understood
as an answer to the two negative effects identified in Section 6: it reintroduces a context
that travels with the call, and it reintroduces a coordinator that drives
participants to a common outcome. It does not, and cannot, reintroduce atomicity.

The programming model is declarative. A method annotated @LRA participates in a
long-running action, beginning one if required. Context propagates in the
Long-Running-Action HTTP header, which the implementation attaches to outgoing
calls and interprets on incoming ones. A participant declares its obligations
through further annotations:

@Compensate, which is invoked if the action is cancelled;
@Complete, invoked if it is closed successfully;
@Status, by which the coordinator may enquire what a participant did;
@Forget, by which a participant may discard state it no longer needs to retain.

Two properties of this protocol are commonly overlooked. The first is that participants
must be idempotent. The coordinator retries. A participant that applies its
effect a second time corrupts its own data. This is the requirement that appears
in every specification document and is absent from a remarkable proportion of
first implementations.

The second is that the coordinator is a separate process that calls the
participants back. As opposed to JTA where the transaction manager is embedded
in the application, under LRA it is not and the participant must reach the coordinator
to begin, join and end an action. The coordinator must reach every participant
to invoke its callbacks. It is entirely possible to construct a deployment in
which the first direction works as expected while the second does not, and the resulting
behavior is discussed in Section 10.

9. The XA Implementation in Detail

The use case is deliberately modest: transfer an amount from one account to
another and record the transfer. Two databases are involved, one holding accounts
and one holding the transfer log, because a single database would reduce the
problem to a local transaction and demonstrate nothing.

One component in this arrangement is essential: the Narayana transaction manager.
Its lineage is running back to the Arjuna research at the University of Newcastle
and provided two decades of good service as the transaction manager of JBoss and
WildFly. Its Quarkus extension, used here, brings a JTA implementation embedded
in the application's own process. It owns the object store, decides the outcome
and executes the 2PC protocol on the application's behalf. The same project supplies
the LRA coordinator that section 10 relies upon, so both implementations in this
article rely on the same body of code.

Configuration

Each datasource is declared as an XA one:

quarkus.datasource.accounts.jdbc.transactions=xa
quarkus.datasource.xfers.jdbc.transactions=xa

That flag is the entire mechanism. The connection pool supplies XAConnection
instances rather than ordinary ones, and each pool enlists an XAResource in the
active transaction upon first use.

The transactional method

@Transactional
public TransferDto processTransfer(TransferRequest request)
{
  Account source = accountRepository.getAccount(request.getSourceAccountId())
    .orElseThrow(() -> new AccountNotFoundException(request.getSourceAccountId()));
  Account destination = accountRepository.getAccount(request.getDestinationAccountId())
    .orElseThrow(() -> new AccountNotFoundException(request.getDestinationAccountId()));
  if (source.getBalance().compareTo(request.getAmount()) < 0)
    throw new InsufficientFundsException(source.getId());
  source.debit(request.getAmount());
  destination.credit(request.getAmount());
  Transfer transfer = new Transfer(Common.getRandomId(), source.getId(), destination.getId(),
        request.getAmount(), request.getCurrency(), TransferStatus.COMPLETED, LocalDateTime.now());
  transferRepository.createTransfer(transfer);
  return transfer.toDto();
}

There is no reference to two-phase commit in this code, and that is the
observation worth recording. The annotation causes a JTA transaction to begin. The
two repositories address two different datasources. Each datasource enlists itself.
When the method returns, Narayana performs the protocol.

The protocol as executed

Upon commit the transaction manager calls prepare on both branches. Each
PostgreSQL instance executes PREPARE TRANSACTION, writing the changes durably in
a state from which they can still either be committed or rolled back. If both
branches vote affirmatively, the transaction manager writes its decision to
its object store. This is the point at which the outcome becomes irrevocable
and then the transaction manager calls commit on both branches, each of which
executes COMMIT PREPARED.

Two consequences of operational importance follow. PostgreSQL refuses prepared
transactions unless max_prepared_transactions is configured with a positive
value, its default being zero, so an otherwise correct application fails at the
first commit. And the transaction manager's object store must be durable, since it
holds the only record of a decision made but not yet applied. Recovery must be
enabled so that transactions left in doubt by a failure are resolved when the
process returns.

The architectural cost

The transfer service interacts directly with the accounts database. It does not
ask anything of the account service, it holds the resource manager instead. This
means that it owns a connection to the accounts database and enlists it in its
own transaction. The transfer service opens that connection, modifies the account
rows itself through its own persistence layer, and the XAResource behind that
connection becomes a branch of the transaction that the transfer service began.
The account service plays no part. Its code does not run and it is not informed.
The commit decision belongs to the transfer service's transaction manager.

This is not an oversight but a requirement. prepare and commit are operations
on an XAResource, and a service boundary exposes no equivalent of them. HTTP
offers no way to ask a remote service to make a change durable while leaving its
outcome open. A coordinator that cannot reach the resource manager cannot enlist
it. The consequence is that the two services need to share a database, and the
independence that the service boundary was intended to establish is not present.
The repository's docker-compose.yaml states this fact in one line: transfer is
given its own database, as well as the accounts datasource URL, whereas
transfer-lra is given, in addition to its own database URL, the one of the
account service.

10. The LRA Implementation in Detail

The saga implementation exposes an identical REST contract and reaches balances
only through the account service's HTTP interface. It has no dependency on the
accounts persistence layer, and that absence is the entire architectural point.

Reserve, then confirm

In the LRA implementation and as opposed to the 2PC one, the account service does
not move money when asked to reserve a debit. It records a Reservation in state
PENDING and leaves the balance unchanged. Available funds are computed as the
balance minus the sum of pending debits, so another possible concurrent saga
cannot reserve the same money. Upon @Complete the reservations are applied;
upon @Compensate they are released.

Accordingly, because the balance never moved, compensation performs no update
and, therefore, no persistence operation can fail during compensation. Hence,
the second issue identified in Section 7 is eliminated by construction rather
than by coding.

Idempotency, enforced twice

Reservations are identified, in business terms, by a triple consisting in the action identifier,
the account and the reservation type. Notice that the triple is not the entity's primary key,
which is a generated value, so nothing in the object model prevents a second row carrying the
same triple. And in order to avoid that, it is declared as a unique constraint in the database:

@Table(name = "RESERVATIONS",
  uniqueConstraints = @UniqueConstraint(name = "UK_RESERVATION_LRA",
    columnNames = {"LRA_ID", "ACCOUNT_ID", "RESERVATION_TYPE"}))

The constraint is needed because the account service, when asked to reserve a
debit, looks for an existing reservation before writing one, which is a
check-then-act sequence and, therefore, not atomic. Two deliveries of the same
reserve request can both find nothing and both insert. The constraint avoids that
and guarantees that the database refuses the 2nd reserve.

Retries could also cause the effect described above. The coordinator waits for
each callback, but a call that times out or whose reply is lost leaves the
action unresolved, so it keeps calling again and again. A settlement instruction
therefore might arrive more than once for a reservation that is already recorded. The
database constraint cannot help here, since no row is being inserted. Then the guard
sits one level down, in the service class shown below. As you can see, the two
callbacks annotated with @Compensate and @Complete annotations obtain their
reservations from a single helper, the pendingFor(...) method, that selects
only the PENDING reservations, so that the ones already confirmed or already
released are passed over rather than settled again.

@ApplicationScoped
public class AccountLraService
{
  ...
  @Transactional
  public ParticipantStatus complete(String lraId)
  {
    pendingFor(lraId).forEach(this::confirm);
    return ParticipantStatus.Completed;
  }
  ...
  @Transactional
  public ParticipantStatus compensate(String lraId)
  {
    pendingFor(lraId).forEach(reservation -> reservation.setState(ReservationState.RELEASED));
    return ParticipantStatus.Compensated;
  }
  ...
  private Stream<Reservation> pendingFor(String lraId)
  {
    return reservations.findByLra(lraId).stream()
     .filter(reservation -> reservation.getState() == ReservationState.PENDING);
  }
  ...
}

11. The Project

The project that illustrates this article is a Quarkus workshop, available at
quarkus-distributed-tx,
showing a simple money transfer use case in the two ways that we discussed along
the article:

XA / 2PC (transfer, port 8080): a genuine 2PC across two XA datasources, coordinated by Narayana.
Saga / MicroProfile LRA (transfer-lra, port 8090 and account, port 8081): a compensation-based consistency example across autonomous services, coordinated by a Narayana LRA coordinator.

Both expose the same /xfers REST contract and are driven by the same shared
test suite (transfer-tck), so any difference you observe is a difference in
transaction strategy and nothing else.

Modules

The following modules are part of the workshop project.

Module	Role
`common`	Shared library: `Common` utility, the transfer DTOs (`TransferDto`, `TransferRequest`, `TransferResponse`, `TransferStatus`), the application exception hierarchy and the single `ApplicationExceptionMapper` that maps them to HTTP status codes.
`account-repository`	Shared persistence layer for accounts: the `Account` entity, `AccountDto`, the `AccountRepository` interface and its two implementations. Depended on by `account` and by `transfer` — and pointedly not by `transfer-lra`.
`transfer-tck`	The REST contract both transfer implementations must satisfy, as an abstract test class. Test tooling is at compile scope so consumers depend on it with `<scope>test</scope>`.
`account`	Account microservice (port 8081). Owns the `accounts` schema. CRUD + debit/credit, plus the LRA participant endpoints under `/lra/accounts`.
`transfer`	XA coordinator (port 8080). Two XA datasources (`accounts`, `xfers`). Transfer CRUD plus the 2PC transfer operation.
`transfer-lra`	Saga orchestrator (port 8090). One plain datasource for its own transfer log; reaches balances only through the account service's API.

Each repository has two implementations: an in-memory one (DefaultAccountRepository,
DefaultTransferRepository) and a JPA/Panache one (AccountRepositoryXA,
TransferRepositoryXA). Both are @Alternative, so neither is enabled by default;
each application picks the XA pair explicitly through
quarkus.arc.selected-alternatives. Only the XA implementations participate in 2PC —
the in-memory ones are there to run the services without a database.

All four modules carry the Jandex plugin so their @Entity, @Provider and CDI bean
classes are indexed when consumed as external dependencies.

Endpoints

Three services expose an HTTP API, each with a Swagger UI at /q/swagger-ui. The
rows marked as callbacks are invoked by the LRA coordinator, not by clients.

Service	Method	Path	Purpose
`account` (8081)	`GET`	`/accounts`	List the accounts
`account` (8081)	`POST`	`/accounts`	Create an account
`account` (8081)	`GET`	`/accounts/{accountId}`	Read one account
`account` (8081)	`PUT`	`/accounts/{accountId}`	Update one account
`account` (8081)	`DELETE`	`/accounts/{accountId}`	Delete one account
`account` (8081)	`POST`	`/accounts/{accountId}/debit`	Debit, amount in the body
`account` (8081)	`POST`	`/accounts/{accountId}/credit`	Credit, amount in the body
`account` (8081)	`POST`	`/lra/accounts/{accountId}/debit`	Reserve a debit, `@LRA(MANDATORY)`
`account` (8081)	`POST`	`/lra/accounts/{accountId}/credit`	Reserve a credit, `@LRA(MANDATORY)`
`account` (8081)	`GET`	`/lra/accounts/{accountId}/availability`	Balance, held and available amounts
`account` (8081)	`PUT`	`/lra/accounts/complete`	`@Complete` callback
`account` (8081)	`PUT`	`/lra/accounts/compensate`	`@Compensate` callback
`account` (8081)	`GET`	`/lra/accounts/status`	`@Status` callback
`account` (8081)	`DELETE`	`/lra/accounts/forget`	`@Forget` callback
`transfer` (8080)	`POST`	`/xfers`	Transfer, in one 2PC transaction
`transfer` (8080)	`GET`	`/xfers`	List the transfer log
`transfer` (8080)	`GET`	`/xfers/{transferId}`	Read one transfer
`transfer` (8080)	`PUT`	`/xfers/{transferId}`	Update one transfer
`transfer` (8080)	`DELETE`	`/xfers/{transferId}`	Delete one transfer
`transfer-lra` (8090)	`POST`	`/xfers`	Transfer, as a saga, `@LRA(REQUIRED)`
`transfer-lra` (8090)	`GET`	`/xfers`	List the transfer log
`transfer-lra` (8090)	`GET`	`/xfers/{transferId}`	Read one transfer
`transfer-lra` (8090)	`PUT`	`/xfers/{transferId}`	Update one transfer
`transfer-lra` (8090)	`DELETE`	`/xfers/{transferId}`	Delete one transfer
`transfer-lra` (8090)	`PUT`	`/xfers/lra/complete`	`@Complete` callback
`transfer-lra` (8090)	`PUT`	`/xfers/lra/compensate`	`@Compensate` callback
`transfer-lra` (8090)	`GET`	`/xfers/lra/status`	`@Status` callback
`transfer-lra` (8090)	`DELETE`	`/xfers/lra/forget`	`@Forget` callback

Two things are worth reading off the table. The two transfer services present the
same POST /xfers contract, taking the same request body of
{sourceAccountId, destinationAccountId, amount, currency}, which is what allows
a single test class to exercise both. And the account service's participant API
sits under its own path prefix instead of altering the existing endpoints, which
is why the saga work left the original account tests untouched.

Build & test

Integration tests use Quarkus Dev Services (Testcontainers), so a running Docker
daemon is required. No manual database setup is needed. Each service seeds its own
data in dev/test profiles, on the behalf of the import.sql file for account and of the
import-accounts.sql for transfer. In the prod profile the account service
owns the accounts schema and no generation or seeding happens.

The following command runs the integration tests:

mvn clean verify

Here is the list of the integration tests provided with the project:

AbstractMoneyTransferContractIT (transfer-tck): this is an abstract class serving as a superclass for all the integration tests. It defines the shared scenarios: happy path, insufficient funds, unknown account, listing and deletion. Assertions are on deltas, and the balance/count probes are abstract, because the XA service can read the databases directly while the saga service can only get them by calling the API over HTTP. Failure paths assert the response body as well as the status. Both stacks must return the business error rather than transaction plumbing, which a status-only assertion would not catch.
MoneyTransferIT (transfer): the contract against XA, with repository-based probes.
MoneyTransferSagaIT (transfer-lra): the contract against LRA, with HTTP probes, plus saga-only assertions about the COMPENSATED audit row and released reservations.
AccountResourceIT (account): account CRUD, debit/credit, 404 on unknown account, and rejection of overdrafts and invalid amounts.

Run the full stack

In order to run the full stack, production like, proceed as follows:

# Build the container images (container-image.build=true is enabled)
mvn clean package
docker compose up -d

docker-compose.yaml starts the whole comparison:

Service	Port	Role
`accounts-db`	5432	Accounts, `max_prepared_transactions=100` for XA
`xfers-db`	5433	XA transfer log, `max_prepared_transactions=100`
`xfers-lra-db`	5434	Saga transfer log (no XA needed)
`lra-coordinator`	50000	`quay.io/jbosstm/lra-coordinator`
`account`	8081	CRUD + LRA participant
`transfer`	8080	XA/2PC
`transfer-lra`	8090	Saga/LRA

Both transfer services run against the same accounts, so you can drive the same
transfer through each and compare:

BODY='{"sourceAccountId":"ACC1","destinationAccountId":"ACC2","amount":10.00,"currency":"EUR"}'
curl -s -XPOST -H 'Content-Type: application/json' -d "$BODY" http://localhost:8080/xfers  # XA
curl -s -XPOST -H 'Content-Type: application/json' -d "$BODY" http://localhost:8090/xfers  # Saga
curl -s http://localhost:8081/lra/accounts/ACC1/availability                                # reservations

Note QUARKUS_LRA_BASE_URI on the two participants: it is the address the
coordinator uses to call them back, and without it a participant advertises a URL
that is only meaningful from its own side of the network.

A Swagger interface is also available with each API, as explained at §11 Endpoints.
Additionally, the smoke test script test-all.sh is a very convenient way to make
sure to cover all the test case possible combinations. Here below is an example
of how to run it:

$ docker compose up -d
$ ./test-all.sh

=== Account API - http://localhost:8081/accounts ===
PASS POST /accounts (create ACC90, 1000.00) -> 201
PASS POST /accounts (create ACC91, 0.00) -> 201
PASS POST /accounts (create ACC92, 10.00) -> 201
PASS GET /accounts/ACC90 -> 200
PASS balance(ACC90) == 1000.00
PASS GET /accounts (list) -> 200
PASS PUT /accounts/ACC90 (rename owner) -> 200
PASS GET /accounts/ACC90 (confirm rename) -> 200
PASS customerName updated
PASS POST /accounts/ACC90/credit (50.00) -> 200
PASS balance(ACC90) == 1050.00
PASS POST /accounts/ACC90/debit (200.00) -> 200
PASS balance(ACC90) == 850.00

=== Account API - negative cases ===
PASS POST credit (-1.00) rejected -> 400
PASS POST debit (0.00) rejected -> 400
PASS POST debit (999999.00) insufficient funds -> 400
PASS GET /accounts/NOSUCH -> 404
PASS POST credit on unknown account -> 404
PASS POST credit without Content-Type -> 415
PASS balance(ACC90) == 850.00
PASS DELETE /accounts/ACC92 -> 204
PASS GET deleted account -> 404
PASS DELETE already-deleted account -> 404

=== Account LRA participant API - http://localhost:8081/lra/accounts ===
PASS GET /lra/accounts/ACC90/availability -> 200
PASS availability exposes balance/held/available
PASS POST /lra/accounts/ACC90/debit without LRA context -> 412
PASS POST /lra/accounts/ACC90/credit without LRA context -> 412
PASS balance(ACC90) == 850.00

=== XA Transfer API (2PC) - http://localhost:8080/xfers ===
PASS POST /xfers (ACC90 -> ACC91, 100.00) -> 200
PASS transferId returned: raizmjf
PASS balance(ACC90) == 750.00
PASS balance(ACC91) == 100.00
PASS GET /xfers/raizmjf -> 200
PASS GET /xfers (list) -> 200
PASS PUT /xfers/raizmjf (currency -> USD) -> 200

=== XA Transfer API - negative cases (nothing must move) ===
PASS POST /xfers insufficient funds -> 400
PASS POST /xfers negative amount -> 400
PASS POST /xfers unknown source -> 404
PASS POST /xfers unknown destination -> 404
PASS balance(ACC90) == 750.00
PASS balance(ACC91) == 100.00
PASS GET /xfers/NOSUCH -> 404
PASS DELETE /xfers/raizmjf -> 204
PASS GET deleted transfer -> 404

=== Saga Transfer API (LRA) - http://localhost:8090/xfers ===
PASS POST /xfers (ACC90 -> ACC91, 25.00) -> 200
PASS transferId returned: etmlebm
PASS balance(ACC90) == 725.00
PASS balance(ACC91) == 125.00
PASS GET /xfers/etmlebm -> 200
PASS GET /xfers (list, includes compensated) -> 200
PASS @Complete flipped the transfer to COMPLETED

=== Saga Transfer API - cancellation and compensation ===
PASS POST /xfers insufficient funds (saga cancels) -> 400
PASS balance(ACC90) == 725.00
PASS balance(ACC91) == 125.00
PASS @Compensate logged the cancelled transfer as COMPENSATED
PASS POST /xfers unknown destination (saga cancels) -> 404
PASS balance(ACC90) == 725.00
PASS GET availability after settled sagas -> 200
PASS held == 0 (no reservation left dangling)
PASS PUT /xfers/etmlebm (currency -> USD) -> 200
PASS GET /xfers/NOSUCH -> 404
PASS DELETE /xfers/etmlebm -> 204
PASS GET deleted transfer -> 404

=== Saga participant callbacks - @Status and @Forget (transfer-lra) ===
PASS coordinator started LRA: http://lra-coordinator:8080/lra-coordinator/0_ffffac120002_a03b_6ad35817_1ed
PASS POST /xfers with an externally started LRA -> 412
PASS GET /xfers/lra/status (@Status) -> 200
PASS @Status reports Compensated for the cancelled LRA
PASS balance(ACC90) moved by 0 (now 725.00)
PASS DELETE /xfers/lra/forget (@Forget) -> 200
PASS GET /xfers/lra/status after @Forget -> 404
PASS @Forget kept the transfer, only dropped its LRA id

=== Account LRA participant API - driving a saga by hand ===
PASS coordinator started LRA: http://lra-coordinator:8080/lra-coordinator/0_ffffac120002_a03b_6ad35817_1f2
PASS POST /lra/accounts/ACC90/debit (40.00, in LRA) -> 200
PASS balance(ACC90) moved by 0 (now 725.00)
PASS held(ACC90) moved by 40.00 (now 40.00)
PASS POST /lra/accounts/ACC91/credit (40.00, in LRA) -> 200
PASS balance(ACC91) moved by 0 (now 125.00)
PASS coordinator closed the LRA -> 200
PASS balance(ACC90) moved by -40.00 (now 685.00)
PASS balance(ACC91) moved by 40.00 (now 165.00)
PASS held(ACC90) moved by 0 (now 0)

=== Account LRA participant API - cancelling a saga by hand ===
PASS coordinator started LRA: http://lra-coordinator:8080/lra-coordinator/0_ffffac120002_a03b_6ad35817_1f7
PASS POST /lra/accounts/ACC90/debit (15.00, in LRA) -> 200
PASS held(ACC90) moved by 15.00 (now 15.00)
PASS coordinator cancelled the LRA -> 200
PASS balance(ACC90) moved by 0 (now 685.00)
PASS held(ACC90) moved by 0 (now 0)

=== Summary ===
87 passed, 0 failed

12. Comparison

The attached GitHub repository contains a multi-module Maven project with two
implementations. The
first uses JTA and XA to obtain a two-phase commit, and is contained entirely in
the transfer module. The second uses MicroProfile LRA, and is necessarily
spread across two modules: transfer-lra orchestrates the saga, while account
takes part in it. That difference in shape is not an accident of packaging. A
JTA coordinator that enlists resource managers directly can live in a single
module, the transfer one, whereas a saga cannot exist unless its participants
are reachable and callable, hence the necessity for it to live in two modules,
transfer-lra and account.

Both implementations satisfy the same test contract. The following differences
are therefore differences of mechanism and of consequence, not of capability.

Dimension	XA and two-phase commit	Saga and LRA
Coordinator	Embedded in the application process	Separate process, must call participants back
Data ownership	Coordinator holds the resource managers, so services share a database	Each service retains its own data
Isolation	Complete; no intermediate state is observable	Absent by design; a reservation is observable while in flight
Failure	Rollback leaves no trace whatsoever	Leaves a record that the operation was attempted and undone
Locks	Held between prepare and commit	None held across the action
Availability	Participants block if the coordinator fails while in doubt	Participants remain available; completion may occur later
Location of difficulty	Infrastructure, written once	Application code, written for each operation
Failure of the undo	Not applicable; nothing was committed	Possible, unless reservations are used

Two entries deserve comment.

The row concerning failure is frequently presented as an advantage of 2PC on the
grounds that the rollbacks are clean. It may equally be regarded as a loss of
information. A cancelled saga records that a transfer was attempted and
subsequently undone, which is an audit trail that a rollback cannot produce
because the rows were never committed. Whether this constitutes an advantage
depends entirely on whether the business is required to account for attempts as
well as for outcomes, and this is a question for the domain rather than for the
architecture.

The row concerning the location of difficulty is, in my opinion, the
one most often omitted from comparisons. 2PC is difficult once, in
infrastructure maintained by specialists. Sagas are difficult repeatedly, in
application code and this argument is important.

The correct conclusion is not that one approach supersedes the other. It is that
the choice is determined by whether the resource managers can be co-located under
a single coordinator. If they can, 2PC provides a stronger guarantee
for less application code. If they cannot, because the services are genuinely
independent or the resources do not support XA, then a saga is not the inferior
option but the only option, and the engineering effort should be directed at
implementing it correctly rather than at regretting the atomicity that was never
available.

13. The Present and the Future

Two-phase commit is not disappearing. It remains appropriate wherever resources
can be co-located, and a significant proportion of enterprise data continues to
reside in exactly such arrangements. Reports of its obsolescence generally
originate from contexts in which it was never applicable.

Sagas are becoming ordinary. What is changing is the level of abstraction at which
they are expressed. Handwritten orchestration is giving way to specified
protocols such as LRA, to workflow engines that record the state of long-running
processes durably, and to durable execution platforms in which the compensation
logic is expressed as ordinary code. The direction of travel is consistent: the difficulty is being moved
back out of application code and into infrastructure, which is where the industry
placed it in the first place, some thirty years ago, and where it appears to
belong.

Two developments merit attention. The first is the growing use of the outbox
pattern with event streaming, which achieves atomicity between a database change
and a message by writing both to the same database and publishing asynchronously.
This is neither 2PC nor a saga in the classical sense, and for many integration
problems it is a better answer than either. The second is the increasing
availability of formal verification tools for distributed protocols, which offers
some prospect that compensation logic might eventually be checked rather than
merely reviewed.

The underlying tension, however, is not a matter of technology and will not be
resolved by these developments. Atomicity across independent parties
requires either that they transfer autonomy to a coordinator or that they accept
observable intermediate states. The FLP (Fischer, Lynch and Paterson) result and its relatives indicate that no
implementation will escape this choice. What improves is the quality of the tools
with which each side of the choice may be pursued, and the clarity with which the
choice is presented to the practitioners.

The most costly systems are not those that chose two-phase commit, nor those that
chose sagas, but those that believed they had chosen the former while in fact
operating the latter, without compensations.

References and Further Reading

Gray, J. Notes on Data Base Operating Systems, 1978.
Fischer, M., Lynch, N., Paterson, M. Impossibility of Distributed Consensus with One Faulty Process, Journal of the ACM, 1985.
Garcia-Molina, H., Salem, K. Sagas, ACM SIGMOD, 1987.
X/Open. Distributed Transaction Processing: The XA Specification.
Object Management Group. Object Transaction Service.
Eclipse MicroProfile. MicroProfile LRA Specification.
The accompanying source code, quarkus-distributed-tx, containing both implementations, the shared contract test suite and a Docker Compose deployment that runs the two stacks side by side.

Distributed Transactions in Enterprise Applications: From X/Open to MicroProfile LRA

Nicolas DUMINIL — Mon, 19 Oct 2026 15:00:00 +0000

Abstract

The problem of making several independent systems agree on a single outcome is older than most of the technology used to solve it. Historically, one of the
first protocol able to provide this synchronization was 2PC (two-phase commit)
that the application servers era made an ordinary feature of enterprise development.
Later lightweight frameworks, service-oriented and microservices architectures
have made the same guarantee considerably harder to obtain.

This article follows that problem from its formalization in the X/Open Distributed
Transaction Processing to the present situation. It then examines two working
implementations of an identical use case, one using XA and two-phase commit, the
other using the saga pattern, as specified by MicroProfile LRA, and compares them
on evidence rather than on preference. The accompanying source code is available
in the repository, where both implementations expose the
same REST contract and are exercised by the same test suite.

1. Origins: X/Open, and the Formalization of 2PC

the TX (Transaction Demarcation) interface governs how an application demarcates a transaction;
the XA (*eXtended Architecture) interface defines how the transaction manager drives the resource manager through the phases of the commit;

2. Several Decades of Service

3. OTS, JTS and JTA

The X/Open model assumed a particular shape: an application, a transaction
manager and some resource managers, generally within reach of one another. What
it did not address is the case that the OO (object-oriented) paradigm made
central the co,cept of transactions spanning objects that reside in different
processes, on different machines, supplied by different vendors, and invoked
remotely as though they were local.

The OMG (Object Management Group), the consortium behind CORBA, answered this in the
mid-1990s with the OTS (Object Transaction Service), adopted as one of the
CORBAservices. OTS described the roles of a distributed transaction in CORBA's
IDL (Interface Definition Language). The protocol underneath had not changed,
the same resources, participants and quorum, in Gray's sense, were at work and
no new algorithms has been proposed. OTS only specified how the 2PC participants
might be distributed objects. And it settled the question that X/Open had left
thin, namely how two transaction managers, from different vendors, should
interoperate.

4. CORBA and IIOP as the Transport of Context

5. The Decline of Heavyweight Servers and the Rise of Lighter Frameworks

6. What the Lighter Frameworks Lost

7. The Saga Pattern, and the Ease of Implementing It Incorrectly

8. MicroProfile LRA

@Compensate, which is invoked if the action is cancelled;
@Complete, invoked if it is closed successfully;
@Status, by which the coordinator may enquire what a participant did;
@Forget, by which a participant may discard state it no longer needs to retain.

9. The XA Implementation in Detail

Configuration

Each datasource is declared as an XA one:

quarkus.datasource.accounts.jdbc.transactions=xa
quarkus.datasource.xfers.jdbc.transactions=xa

That flag is the entire mechanism. The connection pool supplies XAConnection
instances rather than ordinary ones, and each pool enlists an XAResource in the
active transaction upon first use.

The transactional method

@Transactional
public TransferDto processTransfer(TransferRequest request)
{
  Account source = accountRepository.getAccount(request.getSourceAccountId())
    .orElseThrow(() -> new AccountNotFoundException(request.getSourceAccountId()));
  Account destination = accountRepository.getAccount(request.getDestinationAccountId())
    .orElseThrow(() -> new AccountNotFoundException(request.getDestinationAccountId()));
  if (source.getBalance().compareTo(request.getAmount()) < 0)
    throw new InsufficientFundsException(source.getId());
  source.debit(request.getAmount());
  destination.credit(request.getAmount());
  Transfer transfer = new Transfer(Common.getRandomId(), source.getId(), destination.getId(),
        request.getAmount(), request.getCurrency(), TransferStatus.COMPLETED, LocalDateTime.now());
  transferRepository.createTransfer(transfer);
  return transfer.toDto();
}

The protocol as executed

Upon commit the transaction manager calls prepare on both branches. Each
PostgreSQL instance executes PREPARE TRANSACTION, writing the changes durably in
a state from which they can still either be commited or rolled back. If both
branches vote affirmatively, the transaction manager writes its decision to
its object store. This is the point at which the outcome becomes irrevocable
and then the transaction manager calls commit on both branches, each of which
executes COMMIT PREPARED.

The architectural cost

The transfer service interacts directly with the accounts database. It does not
ask anything of the account service, it holds the resource manager instead. This
means that it owns a connection to the accounts database and enlist it in its
own transaction. The transfer service opens that connection, modifies the account
rows itself through its own persistence layer, and the XAResource behind that
connection becomes a branch of the transaction that the transfer service began.
The account service plays no part. Its code does not run and it is not informed.
The commit decision belongs to the transfer service's transaction manager

10. The LRA Implementation in Detail

Reserve, then confirm

Idempotency, enforced twice

@Table(name = "RESERVATIONS",
  uniqueConstraints = @UniqueConstraint(name = "UK_RESERVATION_LRA",
    columnNames = {"LRA_ID", "ACCOUNT_ID", "RESERVATION_TYPE"}))

@ApplicationScoped
public class AccountLraService
{
  ...
  @Transactional
  public ParticipantStatus complete(String lraId)
  {
    pendingFor(lraId).forEach(this::confirm);
    return ParticipantStatus.Completed;
  }
  ...
  @Transactional
  public ParticipantStatus compensate(String lraId)
  {
    pendingFor(lraId).forEach(reservation -> reservation.setState(ReservationState.RELEASED));
    return ParticipantStatus.Compensated;
  }
  ...
  private Stream<Reservation> pendingFor(String lraId)
  {
    return reservations.findByLra(lraId).stream()
     .filter(reservation -> reservation.getState() == ReservationState.PENDING);
  }
  ...
}

11 The Project

The project that illustrates this article is a Quarkus workshop showing a simple
money transfer use case in the two ways that we discussed along the article:

XA / 2PC (transfer, port 8080): a genuine 2PC across two XA datasources, coordinated by Narayana.
Saga / MicroProfile LRA (transfer-lra, port 8090 and account, port 8081): a compensation-based consistency example across autonomous services, coordinated by a Narayana LRA coordinator.

Both expose the same /xfers REST contract and are driven by the same shared
test suite (transfer-tck), so any difference you observe is a difference in
transaction strategy and nothing else.

Modules

The following modules are part of the workshop project.

Module	Role
`common`	Shared library: `Common` utility, the transfer DTOs (`TransferDto`, `TransferRequest`, `TransferResponse`, `TransferStatus`), the application exception hierarchy and the single `ApplicationExceptionMapper` that maps them to HTTP status codes.
`account-repository`	Shared persistence layer for accounts: the `Account` entity, `AccountDto`, the `AccountRepository` interface and its two implementations. Depended on by `account` and by `transfer` — and pointedly not by `transfer-lra`.
`transfer-tck`	The REST contract both transfer implementations must satisfy, as an abstract test class. Test tooling is at compile scope so consumers depend on it with `<scope>test</scope>`.
`account`	Account microservice (port 8081). Owns the `accounts` schema. CRUD + debit/credit, plus the LRA participant endpoints under `/lra/accounts`.
`transfer`	XA coordinator (port 8080). Two XA datasources (`accounts`, `xfers`). Transfer CRUD plus the 2PC transfer operation.
`transfer-lra`	Saga orchestrator (port 8090). One plain datasource for its own transfer log; reaches balances only through the account service's API.

All four modules carry the Jandex plugin so their @Entity, @Provider and CDI bean
classes are indexed when consumed as external dependencies.

Endpoints

Three services expose an HTTP API, each with a Swagger UI at /q/swagger-ui. The
rows marked as callbacks are invoked by the LRA coordinator, not by clients.

Service	Method	Path	Purpose
`account` (8081)	`GET`	`/accounts`	List the accounts
`account` (8081)	`POST`	`/accounts`	Create an account
`account` (8081)	`GET`	`/accounts/{accountId}`	Read one account
`account` (8081)	`PUT`	`/accounts/{accountId}`	Update one account
`account` (8081)	`DELETE`	`/accounts/{accountId}`	Delete one account
`account` (8081)	`POST`	`/accounts/{accountId}/debit`	Debit, amount in the body
`account` (8081)	`POST`	`/accounts/{accountId}/credit`	Credit, amount in the body
`account` (8081)	`POST`	`/lra/accounts/{accountId}/debit`	Reserve a debit, `@LRA(MANDATORY)`
`account` (8081)	`POST`	`/lra/accounts/{accountId}/credit`	Reserve a credit, `@LRA(MANDATORY)`
`account` (8081)	`GET`	`/lra/accounts/{accountId}/availability`	Balance, held and available amounts
`account` (8081)	`PUT`	`/lra/accounts/complete`	`@Complete` callback
`account` (8081)	`PUT`	`/lra/accounts/compensate`	`@Compensate` callback
`account` (8081)	`GET`	`/lra/accounts/status`	`@Status` callback
`account` (8081)	`DELETE`	`/lra/accounts/forget`	`@Forget` callback
`transfer` (8080)	`POST`	`/xfers`	Transfer, in one 2PC transaction
`transfer` (8080)	`GET`	`/xfers`	List the transfer log
`transfer` (8080)	`GET`	`/xfers/{transferId}`	Read one transfer
`transfer` (8080)	`PUT`	`/xfers/{transferId}`	Update one transfer
`transfer` (8080)	`DELETE`	`/xfers/{transferId}`	Delete one transfer
`transfer-lra` (8090)	`POST`	`/xfers`	Transfer, as a saga, `@LRA(REQUIRED)`
`transfer-lra` (8090)	`GET`	`/xfers`	List the transfer log
`transfer-lra` (8090)	`GET`	`/xfers/{transferId}`	Read one transfer
`transfer-lra` (8090)	`PUT`	`/xfers/{transferId}`	Update one transfer
`transfer-lra` (8090)	`DELETE`	`/xfers/{transferId}`	Delete one transfer
`transfer-lra` (8090)	`PUT`	`/xfers/lra/complete`	`@Complete` callback
`transfer-lra` (8090)	`PUT`	`/xfers/lra/compensate`	`@Compensate` callback
`transfer-lra` (8090)	`GET`	`/xfers/lra/status`	`@Status` callback
`transfer-lra` (8090)	`DELETE`	`/xfers/lra/forget`	`@Forget` callback

Build & test

The following command runs the integration tests:

mvn clean verify

Here is the list of the integration tests provided with the project:

AbstractMoneyTransferContractIT (transfer-tck): this is and abstract class serving as a superclass for all the integration tests. It defines the shared scenarios: happy path, insufficient funds, unknown account, listing and deletion. Assertions are on deltas*, and the balance/count probes are abstract, because the XA service can read the databases directly while the saga service can only get them by calling the API over HTTP. Failure paths assert the response body as well as the status. Both stacks must return the business error rather than transaction plumbing, which a status-only assertion would not catch.
MoneyTransferIT (transfer): the contract against XA, with repository-based probes.
MoneyTransferSagaIT (transfer-lra): the contract against LRA, with HTTP probes, plus saga-only assertions about the COMPENSATED audit row and released reservations.
AccountResourceIT (account): account CRUD, debit/credit, 404 on unknown account, and rejection of overdrafts and invalid amounts.

Run the full stack

In order to run the full stack, production like, proceed as follows:

# Build the container images (container-image.build=true is enabled)
mvn clean package
docker compose up -d

docker-compose.yaml starts the whole comparison:

Service	Port	Role
`accounts-db`	5432	Accounts, `max_prepared_transactions=100` for XA
`xfers-db`	5433	XA transfer log, `max_prepared_transactions=100`
`xfers-lra-db`	5434	Saga transfer log (no XA needed)
`lra-coordinator`	50000	`quay.io/jbosstm/lra-coordinator`
`account`	8081	CRUD + LRA participant
`transfer`	8080	XA/2PC
`transfer-lra`	8090	Saga/LRA

Both transfer services run against the same accounts, so you can drive the same
transfer through each and compare:

BODY='{"sourceAccountId":"ACC1","destinationAccountId":"ACC2","amount":10.00,"currency":"EUR"}'
curl -s -XPOST -H 'Content-Type: application/json' -d "$BODY" http://localhost:8080/xfers  # XA
curl -s -XPOST -H 'Content-Type: application/json' -d "$BODY" http://localhost:8090/xfers  # Saga
curl -s http://localhost:8081/lra/accounts/ACC1/availability                                # reservations

$ docker compose up -d
$ ./test-all.sh

=== Account API - http://localhost:8081/accounts ===
PASS POST /accounts (create ACC90, 1000.00) -> 201
PASS POST /accounts (create ACC91, 0.00) -> 201
PASS POST /accounts (create ACC92, 10.00) -> 201
PASS GET /accounts/ACC90 -> 200
PASS balance(ACC90) == 1000.00
PASS GET /accounts (list) -> 200
PASS PUT /accounts/ACC90 (rename owner) -> 200
PASS GET /accounts/ACC90 (confirm rename) -> 200
PASS customerName updated
PASS POST /accounts/ACC90/credit (50.00) -> 200
PASS balance(ACC90) == 1050.00
PASS POST /accounts/ACC90/debit (200.00) -> 200
PASS balance(ACC90) == 850.00

=== Account API - negative cases ===
PASS POST credit (-1.00) rejected -> 400
PASS POST debit (0.00) rejected -> 400
PASS POST debit (999999.00) insufficient funds -> 400
PASS GET /accounts/NOSUCH -> 404
PASS POST credit on unknown account -> 404
PASS POST credit without Content-Type -> 415
PASS balance(ACC90) == 850.00
PASS DELETE /accounts/ACC92 -> 204
PASS GET deleted account -> 404
PASS DELETE already-deleted account -> 404

=== Account LRA participant API - http://localhost:8081/lra/accounts ===
PASS GET /lra/accounts/ACC90/availability -> 200
PASS availability exposes balance/held/available
PASS POST /lra/accounts/ACC90/debit without LRA context -> 412
PASS POST /lra/accounts/ACC90/credit without LRA context -> 412
PASS balance(ACC90) == 850.00

=== XA Transfer API (2PC) - http://localhost:8080/xfers ===
PASS POST /xfers (ACC90 -> ACC91, 100.00) -> 200
PASS transferId returned: raizmjf
PASS balance(ACC90) == 750.00
PASS balance(ACC91) == 100.00
PASS GET /xfers/raizmjf -> 200
PASS GET /xfers (list) -> 200
PASS PUT /xfers/raizmjf (currency -> USD) -> 200

=== XA Transfer API - negative cases (nothing must move) ===
PASS POST /xfers insufficient funds -> 400
PASS POST /xfers negative amount -> 400
PASS POST /xfers unknown source -> 404
PASS POST /xfers unknown destination -> 404
PASS balance(ACC90) == 750.00
PASS balance(ACC91) == 100.00
PASS GET /xfers/NOSUCH -> 404
PASS DELETE /xfers/raizmjf -> 204
PASS GET deleted transfer -> 404

=== Saga Transfer API (LRA) - http://localhost:8090/xfers ===
PASS POST /xfers (ACC90 -> ACC91, 25.00) -> 200
PASS transferId returned: etmlebm
PASS balance(ACC90) == 725.00
PASS balance(ACC91) == 125.00
PASS GET /xfers/etmlebm -> 200
PASS GET /xfers (list, includes compensated) -> 200
PASS @Complete flipped the transfer to COMPLETED

=== Saga Transfer API - cancellation and compensation ===
PASS POST /xfers insufficient funds (saga cancels) -> 400
PASS balance(ACC90) == 725.00
PASS balance(ACC91) == 125.00
PASS @Compensate logged the cancelled transfer as COMPENSATED
PASS POST /xfers unknown destination (saga cancels) -> 404
PASS balance(ACC90) == 725.00
PASS GET availability after settled sagas -> 200
PASS held == 0 (no reservation left dangling)
PASS PUT /xfers/etmlebm (currency -> USD) -> 200
PASS GET /xfers/NOSUCH -> 404
PASS DELETE /xfers/etmlebm -> 204
PASS GET deleted transfer -> 404

=== Saga participant callbacks - @Status and @Forget (transfer-lra) ===
PASS coordinator started LRA: http://lra-coordinator:8080/lra-coordinator/0_ffffac120002_a03b_6ad35817_1ed
PASS POST /xfers with an externally started LRA -> 412
PASS GET /xfers/lra/status (@Status) -> 200
PASS @Status reports Compensated for the cancelled LRA
PASS balance(ACC90) moved by 0 (now 725.00)
PASS DELETE /xfers/lra/forget (@Forget) -> 200
PASS GET /xfers/lra/status after @Forget -> 404
PASS @Forget kept the transfer, only dropped its LRA id

=== Account LRA participant API - driving a saga by hand ===
PASS coordinator started LRA: http://lra-coordinator:8080/lra-coordinator/0_ffffac120002_a03b_6ad35817_1f2
PASS POST /lra/accounts/ACC90/debit (40.00, in LRA) -> 200
PASS balance(ACC90) moved by 0 (now 725.00)
PASS held(ACC90) moved by 40.00 (now 40.00)
PASS POST /lra/accounts/ACC91/credit (40.00, in LRA) -> 200
PASS balance(ACC91) moved by 0 (now 125.00)
PASS coordinator closed the LRA -> 200
PASS balance(ACC90) moved by -40.00 (now 685.00)
PASS balance(ACC91) moved by 40.00 (now 165.00)
PASS held(ACC90) moved by 0 (now 0)

=== Account LRA participant API - cancelling a saga by hand ===
PASS coordinator started LRA: http://lra-coordinator:8080/lra-coordinator/0_ffffac120002_a03b_6ad35817_1f7
PASS POST /lra/accounts/ACC90/debit (15.00, in LRA) -> 200
PASS held(ACC90) moved by 15.00 (now 15.00)
PASS coordinator cancelled the LRA -> 200
PASS balance(ACC90) moved by 0 (now 685.00)
PASS held(ACC90) moved by 0 (now 0)

=== Summary ===
87 passed, 0 failed

12. Comparison

Both implementations satisfy the same test contract. The following differences
are therefore differences of mechanism and of consequence, not of capability.

Dimension	XA and two-phase commit	Saga and LRA
Coordinator	Embedded in the application process	Separate process, must call participants back
Data ownership	Coordinator holds the resource managers, so services share a database	Each service retains its own data
Isolation	Complete; no intermediate state is observable	Absent by design; a reservation is observable while in flight
Failure	Rollback leaves no trace whatsoever	Leaves a record that the operation was attempted and undone
Locks	Held between prepare and commit	None held across the action
Availability	Participants block if the coordinator fails while in doubt	Participants remain available; completion may occur later
Location of difficulty	Infrastructure, written once	Application code, written for each operation
Failure of the undo	Not applicable; nothing was committed	Possible, unless reservations are used

Two entries deserve comment.

The row concerning failure is frequently presented as an advantage of 2PC on the
grounds that the rollbacks are clean. It may equally be regarded as a loss of
information. A canceled saga records that a transfer was attempted and
subsequently undone, which is an audit trail that a rollback cannot produce
because the rows were never committed. Whether this constitutes an advantage
depends entirely on whether the business is required to account for attempts as
well as for outcomes, and this is a question for the domain rather than for the
architecture.

13. The Present and the Future

An important development merit attention: the growing use of the outbox
pattern with event streaming, which achieves atomicity between a database change
and a message by writing both to the same database and publishing asynchronously.
This is neither 2PC nor a saga in the classical sense, and for many integration
problems it is a better answer than either. The second is the increasing
availability of formal verification tools for distributed protocols, which offers
some prospect that compensation logic might eventually be checked rather than
merely reviewed.

The underlying tension, however, is not a matter of technology and will not be
resolved by this development. Atomicity across independent parties
requires either that they transfer autonomy to a coordinator or that they accept
observable intermediate states. The FLP (Fisher, Lynch and Paterson) result and its relatives indicate that no
implementation will escape this choice. What improves is the quality of the tools
with which each side of the choice may be pursued, and the clarity with which the
choice is presented to the practitioners.

References and Further Reading

Gray, J. Notes on Data Base Operating Systems, 1978.
Fischer, M., Lynch, N., Paterson, M. Impossibility of Distributed Consensus with One Faulty Process, Journal of the ACM, 1985.
Garcia-Molina, H., Salem, K. Sagas, ACM SIGMOD, 1987.
X/Open. Distributed Transaction Processing: The XA Specification.
Object Management Group. Object Transaction Service.
Eclipse MicroProfile. MicroProfile LRA Specification.
The accompanying source code, quarkus-distributed-tx, containing both implementations, the shared contract test suite and a Docker Compose deployment that runs the two stacks side by side.

50 Shades of Quarkus RESTful Services

Nicolas DUMINIL — Fri, 25 Apr 2025 14:30:54 +0000

I'm so pleased to let my network know that my new booklet, entitled "50 Shades of Quarkus RESTful Services", is now available in both paperback and hardcover format. The Kindle format was already available as well, since last month.

This booklet is dedicated to software architects and developers who think that the allegedly "no-code" solutions are rubbish and the ML and LLM based tools, while unavoidable nowadays, aren't meant to generate end-to-end code.

What's inside:

Historical approach of the RESTful services, from the RPC/Corba/DCOM ancestors, up to date.
Quarkus RESTful services basics and annotations. Eclipse MicroProfile implementation by Quarkus.
Quarkus Synchronous RESTful services and clients.
Quarkus Asynchronous RESTful services and clients.
Quarkus Reactive RESTful services and clients.
Anatomy of enterprise grade applications.
Quarkus microservices based implemntation.
Quarkus unit, integration and end-to-end testing.

You don't need to be a Java champion to read this booklet, just be willing to become one. Ready ?

https://shorturl.at/wtQVN

50 Shades of Java Executors: A deep dive into the Java multi-threading world

Nicolas DUMINIL — Fri, 25 Apr 2025 13:56:51 +0000

I'm pleased to announce the publication of my most recent booklet on concurrent programming techniques in Java, with a particular focus on race condition management through multi-threading and executors. It explores modern concurrency patterns and implementations, highlighting the latest features introduced in Java 21 and 23 LTS (Long Term Support) releases. Special attention is given to the evolution of Java's executor framework and its role in managing concurrent operations efficiently.
This booklet serves as a practical guide for developers seeking to understand and implement robust concurrent programming solutions using Java's latest threading capabilities. The presented concepts are illustrated by code examples implementing real business cases. A full benchmark comparing all the presented solutions is provided at the end of the report.

https://www.amazon.fr/50-Shades-Java-Executors-multi-threading/dp/B0DPJ1ZFLS

DEV Community: Nicolas DUMINIL

Spring AI or LangChain4j? One App, Three Stacks, One Test

One interface, three implementations

Spring AI: a fluent ChatClient

LangChain4j: a plain ChatModel, and the same code on two runtimes

One test to compare them all

What the comparison reveals

Where this goes next

Using Anthropic evaluation to check Claude Code plugin efficiency

Context

A criterion for useful skill content

Restructuring before measuring

The measurement method

First results

Trimming, and the regression the evaluation caught

Final state and cost

Lessons

Limitations

Time-Based One-Time Passwords with HashiCorp Vault and Quarkus

Abstract

1. What is TOTP and what problem does it solve?

1.1 The weakness of the static password

1.2 Multi-factor authentication

1.3 The algorithm

2. What is HashiCorp Vault and what is it used for?

3. Use cases

4. Vault configuration

4.1 The server configuration in vault.hcl

4.2 The access policy in totp-policy.hcl

4.3 The bootstrap script init.sh

5. The application code

5.1 The service TotpService

5.2 The resource TotpApi

5.3 The integration tests

6. Deployment

7. Conclusion

Distributed Transactions in Enterprise Applications: From X/Open to MicroProfile LRA

Abstract

1. Origins: X/Open, and the Formalization of 2PC

2. Several Decades of Service

3. OTS, JTS and JTA

4. CORBA and IIOP as the Transport of Context

5. The Decline of Heavyweight Servers and the Rise of Lighter Frameworks

6. What the Lighter Frameworks Lost

7. The Saga Pattern, and the Ease of Implementing It Incorrectly

8. MicroProfile LRA

9. The XA Implementation in Detail

Configuration

The transactional method

The protocol as executed

The architectural cost

10. The LRA Implementation in Detail

Reserve, then confirm

Idempotency, enforced twice

11. The Project

Modules

Endpoints

Build & test

Run the full stack

12. Comparison

13. The Present and the Future

References and Further Reading

Distributed Transactions in Enterprise Applications: From X/Open to MicroProfile LRA

Abstract

1. Origins: X/Open, and the Formalization of 2PC

2. Several Decades of Service

3. OTS, JTS and JTA

4. CORBA and IIOP as the Transport of Context

5. The Decline of Heavyweight Servers and the Rise of Lighter Frameworks

6. What the Lighter Frameworks Lost

7. The Saga Pattern, and the Ease of Implementing It Incorrectly

8. MicroProfile LRA

9. The XA Implementation in Detail

Configuration

The transactional method

The protocol as executed

The architectural cost

10. The LRA Implementation in Detail

Reserve, then confirm

Idempotency, enforced twice

4.1 The server configuration in `vault.hcl`

4.2 The access policy in `totp-policy.hcl`

4.3 The bootstrap script `init.sh`

5.1 The service `TotpService`

5.2 The resource `TotpApi`