Specifying Transaction Attributes

Use

The EJB 3.0 specification provides both bean-managed and container-managed transaction support. With bean-managed transaction demarcation, the bean provider controls the boundaries of the transaction. With container-managed transaction demarcation, the container controls the boundaries of the transaction on behalf of the bean provider.

To use container-managed transaction demarcation, you provide instructions called transaction attributes in metadata annotations or in the deployment descriptor. These transaction attributes tell the container whether it should:

Run an enterprise bean method in a client's transaction context;
Run the enterprise bean method in a new transaction context started by the container;
Run the enterprise bean method in an unspecified transaction context (that is without a transaction).

Note
The container applies container-managed transaction demarcation by default. To use bean-managed transaction demarcation, use the @TransactionManagement(BEAN) annotation.

Procedure

Using Container-Managed Transaction Demarcation for Session Beans' Methods

To use container-managed transactions, you annotate the bean class and/or business methods in the class with the @TransactionAttribute annotation and specify the TransactionAttributeType attribute with one of the following values:

NOT_SUPPORTED

The business method is executed in an unspecified transaction context.
REQUIRED

The business method is executed in a transaction context. If the client is associated with a transaction then the method is executed in the same transaction context as the client. Otherwise, the container creates a new transaction context.
SUPPORTS

If a client transaction context exists, the business method is executed in it. If a client transaction context does not exist, the business method is executed in an unspecified transaction context.
REQUIRES_NEW

Regardless of whether a client transaction context exists, the business method is executed in a new transaction context.
MANDATORY

The client must already be associated with a transaction context and the business method is executed in the client's transaction context.

If the client is not associated with a transaction, the container throws an exception.
NEVER

The client must not be associated with a transaction and the business method is executed in an unspecified transaction context.

If the client is associated with a transaction, the container throws an exception.

Example
@TransactionAttribute(TransactionAttributeType.REQUIRES_NEW)

Using Container-Managed Transaction Demarcation for Message-Driven Beans' Message Listener Methods

To use container-manager transactions, you annotate message listener methods with the @TransactionAttribute annotation and specify the TransactionAttributeType attribute with one of the following values:

NOT_SUPPORTED

The message listener method is executed in an unspecified transaction context.
REQUIRED

The message listener method is executed in a valid transaction context. The application server starts a transaction before the listener method of the message-driven bean is invoked. After the message-driven bean receives the message, this message can interact with other EJBs and with resources such as databases. All these operations remain in the same transactional context started by the application server.

If the onMessage() method completes successfully, the transaction is committed. Otherwise the transaction is rolled back.

Using Container-Managed Transaction Demarcation for Stateless Session Beans' and Message-Driven Beans' Timeout Callback Methods

To use container-managed transactions, you annotate timeout callback methods with the @TransactionAttribute annotation and specify the TransactionAttributeType attribute with one of the following values:

NOT_SUPPORTED

The timeout callback method is executed in an unspecified transaction context.
REQUIRES_NEW

The timeout callback method is executed in a new transaction context.
REQUIRED

The timeout callback method is executed in a transactional context. The application server must start new transaction. In this case, the function of REQUIRED is similar to the function of REQUIRES_NEW . The REQUIRED attribute is allowed so that you can use it as a default transaction attribute.

If the transaction is rolled back, the container retries the timeout.

Example

This is an example of a bean-managed transaction demarcation:

package com.sap.example;

 

import javax.annotation.Resource;

import javax.ejb.Stateless;

import javax.ejb.TransactionManagement;

import javax.ejb.TransactionManagementType;

import javax.persistence.EntityManager;

import javax.persistence.PersistenceContext;

import javax.transaction.UserTransaction;

 

@Stateless

@TransactionManagement(TransactionManagementType.BEAN)

public class StatelessBean implements StatelessLocal {

 

   @Resource

   UserTransaction ut;

 

   @PersistenceContext

   EntityManager em;

 

   public void businessMethod() {

      ut.begin(); // Start a new transaction

      try {

         // Do work

         em.persist(myEntity);

         ut.commit(); // Commit the transaction

      } catch (Exception e) {

         ut.rollback(); // Rollback the transaction

      }

   }

}

This is an example of a container-managed transaction:

package com.sap.example;

 

import javax.ejb.Stateless;

import javax.ejb.TransactionAttribute;

import javax.ejb.TransactionAttributeType;

import javax.ejb.TransactionManagement;

import javax.ejb.TransactionManagementType;

import javax.persistence.EntityManager;

import javax.persistence.PersistenceContext;

 

@Stateless

@TransactionManagement(TransactionManagementType.CONTAINER)

public class StatelessBean1 implements StatelessLocal {

   

   @PersistenceContext EntityManager em; 

   

   @TransactionAttribute(TransactionAttributeType.REQUIRES_NEW)

   public void businessMethod() {

      // Work in transaction

   }

}

Annotation Reference

Name

Use

Target

Members

@Transaction

Management

Use this annotation to specify the transaction demarcation type of a session bean or message-driven bean. If you do not use this annotation, the bean has container-managed transaction demarcation.

TYPE

v alue - the demarcation type can be either CONTAINER or BEAN. The default value is CONTAINER .

@Transaction

Attribute

Use this annotation to specify the transaction context in which a method is invoked by the container. You can specify this annotation only if you use container-managed transaction demarcation. You can specify @TransactionAttribute on the bean class and/or on business methods in the class, message listener methods, and timeout callback methods.

On a bean class, it applies to all business methods of the class, message listener methods, and timeout callback methods.

On a method, it applies to that method only.

If you use @TransactionAttribute at both the class and the method level, the method value overrides if the two disagree.

If you do not use this annotation, and the bean uses container-managed transaction demarcation, the semantics of the REQUIRED transaction attribute are assumed.

TYPE

METHOD

value - the transaction attribute type can be one of the following:

MANDATORY,

REQUIRED,

REQUIRES_NEW,

SUPPORTS,

NOT_SUPPORTED,

NEVER .

The default value is REQUIRED .