Container-Managed Transactions

Transaction Attributes

Required Attribute

RequiresNew Attribute

Mandatory Attribute

NotSupported Attribute

Supports Attribute

Never Attribute

Summary of Transaction Attributes

Setting Transaction Attributes

Rolling Back a Container-Managed Transaction

Synchronizing a Session Bean's Instance Variables

Methods Not Allowed in Container-Managed Transactions

Container-Managed Transactions

In an enterprise bean withcontainer-managed transaction demarcation, the EJB container sets the boundariesof the transactions. You can use container-managed transactions with any type of enterprisebean: session, or message-driven. Container-managed transactions simplify development because the enterprise bean code doesnot explicitly mark the transaction’s boundaries. The code does not include statements thatbegin and end the transaction.

By default if no transaction demarcation is specified enterprise beans use container-managed transactiondemarcation.

Typically, the container begins a transaction immediately before an enterprise bean method starts.It commits the transaction just before the method exits. Each method can beassociated with a single transaction. Nested or multiple transactions are not allowed withina method.

Container-managed transactions do not require all methods to be associated with transactions. Whendeveloping a bean, you can specify which of the bean’s methods are associatedwith transactions by setting the transaction attributes.

Enterprise beans that use container-managed transaction demarcation must not use any transaction managementmethods that interfere with the container’s transaction demarcation boundaries. Examples of such methodsare thecommit,setAutoCommit, androllback methods ofjava.sql.Connection or thecommit androllback methods ofjavax.jms.Session. If you require control over the transaction demarcation, youmust use application-managed transaction demarcation.

Enterprise beans that use container-managed transaction demarcation also must not use thejavax.transaction.UserTransactioninterface.

Transaction Attributes

Atransaction attribute controls the scope of a transaction.Figure 33-1 illustrates why controlling the scopeis important. In the diagram,method-A begins a transaction and then invokesmethod-BofBean-2. Whenmethod-B executes, does it run within the scope of the transactionstarted bymethod-A, or does it execute with a new transaction? The answerdepends on the transaction attribute ofmethod-B.

Figure 33-1 Transaction Scope

A transaction attribute can have one of the following values:

• Required

• RequiresNew

• Mandatory

• NotSupported

• Supports

• Never

Required Attribute

If the client is running within a transaction and invokes the enterprise bean’smethod, the method executes within the client’s transaction. If the client is notassociated with a transaction, the container starts a new transaction before running themethod.

TheRequired attribute is the implicit transaction attribute for all enterprise bean methodsrunning with container-managed transaction demarcation. You typically do not set theRequired attribute unlessyou need to override another transaction attribute. Because transaction attributes are declarative, youcan easily change them later.

RequiresNew Attribute

If the client is running within a transaction and invokes the enterprise bean’smethod, the container takes the following steps:

1. Suspends the client’s transaction

2. Starts a new transaction

3. Delegates the call to the method

4. Resumes the client’s transaction after the method completes

If the client is not associated with a transaction, the container starts anew transaction before running the method.

You should use theRequiresNew attribute when you want to ensure that themethod always runs within a new transaction.

Mandatory Attribute

If the client is running within a transaction and invokes the enterprise bean’smethod, the method executes within the client’s transaction. If the client is notassociated with a transaction, the container throws theTransactionRequiredException.

Use theMandatory attribute if the enterprise bean’s method must use the transactionof the client.

NotSupported Attribute

If the client is running within a transaction and invokes the enterprise bean’smethod, the container suspends the client’s transaction before invoking the method. After themethod has completed, the container resumes the client’s transaction.

If the client is not associated with a transaction, the container does notstart a new transaction before running the method.

Use theNotSupported attribute for methods that don’t need transactions. Because transactions involveoverhead, this attribute may improve performance.

Supports Attribute

If the client is running within a transaction and invokes the enterprise bean’smethod, the method executes within the client’s transaction. If the client is notassociated with a transaction, the container does not start a new transaction beforerunning the method.

Because the transactional behavior of the method may vary, you should use theSupports attribute with caution.

Never Attribute

If the client is running within a transaction and invokes the enterprise bean’smethod, the container throws aRemoteException. If the client is not associated witha transaction, the container does not start a new transaction before running themethod.

Summary of Transaction Attributes

Table 33-1 summarizes the effects of the transaction attributes. Both theT1 and theT2transactions are controlled by the container. AT1 transaction is associated withthe client that calls a method in the enterprise bean. In most cases,the client is another enterprise bean. AT2 transaction is started by thecontainer just before the method executes.

In the last column ofTable 33-1, the wordNone means that the business methoddoes not execute within a transaction controlled by the container. However, the database callsin such a business method might be controlled by the transaction manager ofthe DBMS.

Table 33-1 Transaction Attributes and Scope

Setting Transaction Attributes

Transaction attributes are specified by decorating the enterprise bean class or method withajavax.ejb.TransactionAttribute annotation, and setting it to one of thejavax.ejb.TransactionAttributeType constants.

If you decorate the enterprise bean class with@TransactionAttribute, the specifiedTransactionAttributeTypeis applied to all the business methods in the class. Decoration a businessmethod with@TransactionAttribute applies theTransactionAttributeType only to that method. If a@TransactionAttributeannotation decoratesboth the class and the method, the methodTransactionAttributeType overrides the classTransactionAttributeType.

TheTransactionAttributeType constants encapsulate the transaction attributes described earlier in this section.

• Required:TransactionAttributeType.REQUIRED

• RequiresNew:TransactionAttributeType.REQUIRES_NEW

• Mandatory:TransactionAttributeType.MANDATORY

• NotSupported:TransactionAttributeType.NOT_SUPPORTED

• Supports:TransactionAttributeType.SUPPORTS

• Never:TransactionAttributeType.NEVER

The following code snippet demonstrates how to use the@TransactionAttribute annotation:

@TransactionAttribute(NOT_SUPPORTED)@Statefulpublic class TransactionBean implements Transaction {...    @TransactionAttribute(REQUIRES_NEW)    public void firstMethod() {...}    @TransactionAttribute(REQUIRED)    public void secondMethod() {...}    public void thirdMethod() {...}    public void fourthMethod() {...}}

In this example, theTransactionBean class’s transaction attribute has been set toNotSupported.firstMethod has been set toRequiresNew, andsecondMethod has been set toRequired. Because a@TransactionAttribute set on a method overrides the class@TransactionAttribute,calls tofirstMethod will create a new transaction, and calls tosecondMethod willeither run in the current transaction, or start a new transaction. Calls tothirdMethod orfourthMethod do not take place within a transaction.

Rolling Back a Container-Managed Transaction

There are two ways to roll back a container-managed transaction. First, if asystem exception is thrown, the container will automatically roll back the transaction. Second,by invoking thesetRollbackOnly method of theEJBContext interface, the bean method instructs thecontainer to roll back the transaction. If the bean throws an application exception,the rollback is not automatic but can be initiated by a calltosetRollbackOnly.

Synchronizing a Session Bean’s Instance Variables

TheSessionSynchronization interface, which is optional, allows stateful session bean instances to receivetransaction synchronization notifications. For example, you could synchronize the instance variables of an enterprisebean with their corresponding values in the database. The container invokes theSessionSynchronizationmethods (afterBegin,beforeCompletion, andafterCompletion) at each of the main stages of atransaction.

TheafterBegin method informs the instance that a new transaction has begun. Thecontainer invokesafterBegin immediately before it invokes the business method.

The container invokes thebeforeCompletion method after the business method has finished, butjust before the transaction commits. ThebeforeCompletion method is the last opportunity for thesession bean to roll back the transaction (by callingsetRollbackOnly).

TheafterCompletion method indicates that the transaction has completed. It has a singleboolean parameter whose value istrue if the transaction was committed andfalseif it was rolled back.

Methods Not Allowed in Container-Managed Transactions

You should not invoke any method that might interfere with the transaction boundariesset by the container. The list of prohibited methods follows:

• Thecommit,setAutoCommit, androllback methods ofjava.sql.Connection

• ThegetUserTransaction method ofjavax.ejb.EJBContext

• Any method ofjavax.transaction.UserTransaction

You can, however, use these methods to set boundaries in application-managed transactions.

Copyright © 2010, Oracle and/or its affiliates. All rights reserved.Legal Notices