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, and EJB 3.2. 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
or
ejbLite-3.2
to the server.xml configuration file. EJB is
enabled by adding ejb-3.2
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
JTA transaction assuming that you have not disabled CICS JTA
integration using the <cicsts_jta Integration="false"/>
server.xml element.
- 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 unit of work or is part of a wider, distributed JTA transaction.
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.
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 | 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 |
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.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 will cause 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.