Using JTA transactions in EJBs

How to use JTA transactions in Enterprise JavaBeans (EJBs) on Liberty.

About this task

EJBs are Java™ objects that are managed by the Liberty JVM server, allowing a modular architecture of Java applications. The Liberty JVM server supports EJB Lite 3.1 and EJB Lite 3.2, a lightweight subset of the full EJB specification, providing session, lifecycle (through interceptor methods), transaction and security management. EJBs are deployed to a Liberty server using an enterprise archive (EAR) file created from an enterprise application project. Enterprise application projects can contain both EJB and Web projects.

EJB Lite is enabled by adding the feature ejbLite-3.1 and ejbLite-3.2to the server.xml configuration file. EJBs are deployed into a container. This container works in the background ensuring that aspects like session management, transactions and security are adhered to.

EJBs support two types of transaction management: container managed and bean managed. Container managed transactions provide a transactional context for calls to bean methods, and are defined using Java annotations or the deployment descriptor file ejb-jar.xml. Bean managed transactions are controlled directly using the Java Transaction API (JTA). In both cases the CICS® UOW remains subordinate to the outcome of the JTA transaction, assuming that you have not disabled CICS JTA integration. There are six different transaction attributes that can be specified for container managed transactions:
  • Mandatory
  • Required
  • RequiresNew
  • Supports
  • NotSupported
  • Never

A JTA transaction is a distributed unit of work as defined in the J2EE specification. The setting of a method’s transaction attribute determines whether or not the CICS task under which the method executes, runs under its own unit of work, or is part of a wider, distributed JTA transaction. The following table describes the resulting transactional context of an invoked EJB method, depending on the transaction attribute and whether or not the calling application already has a JTA transactional context.

Important: Liberty does not support outbound or inbound transaction propagation. For more information, see .
Table 1. EJB transaction support
Transaction Attribute No JTA transaction Pre-existing JTA transaction Accessing a remote EJB with a pre-existing JTA transaction Exception behavior
Mandatory Throws exception javax.ejb.EJBTransactionRequiredException Inherits the existing JTA transaction Throws exception com.ibm.websphere.csi.CSITransactionMandatoryException. Rollback
Required EJB container creates a new JTA transaction Inherits the existing JTA transaction Throws exception com.ibm.websphere.csi.CSITransactionRequiredException. Rollback
RequiresNew EJB container creates a new JTA transaction Throws exception javax.ejb.EJBException EJB container creates a new JTA transaction that is managed by the remote server. Rollback
Supported Continues without a JTA transaction Inherits the existing JTA transaction Throws exception com.ibm.websphere.csi.CSITransactionSupportedException. Rollback if called from JTA
NotSupported Continues without a JTA transaction Suspends the JTA transaction but not the CICS UOW The remote server continues without a JTA transaction. No rollback
Never Continues without a JTA transaction Throws exception javax.ejb.EJBException The remote server continues without a JTA transaction. No rollback
Note:
  • The transaction attribute 'NotSupported' cannot be supported by a CICS Liberty JVM server. Calling a method marked as 'NotSupported' will suspend the JTA transaction but not suspend the CICS UOW. Any modification of CICS resources during this method call will still be recoverable.
  • The transaction attribute 'RequiresNew' is supported by a CICS Liberty JVM server, with the restriction that CICS UOW cannot be nested. Attempting to call a method marked as 'RequiresNew' when already in a JTA transaction will cause an exception to be thrown.
The standard restrictions for WLP also apply, see Runtime environment known restrictions.