Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

12.2. Transaction Concepts

12.2.1. About Transactions

A transaction consists of two or more actions which must either all succeed or all fail. A successful outcome is a commit, and a failed outcome is a roll-back. In a roll-back, each member's state is reverted to its state before the transaction attempted to commit.
The typical standard for a well-designed transaction is that it is Atomic, Consistent, Isolated, and Durable (ACID).

12.2.2. About ACID Properties for Transactions

ACID is an acronym which stands for Atomicity, Consistency, Isolation, and Durability. This terminology is usually used in the context of databases or transactional operations.

ACID Definitions

For a transaction to be atomic, all transaction members must make the same decision. Either they all commit, or they all roll back. If atomicity is broken, what results is termed a heuristic outcome.
Consistency means that data written to the database is guaranteed to be valid data, in terms of the database schema. The database or other data source must always be in a consistent state. One example of an inconsistent state would be a field in which half of the data is written before an operation aborts. A consistent state would be if all the data were written, or the write were rolled back when it could not be completed.
Isolation means that data being operated on by a transaction must be locked before modification, to prevent processes outside the scope of the transaction from modifying the data.
Durability means that in the event of an external failure after transaction members have been instructed to commit, all members will be able to continue committing the transaction when the failure is resolved. This failure may be related to hardware, software, network, or any other involved system.

12.2.3. About the Transaction Coordinator or Transaction Manager

The terms Transaction Coordinator and Transaction Manager are mostly interchangeable in terms of transactions with JBoss EAP 6. The term Transaction Coordinator is usually used in the context of distributed transactions.
In JTA transactions, The Transaction Manager runs within JBoss EAP 6 and communicates with transaction participants during the two-phase commit protocol.
The Transaction Manager tells transaction participants whether to commit or roll back their data, depending on the outcome of other transaction participants. In this way, it ensures that transactions adhere to the ACID standard.
In JTS transactions, the Transaction Coordinator manages interactions between transaction managers on different servers.

12.2.4. About Transaction Participants

A transaction participant is any process within a transaction, which has the ability to commit or roll back state. This may be a database or other application. Each participant of a transaction independently decides whether it is able to commit or roll back its state, and only if all participants can commit, does the transaction as a whole succeed. Otherwise, each participant rolls back its state, and the transaction as a whole fails. The Transaction Manager coordinates the commit or rollback operations and determines the outcome of the transaction.

12.2.5. About Java Transactions API (JTA)

Java Transactions API (JTA) is part of Java Enterprise Edition specification. It is defined in JSR-907.
Implementation of JTA is done using Transaction manager, which is covered by project Narayana for JBoss EAP application server. Transaction manager allows application to assign various resources, for example, database or JMS brokers, through a single global transaction. The global transaction is referred as XA transaction. Only resources with XA capabilities can be included in a transaction.
In this document, JTA refers to Java Transaction API, this term is used to indicate how the transaction manager processes the transactions. Transaction manager works in JTA transactions mode, the data is shared via memory and transaction context is transferred by remote EJB calls. In JTS mode, the data is shared by sending Common Object Request Broker Architecture (CORBA)messages and transaction context is transferred by IIOP calls. Both modes support distribution of transaction over multiple EAP servers.
Annotations is a method for creating and controlling transactions within your code.

12.2.6. About Java Transaction Service (JTS)

Java Transaction Service (JTS) is a mapping of the Object Transaction Service (OTS) to Java. Java applications use the JTA API to manage transactions. JTA then interacts with a JTS transaction implementation when the transaction manager is switched to JTS mode. To use special JTS capabilities, for example, nested transactions, you need to manually use the JTS API.
JTS works over the IIOP protocol. Transaction managers that use JTS, communicate with each other using a process called an Object Request Broker (ORB), using a communication standard called Common Object Request Broker Architecture (CORBA).
Using JTA API from an application standpoint, a JTS transaction behaves in the same way as a JTA transaction.


The implementation of JTS included in JBoss EAP 6 supports distributed transactions. The difference from fully-compliant JTS transactions is interoperability with external third-party ORBs. This feature is unsupported with JBoss EAP 6. Supported configurations distribute transactions across multiple JBoss EAP 6 containers only.

12.2.7. About XA Datasources and XA Transactions

An XA datasource is a datasource which can participate in an XA global transaction.
An XA transaction is a transaction which can span multiple resources. It involves a coordinating transaction manager, with one or more databases or other transactional resources, all involved in a single global transaction.

12.2.8. About XA Recovery

The Java Transaction API (JTA) allows distributed transactions across multiple X/Open XA resources. XA stands for Extended Architecture which was developed by the X/Open Group to define a transaction which uses more than one back-end data store. The XA standard describes the interface between a global Transaction Manager (TM) and a local resource manager. XA allows multiple resources, such as application servers, databases, caches, and message queues, to participate in the same transaction, while preserving atomicity of the transaction. Atomicity means that if one of the participants fails to commit its changes, the other participants abort the transaction, and restore their state to the same status as before the transaction occurred.
XA Recovery is the process of ensuring that all resources affected by a transaction are updated or rolled back, even if any of the resources are transaction participants crash or become unavailable. Within the scope of JBoss EAP 6, the Transaction subsystem provides the mechanisms for XA Recovery to any XA resources or subsystems which use them, such as XA datasources, JMS message queues, and JCA resource adapters.
XA Recovery happens without user intervention. In the event of an XA Recovery failure, errors are recorded in the log output. Contact Red Hat Global Support Services if you need assistance.

12.2.9. About the 2-Phase Commit Protocol

The Two-phase commit protocol (2PC) refers to an algorithm to determine the outcome of a transaction.
Phase 1

In the first phase, the transaction participants notify the transaction coordinator whether they are able to commit the transaction or must roll back.

Phase 2

In the second phase, the transaction coordinator makes the decision about whether the overall transaction should commit or roll back. If any one of the participants cannot commit, the transaction must roll back. Otherwise, the transaction can commit. The coordinator directs the transactions about what to do, and they notify the coordinator when they have done it. At that point, the transaction is finished.

12.2.10. About Transaction Timeouts

In order to preserve atomicity and adhere to the ACID standard for transactions, some parts of a transaction can be long-running. Transaction participants need to lock parts of datasources when they commit, and the transaction manager needs to wait to hear back from each transaction participant before it can direct them all whether to commit or roll back. Hardware or network failures can cause resources to be locked indefinitely.
Transaction timeouts can be associated with transactions in order to control their lifecycle. If a timeout threshold passes before the transaction commits or rolls back, the timeout causes the transaction to be rolled back automatically.
You can configure default timeout values for the entire transaction subsystem, or you disable default timeout values, and specify timeouts on a per-transaction basis.

12.2.11. About Distributed Transactions

A distributed transaction, is a transaction with participants on multiple JBoss EAP 6 servers. Java Transaction Service (JTS) specification mandates that JTS transactions be able to be distributed across application servers from different vendors (transaction distribution among servers from different vendors is not a supported feature). Java Transaction API (JTA) does not define that but JBoss EAP 6 supports distributed JTA transactions among JBoss EAP6 servers.


In other app server vendor documentation, you can find that term distributed transaction means XA transaction. In context of JBoss EAP 6 documentation, the distributed transaction refers transactions distributed among several application servers. Transaction which consists from different resources (for example, database resource and jms resource) are referred as XA transactions in this document. For more information, refer Section 12.2.6, “About Java Transaction Service (JTS)” and Section 12.2.7, “About XA Datasources and XA Transactions”.

12.2.12. About the ORB Portability API

The Object Request Broker (ORB) is a process which sends and receives messages to transaction participants, coordinators, resources, and other services distributed across multiple application servers. An ORB uses a standardized Interface Description Language (IDL) to communicate and interpret messages. Common Object Request Broker Architecture (CORBA) is the IDL used by the ORB in JBoss EAP 6.
The main type of service which uses an ORB is a system of distributed Java Transactions, using the Java Transaction Service (JTS) protocol. Other systems, especially legacy systems, may choose to use an ORB for communication, rather than other mechanisms such as remote Enterprise JavaBeans or JAX-WS or JAX-RS Web Services.
The ORB Portability API provides mechanisms to interact with an ORB. This API provides methods for obtaining a reference to the ORB, as well as placing an application into a mode where it listens for incoming connections from an ORB. Some of the methods in the API are not supported by all ORBs. In those cases, an exception is thrown.
The API consists of two different classes:

ORB Portability API Classes

  • com.arjuna.orbportability.orb
  • com.arjuna.orbportability.oa
Refer to the JBoss EAP 6 Javadocs bundle from the Red Hat Customer Portal for specific details about the methods and properties included in the ORB Portability API.

12.2.13. About Nested Transactions

Nested transactions are transactions where some participants are also transactions.

Benefits of Nested Transactions

Fault Isolation
If a subtransaction rolls back, perhaps because an object it is using fails, the enclosing transaction does not need to roll back.
If a transaction is already associated with a call when a new transaction begins, the new transaction is nested within it. Therefore, if you know that an object requires transactions, you can create them within the object. If the object's methods are invoked without a client transaction, then the object's transactions are top-level. Otherwise, they are nested within the scope of the client's transactions. Likewise, a client does not need to know whether an object is transactional. It can begin its own transaction.
Nested Transactions are only supported as part of the Java Transaction Service (JTS) API, and not part of the Java Transaction API (JTA). Attempting to nest (non-distributed) JTA transactions results in an exception.
Modifying JBoss EAP 6 configuration of transaction subsystem to use JTS does not indicate that nested transaction will be used or activated. If you need to use them, you have to directly use ORB API as JTA API does not provide any method to start the nested transaction.

12.2.14. About XML Transaction Service

The XML Transaction Service (XTS) component supports the coordination of private and public Web Services in a business transaction. Using XTS, you can coordinate complex business transactions in a controlled and reliable manner. The XTS API supports a transactional coordination model based on the WS-Coordination, WS-Atomic Transaction, and WS-Business Activity protocols. Overview of Protocols Used by XTS

This topic describes the fundamental concepts associated with the WS-Coordination (WS-C), WS-Atomic Transaction (WS-AT) and WS-Business Activity (WS-BA) protocols, as defined in the specifications of each protocol.
The WS-C specification defines a framework that allows different coordination protocols to be plugged in to coordinate work between clients, services, and participants.
WS-T protocol comprises the pair of transaction coordination protocols, WS-Atomic Transaction (WS-AT) and WS-Business Activity (WS-BA) , which utilize the coordination framework provided by WS-C. WS-T is developed to unify existing traditional transaction processing systems, allowing them to communicate reliably with one another. Web Services-Atomic Transaction Process

An atomic transaction (AT) is designed to support short duration interactions where ACID semantics are appropriate. Within the scope of an AT, Web Services typically employ bridging to access XA resources, such as databases and message queues, under the control of the WS-T. When the transaction terminates, the participant propagates the outcome decision of the AT to the XA resources, and the appropriate commit or rollback actions are taken by each participant.
Atomic Transaction Process

  1. To initiate an AT, the client application first locates a WS-C Activation Coordinator Web Service that supports WS-T.
  2. The client sends a WS-C CreateCoordinationContext message to the service, specifying as its coordination type.
  3. The client receives an appropriate WS-T context from the activation service.
  4. The response to the CreateCoordinationContext message, the transaction context, has its CoordinationType element set to the WS-AT namespace, It also contains a reference to the atomic transaction coordinator endpoint, the WS-C Registration Service, where participants can be enlisted.
  5. The client normally proceeds to invoke Web Services and complete the transaction, either committing all the changes made by the Web Services, or rolling them back. In order to be able to drive this completion, the client must register itself as a participant for the Completion protocol, by sending a register message to the Registration Service whose endpoint was returned in the Coordination Context.
  6. Once registered for completion, the client application then interacts with Web Services to accomplish its business-level work. With each invocation of a business Web Service, the client inserts the transaction context into a SOAP header block, such that each invocation is implicitly scoped by the transaction. The toolkits that support WS-AT aware Web Services provide facilities to correlate contexts found in SOAP header blocks with back-end operations. This ensures that modifications made by the Web Service are done within the scope of the same transaction as the client and subject to commit or rollback by the Transaction Coordinator.
  7. Once all the necessary application work is complete, the client can terminate the transaction, with the intent of making any changes to the service state permanent. The completion participant instructs the coordinator to try to commit or roll back the transaction. When the commit or rollback operation completes, a status is returned to the participant to indicate the outcome of the transaction. Web Services-Business Activity Process

Web Services-Business Activity (WS-BA) defines a protocol for Web Services based applications to enable existing business processing and workflow systems to wrap their proprietary mechanisms and interoperate across implementations and business boundaries.
Unlike the WS-AT protocol model, where participants inform the transaction coordinator of their state only when asked, a child activity within a BA can specify its outcome to the coordinator directly, without waiting for a request. A participant may choose to exit the activity or notify the coordinator of a failure at any point. This feature is useful when tasks fail because the notification can be used to modify the goals and drive processing forward, without waiting until the end of the transaction to identify failures.
WS-BA Process

  1. Services are requested to do work.
  2. Wherever these services have the ability to undo any work, they inform the BA, in case the BA later decides the cancel the work. If the BA suffers a failure. it can instruct the service to execute its undo behavior.

The BA protocols employ a compensation-based transaction model. When a participant in a business activity completes its work, it may choose to exit the activity. This choice does not allow any subsequent rollback. Alternatively, the participant can complete its activity, signaling to the coordinator that the work it has done can be compensated if, at some later point, another participant notifies a failure to the coordinator. In this latter case, the coordinator asks each non-exited participant to compensate for the failure, giving them the opportunity to execute whatever compensating action they consider appropriate. If all participants exit or complete without failure, the coordinator notifies each completed participant that the activity has been closed. Transaction Bridging Overview

Transaction Bridging describes the process of linking the Java EE and WS-T domains. The transaction bridge component txbridge provides bi-directional linkage, such that either type of transaction may encompass business logic designed for use with the other type. The technique used by the bridge is a combination of interposition and protocol mapping.
In the transaction bridge, an interposed coordinator is registered into the existing transaction and performs the additional task of protocol mapping; that is, it appears to its parent coordinator to be a resource of its native transaction type, whilst appearing to its children to be a coordinator of their native transaction type, even though these transaction types differ.
The transaction bridge resides in the package org.jboss.jbossts.txbridge and its sub-packages. It consists of two distinct sets of classes, one for bridging in each direction.
For more details, see Transaction Bridge Documentation.