Understanding EJB Transaction Services

You can enable OC4J to manage transactions by using the Java Transaction API (JTA) supported by the Java Transaction Service (JTS). Using annotations or the deployment descriptor, you define the transactional properties of enterprise beans during design or deployment, and then let OC4J take over the responsibility of transaction management.

Note:

Only flat transactions are supported; nested transactions are not supported.

This section describes the following:

Who Manages a Transaction?
How are Transactions Handled When a Client Invokes a Business Method?
How do You Participate in a Global or Two-Phase Commit (2PC) Transaction?

For more information, see the following:

"Configuring Transaction Services"
"Transaction Best Practices"
"OC4J Transaction Support" in the Oracle Containers for J2EE Services Guide

Who Manages a Transaction?

A transaction can be managed by either the container (see "What are Container-Managed Transactions?") or the bean ("What are Bean-Managed Transactions?").

Container-managed transaction management is the default.

When configuring transaction management for your enterprise beans, consider the following restrictions:

EJB 3.0 entities cannot be configured with a transaction management type. EJB 3.0 entities execute within the transactional context of the caller.
EJB 2.1 entity beans must always use container-managed transaction demarcation. An EJB 2.1 entity bean must not be designated with bean-managed transaction demarcation.

For all other EJB types, you can choose either container-managed or bean-managed transaction management.

For more information, see the following:

What are Container-Managed Transactions?

When you use container-managed transactions (CMT), your EJB delegates to the container the responsibility to ensure that a transaction is started and committed when appropriate.

All session and message-driven beans may use CMT.

EJB 2.1 entity beans must use CMT.

EJB 3.0 entities cannot be configured with a transaction management type. EJB 3.0 entities execute within the transactional context of the caller.

When developing an enterprise bean that uses CMT, consider the following:

Do not use resource manager-specific transaction management methods such as java.sqlConnection methods commit, setAutoCommit, and rollback or javax.jms.Session methods commit or rollback.
Do not obtain or use the javax.transaction.UserTransaction interface.
A stateful session bean using CMT may implement the javax.ejb.SessionSynchronization interface.
An enterprise bean that uses CMT may use javax.ejb.EJBContext methods setRollbackOnly and getRollbackOnly.

For an EJB that uses CMT, for each business method, you can also specify a transaction attribute that determines how the container manages transactions when a client invokes the method (see "How are Transactions Handled When a Client Invokes a Business Method?").

What are Bean-Managed Transactions?

When you use bean-managed transactions (BMT), the bean-provider is responsible for ensuring that a transaction is started and committed when appropriate.

Only session and message-driven beans may use BMT.

When developing an EJB that uses BMT, consider the following:

Use the javax.transaction.UserTransaction methods begin and commit to demarcate transactions.
A stateful session bean instance may, but is not required to, commit a started transaction before a business method returns.

If a transaction has not been completed by the end of a business method, the container retains the association between the transaction and the instance across multiple client calls until the instance eventually completes the transaction.
A stateless session bean instance must commit any transactions that it started before a business method or timeout callback method returns.
A message-driven bean instance must commit a transaction before a message listener method or timeout callback method returns.
After starting a transaction, do not use resource-manager specific transaction management methods such as java.sqlConnection methods commit, setAutoCommit, and rollback or javax.jms.Session methods commit or rollback.
A bean that uses BMT must not use EJBContext methods getRollbackOnly and setRollbackOnly. It must use UserTransaction method getStatus and rollback instead.

How are Transactions Handled When a Client Invokes a Business Method?

For an enterprise bean that uses CMT (see "What are Container-Managed Transactions?"), you can specify a transaction attribute that determines how the container must manage transactions when a client invokes a bean method.

You can specify a transaction attribute for each of the following types of bean method:

a method of a bean's business interface;
a message listener method of a message-driven bean;
a timeout callback method;
a stateless session bean's Web service endpoint method;
for EJB 2.1 and earlier, a method of a session or entity bean's home or component interface

Table 2-6 shows what transaction (if any) an EJB method invocation uses depending on how its transaction attribute is configured and whether or not a client-controlled transaction exists at the time the method is invoked.

OC4J starts a container-controlled transaction implicitly to satisfy the transaction attribute configuration when a bean method is invoked in the absence of a client-controlled transaction.

Table 2-6 EJB Transaction Support by Transaction Attribute

Transaction Attribute	ClientEControlled Transaction Exists	ClientEControlled Transaction Does Not Exist
Not Supported	Container suspends the client transaction	Use no transaction
Supports	Use client-controlled transaction	Use no transaction
Required^Foot 1	Use client-controlled transaction	Container starts a new transaction
Requires New	Container suspends the client transaction and starts a new transaction	Container starts a new transaction
Mandatory	Use client-controlled transaction	Exception raised
Never	Exception raised	Use no transaction

^Footnote 1For message-driven beans using the OEMS JMS (in-memory or file-based) message service provider, Required is supported only if you access this message service provider using the Oracle JMS Connector. For more information, see "Restrictions When Accessing a Message Service Provider Without a J2CA Resource Adapter".

Oracle recommends that you do not make modifications to entity beans under conditions identified as "Use no transaction". Oracle also recommends that you avoid using the Supports transaction attribute because it leads to a non-transactional state whenever the client does not explicitly provide a transaction.

Using TopLink CMP, a transaction must be present in order to modify an EJB 2.X CMP entity bean: If no transaction is present, the TopLink persistence manager returns a read-only copy of the bean.

For more information, see the following:

How do You Participate in a Global or Two-Phase Commit (2PC) Transaction?

If all resources enlisted in a transaction are XA-compliant, then OC4J automatically coordinates a global or two-phase commit transaction.

In this release of OC4J, transaction coordination functionality is now located in OC4J, replacing in-database coordination, which is now deprecated. Also, the middle-tier coordinator is now heterogeneous, meaning that it supports all XA-compatible resources, not just those from Oracle.

The middle-tier coordinator supports the following:

any XA-compliant resource;
interpositioning and transaction inflow;
last resource commit optimization;
recovery logging;

For more information, see the following:

"Configuring Message Services for Two-Phase Commit (2PC) Transactions"
"Middle-Tier Two-Phase Commit (2PC) Coordinator" in the Oracle Containers for J2EE Services Guide