8.6 Enterprise JavaBeans Tier Transactions

Enterprise beans offer two types of transaction demarcation: bean-managed and container-managed. In container-managed transaction demarcation, six different transaction attributes--Required, RequiresNew, NotSupported, Supports, Mandatory, and Never--can be associated with an enterprise bean method. An application component provider or assembler specifies the type of transaction demarcation and transaction attributes for the methods of the enterprise beans in the deployment descriptor.

This section discusses the types of transactions and the attributes of container-managed transactions and presents guidelines for choosing among the available options.

8.6.1 Bean-Managed Transaction Demarcation

With bean-managed transaction demarcation, an enterprise bean uses the javax.transaction.UserTransaction interface to explicitly demarcate transaction boundaries. Session beans and message-driven beans can choose to use bean-managed demarcation; entity beans must always use container-managed transaction demarcation.

Code Example 8.2 illustrates the use of the JTA UserTransaction interface to demarcate transactions in an enterprise bean with bean-managed transaction demarcation.

UserTransaction ut = ejbContext.getUserTransaction();
ut.begin();
// perform transactional work here
ut.commit();

The UserTransaction interface is used the same way in the EJB tier as in the Web tier except that the reference to the interface is obtained by calling EJBContext.getUserTransaction instead of by way of a JNDI lookup. As noted in Section 8.5 on page 261, resource managers are implicitly enlisted into a transaction, if one is active, the first time they are accessed from the thread that started the transaction. It is not necessary for Web components to explicitly demarcate transactions of the resource managers.

8.6.2 Container-Managed Transaction Demarcation

The EJB container manages transaction boundaries for enterprise beans that use container-managed transaction demarcation. A transaction attribute for an enterprise bean method determines that method's transactional semantics, defining the behavior the EJB container must provide when the method is called. Transaction attributes are associated with enterprise bean methods in the bean's deployment descriptor. For example, if a method has a transaction attribute RequiresNew, the EJB container begins a new JTA transaction every time this method is called and attempts to commit the transaction before the method returns. The same transaction attribute can be specified for all the methods of an enterprise bean or different attributes can be specified for each method of a bean. Refer to Section 8.6.3 for more information on transaction attributes.

Even in container-managed demarcation, an enterprise bean has some control over the transaction. For example, an enterprise bean can choose to roll back a transaction started by the container using the method setRollbackOnly on the SessionContext, EntityContext and MessageDrivenContext object.

There are several benefits of using container-managed transaction demarcation:

• The transaction behavior of an enterprise bean is specified declaratively instead of programmatically. This frees the application component provider from writing transaction demarcation code in the component.
• It is less error-prone because the container handles transaction demarcation automatically.
• It is easier to compose multiple enterprise beans to perform a certain task with specific transaction behavior. An application assembler that understands the application can customize the transaction attributes in the deployment descriptor without code modification.

8.6.3 Transaction Attributes

A transaction attribute is a value associated with a method of an enterprise bean that uses container-managed transaction demarcation. A transaction attribute is defined for an enterprise bean method in the bean's deployment descriptor, usually by an application component provider or application assembler. The transaction attribute controls how the EJB container demarcates transactions of enterprise bean methods. In most cases, all methods of an enterprise bean will have the same transaction attribute. For optimization purposes, it is possible to have different attributes for different methods. For example, an enterprise bean may have methods that do not need to be transactional.

A transaction attribute must be specified for the methods in the component interface of a session bean and for the methods in the component and home interfaces of an entity bean.

If the transaction attribute is Required, the container ensures that the enterprise bean's method will always be invoked with a JTA transaction. If the calling client is associated with a JTA transaction, the enterprise bean method will be invoked in the same transaction context. However, if a client is not associated with a transaction, the container will automatically begin a new transaction and try to commit the transaction when the method completes.

If the transaction attribute is RequiresNew, the container always creates a new transaction before invoking the enterprise bean method and commits the transaction when the method returns. If the calling client is associated with a transaction context, the container suspends the association of the transaction context with the current thread before starting the new transaction. When the method and the transaction complete, the container resumes the suspended transaction.

If the transaction attribute is NotSupported, the transactional context of the calling client is not propagated to the enterprise bean. If a client calls with a transaction context, the container suspends the client's transaction association before invoking the enterprise bean's method. After the method completes, the container resumes the suspended transaction association.

It the transaction attribute is Supports and the client is associated with a transaction context, the context is propagated to the enterprise bean method, similar to the way the container treats the Required case. If the client call is not associated with any transaction context, the container behaves similarly to the NotSupported case. The transaction context is not propagated to the enterprise bean method.

The transaction attribute Mandatory requires the container to invoke a bean's method in a client's transaction context. If the client is not associated with a transaction context when calling this method, the container throws javax.transaction.TransactionRequiredException if the client is a remote client or javax.ejb.TransactionRequiredLocalException if the client is a local client. If the calling client has a transaction context, the case is treated as Required by the container.

The transaction attribute Never requires that the enterprise bean method explicitly not be called within a transaction context. If the client calls with a transaction context, the container throws java.rmi.RemoteException if the client is a remote client or javax.ejb.EJBException if the client is a local client. If the client is not associated with any transaction context, the container invokes the method without initiating a transaction.

8.6.4 Enterprise JavaBeans Tier Transaction Guidelines

As mentioned previously, the recommended way to manage transactions is through container-managed demarcation. Declarative transaction management provides one of the major benefits of the J2EE platform by freeing the application component provider from the burden of managing transactions. Furthermore, the transaction characteristics of an application can be changed without code modification by switching the transaction attributes, making components useful in more contexts. Transaction demarcation should be selected with great care by someone who understands the application well. Bean-managed transaction demarcation is only for advanced users who want fine-grain control over the transactional behavior of the application.

Most enterprise beans perform transactional work (for example, accessing a JDBC database). The default choice for a transaction attribute should be Required. Using this attribute ensures that the methods of an enterprise bean are invoked within a JTA transaction. In addition, enterprise beans with the Required transaction attribute can be easily composed to perform work within the scope of a single JTA transaction.

Message-driven beans may use only the Required and NotSupported transaction attributes. Entity beans that use EJB 2.0 container-managed persistence should use only the Required, RequiresNew, or Mandatory transaction attributes for most component and home interface methods.

The RequiresNew transaction attribute is useful when the bean method needs to commit unconditionally, whether or not a transaction is already in progress. An example of this requirement is a bean method that performs logging. This bean method should be invoked with the RequiresNew transaction attribute so that logging records are created even if the calling client's transaction is rolled back.

The NotSupported transaction attribute can be used when the resource manager responsible for the transaction is not supported by the J2EE product. For example, if a bean method is invoking an operation on an enterprise resource planning system that is not integrated with the J2EE server, the server has no control over that system's transactions. In this case, the bean's transaction attribute should be set to NotSupported to clearly indicate that the enterprise resource planning system is not accessed within a JTA transaction.

Using the transaction attribute Supports is not recommended. An enterprise bean with this attribute would have transactional behavior that differed depending on whether the caller is associated with a transaction context, possibly leading to a violation of the ACID rules for transactions.

The transaction attributes Mandatory and Never can be used when it is necessary to verify the transaction association of the calling client. These attributes may make it more difficult to use the component inside an application because it restricts the calling client's transaction context.

As previously mentioned, entity beans that use EJB 2.0 container-managed persistence can only use Required, RequiresNew, or Mandatory transaction attributes for most business methods and methods on the home interface. Because accessing the container-managed persistence (CMP) and container-managed relationship (CMR) fields of an entity bean requires transactions, the Mandatory transaction attribute should be used for all get and set methods of an entity bean's CMP and CMR fields. Use of the RequiresNew transaction attribute for get and set methods of CMR fields is not recommended, because it is illegal to iterate through the same collection object corresponding to a CMR field in different transactions.