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, EJB Lite 3.2, Enterprise Beans Lite 4.0, EJB 3.2, and Enterprise Beans 4.0. EJBs are deployed to a Liberty server using an Enterprise Application 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 relevant feature ejbLite-3.1, ejbLite-3.2, or enterpriseBeansLite-4.0 to the server.xml configuration file. EJB is enabled by adding ejb-3.2 or enterpriseBeans-4.0 to 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®® unit of work (UOW) remains subordinate to the outcome of the Liberty JTA transaction assuming that you have not disabled CICS JTA integration using the <cicsts_jta Integration="false"/> server.xml element.

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 UOW as defined in the JEE specification. Setting of a method's transaction attribute determines whether or not the CICS task, under which the method executes, runs under its own UOW or is part of a wider, distributed JTA transaction.
Note: Although it is respected by the Liberty JTA transaction system, the transaction attribute NotSupported does not integrate with and is not supported by the CICS UOW. This applies to EJBs in general.
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 Using enterprise JavaBeans with remote interfaces on Liberty.
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 EJBTransactionRequiredException. Inherits the existing JTA transaction. Throws exception com.ibm.websphere.csi.CSITransactionMandatoryException. Rollback
Required

This is the default transaction attribute.

 EJB container creates new JTA transaction. Inherits the existing JTA transaction. Throws exception com.ibm.websphere.csi.CSITransactionRequiredException. Rollback
RequiresNew EJB container creates new JTA transaction. Throws exception javax.ejb.EJBException. EJB container creates a new JTA transaction that is managed by the remote server. Rollback
Supports 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
Important: 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.
Note: If JTA integration is enabled, the transaction attribute RequiresNew is supported by a CICS Liberty JVM server, with the restriction that the CICS UOW cannot be nested. Attempting to call a method marked as RequiresNew when already in a JTA transaction causes an exception to be thrown.

If you call an EJB from a servlet or a POJO and do not explicitly configure the EJB transactional attribute, then by default, container-managed transaction management applies, as does a default transaction attribute of Required. This means each call to the EJB starts a new JTA transaction with a subordinate CICS UOW and commits the JTA transaction after each call. If you do not require the use of JTA with EJBs consider using the transaction attribute Never.

For information about additional Enterprise JavaBeans (EJB) feature restrictions, see Liberty: Runtime environment known issues and restrictions.