Jakarta Transactions

In the X/Open XA architecture, a transaction manager or transaction processing monitor (TP monitor) coordinates the transactions across multiple resources such as databases and message queues. Each resource has its own resource manager. The resource manager typically has its own API for manipulating the resource, for example the JDBC API to work with relational databases. In addition, the resource manager allows a TP monitor to coordinate a distributed transaction between its own and other resource managers. Finally, there is the application which communicates with the TP monitor to begin, commit or roll back the transactions. The application also communicates with the individual resources using their own API to modify the resource.

The JTA API consists of classes in two Java packages:

• javax.transaction
• javax.transaction.xa

The JTA is modelled on the X/Open XA architecture, but it defines two different APIs for demarcating transaction boundaries. It distinguishes between an application server such as an EJB server and an application component. It provides an interface, javax.transaction.TransactionManager, that is used by the application server itself to begin, commit and roll back the transactions. It provides a different interface, the javax.transaction.UserTransaction, that is used by general client code such as a servlet or an EJB to manage the transactions.

The JTA architecture requires that each resource manager must implement the javax.transaction.xa.XAResource interface in order to be managed by the TP monitor. As stated previously, each resource will have its own specific API, for instance:

• relational databases use JDBC
• messaging services use JMS
• generalized EIS (Enterprise Information System) resources use Java EE Connector API.

The Jakarta Transactions API consists of three elements: a high-level application transaction demarcation interface, a high-level transaction manager interface intended for an application server, and a standard Java mapping of the X/Open XA protocol intended for a transactional resource manager.

@RequestScoped
public class ExampleBean {

    @Transactional
    public void foo() { // A transaction is active here
        
        // Do work

    } // After the method returns transaction is committed or rolled back
}

@TransactionScoped
public class TxScopedBean {
    public int number;

    public int getNumber() {return number;}
    public void setNumber(int number) {this.number = number;}
}

@RequestScoped
public class ExampleBean {

    @Inject
    private TxScopedBean txScopedBean;

    @Transactional
    public void foo() {
        txScopedBean.setNumber(1);
    }

    @Transactional
    public void bar() {
        System.out.print(tXscopedBean.getNumber());
    }
}

EJB servers are required to support the UserTransaction interface for use by EJB beans with the BEAN value in the javax.ejb.TransactionManagement annotation (this is called bean-managed transactions or BMT). The UserTransaction interface is exposed to EJB components through either the EJBContext interface using the getUserTransaction method, or directly via injection using the general @Resource annotation. Thus, an EJB application does not interface with the Transaction Manager directly for transaction demarcation; instead, the EJB bean relies on the EJB server to provide support for all of its transaction work as defined in the Jakarta Enterprise Beans Specification. (The underlying interaction between the EJB Server and the TM is transparent to the application; the burden of implementing transaction management is on the EJB container and server provider.[1])

The code sample below illustrates the usage of UserTransaction via bean-managed transactions in an EJB session bean:

@Stateless
@TransactionManagement(BEAN)
public class ExampleBean {

    @Resource
    private UserTransaction utx;

    public void foo() {
        // start a transaction
        utx.begin();

        // Do work

        // Commit it
        utx.commit();
    }
}

Alternatively, the UserTransaction can be obtained from the SessionContext:

@Stateless
@TransactionManagement(BEAN)
public class ExampleBean {

    @Resource
    private SessionContext ctx;

    public void foo() {
        UserTransaction utx = ctx.getUserTransaction();

        // start a transaction
        utx.begin();

        // Do work

        // Commit it
        utx.commit();
    }
}

Note though that in the example above if the @TransactionManagement(BEAN) annotation is omitted, a JTA transaction is automatically started whenever foo() is called and is automatically committed or rolled back when foo() is exited. Making use of a UserTransaction is thus not necessary in EJB programming, but might be needed for very specialized code.

The UserTransaction should be available under java:comp/UserTransaction (if a JTA implementation is installed in the environment).

• Java transaction service

• Official website
• JSR 907
• Atomikos transaction manager website
• Narayana transaction manager website
• Bitronix transaction manager website