Java Transaction API (JTA)

The Java™ Transaction API (JTA) can be used to coordinate transactional updates to multiple resource managers.

You can use the Java Transaction API (JTA) to coordinate transactional updates to CICS® resources and other third party resource managers, such as a type 4 database driver connection within a Liberty JVM server. In this scenario, the Liberty transaction manager is the transaction coordinator and the CICS unit of work is subordinate, as though the transaction had originated outside of the CICS system.

Note: If you have the JVM profile option com.ibm.cics.jvmserver.wlp.jta.integration=false and use autoconfigure, or are manually configuring server.xml and include the <cicsts_jta Integration="false"/> element, then the CICS unit-of-work will not participate in the JTA transaction and is committed or rolled back separately.

A type 2 driver connection to a local DB2® database using a CICS data source is accessed using the CICS DB2 attachment. It is not necessary to use JTA to coordinate with updates to other CICS resources.

In JTA you create a UserTransaction object to encapsulate and coordinate updates to multiple resource managers. The following code fragment shows how to create and use a User Transaction:

InitialContext ctx = new InitialContext();
UserTransaction tran = (UserTransaction)ctx.lookup("java:comp/UserTransaction");

DataSource ds = (DataSource)ctx.lookup("jdbc/SomeDB");
Connection con = ds.getConnection();

// Start the User Transaction
tran.begin();

// Perform updates to CICS resources via JCICS API and
// to database resources via JDBC/SQLJ APIs

if (allOk) {
    // Commit updates on both systems
    tran.commit();
} else {
    // Backout updates on both systems
    tran.rollback();
}

If you are using an OSGi application, ensure that you include the following entry in the MANIFEST.MF:

Import-Package: javax.transaction;version="[1.1,2)"

Your development environment might not highlight this dependency by default. It is advisable to explicitly check and to ensure the minimum version of 1.1 is specified. If you allow the runtime environment to resolve the dependency itself, it might resolve to the lower version of the package from the underlying JRE, and conflict with the Liberty runtime.

Unlike a CICS unit of work, a UserTransaction must be explicitly started using the begin() method. Invoking begin() causes CICS to commit any updates that may have been made prior to starting the UserTransaction. The UserTransaction is terminated by invoking either of the commit() or rollback() methods, or by the web container when the web application terminates. While the UserTransaction is active, the program cannot invoke the JCICS Task commit() or rollback() methods.

The JCICS methods Task.commit() and Task.rollback() will not be valid within a JTA transaction context. If either is attempted, an InvalidRequestException will be thrown.

The Liberty default is to wait until the first UserTransaction is created before attempting to recover any indoubt JTA transactions. However, CICS will initiate transaction recovery as soon as the Liberty JVM server initialization is complete. If the JVM server is installed as disabled, recovery will run when it is set to enabled.

If you are using EJBs, see Using JTA transactions in EJBs .