Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic JTA

# Transactions in EJB Applications

This section includes the following topics:

- Before You Begin
- General Guidelines
- Transaction Attributes
- Participating in a Transaction
- Transaction Semantics
- Session Synchronization
- Synchronization During Transactions
- Setting Transaction Timeouts
- Handling Exceptions in EJB Transactions

This section describes how to integrate transactions in Enterprise JavaBeans (EJBs) applications that run under BEA WebLogic Server.

# Before You Begin

Before you begin, you should read Introducing Transactions, particularly the following topics:

- Transactions in WebLogic Server EJB Applications
- Transactions Sample EJB Code

This document describes the BEA WebLogic Server implementation of transactions in Enterprise JavaBeans. The information in this document supplements the Enterprise JavaBeans Specification 2.0, published by Sun Microsystems, Inc.

Note: Before proceeding with the rest of this chapter, you should be familiar with the contents of the EJB Specification 2.0 document, particularly the concepts and material presented in Chapter 16, "Support for Transactions."

For information about implementing Enterprise JavaBeans in WebLogic Server applications, see Programming WebLogic Enterprise JavaBeans.

# General Guidelines

The following general guidelines apply when implementing transactions in EJB applications for WebLogic Server:

- The EJB specification allows for flat transactions only. Transactions cannot be nested.
- The EJB specification allows for distributed transactions that span multiple resources (such as databases) and supports the two-phase commit protocol for both EJB CMP 2.0 and EJB CMP 1.1.
- WebLogic Server supports any JTA-compliant XA resource. For information on the XA resource driver supplied with WebLogic Server, see "Transactions and the WebLogic jDriver for Oracle in Configuring and Using WebLogic jDriver for Oracle.
- Use standard programming techniques to optimize transaction processing. For example, properly demarcate transaction boundaries and complete transactions quickly.
- Use a database connection from a local TxDataSource—on the WebLogic Server instance on which the EJB is running. Do not use a connection from a TxDataSource on a remote WebLogic Server instance.
- Be sure to tune the EJB cache to ensure maximum performance in transactional EJB applications. For more information, see Programming WebLogic Server Enterprise Java Beans.

For general guidelines about the WebLogic Server Transaction Service, see Capabilities and Limitations.

# Transaction Attributes

This section includes the following sections:

- About Transaction Attributes for EJBs
- Transaction Attributes for Container-Managed Transactions
- Transaction Attributes for Bean-Managed Transactions

## About Transaction Attributes for EJBs

Transaction attributes determine how transactions are managed in EJB applications. For each EJB, the transaction attribute specifies whether transactions are demarcated by the WebLogic Server EJB container (container-managed transactions) or by the EJB itself (bean-managed transactions). The setting of the `transaction-type` element in the deployment descriptor determines whether an EJB is container-managed or bean-managed. See Chapter 16, "Support for Transactions," and Chapter 21, "Deployment Descriptor," in the EJB Specification 2.0, for more information about the `transaction-type` element.

In general, the use of container-managed transactions is preferred over bean-managed transactions because application coding is simpler. For example, in container-managed transactions, transactions do not need to be started explicitly.

WebLogic Server fully supports method-level transaction attributes as defined in Section 16.4 in the EJB Specification 2.0.

## Transaction Attributes for Container-Managed Transactions

For container-managed transactions, the transaction attribute is specified in the `container-transaction` element in the deployment descriptor. Container-managed transactions include all entity beans and any stateful or stateless session beans with a `transaction-type` set to `Container`. For more information about these elements, see Programming WebLogic Server Enterprise JavaBeans.

The Application Assembler can specify the following transaction attributes for EJBs and their business methods:

- `NotSupported`
- `Supports`
- `Required`
- `RequiresNew`
- `Mandatory`
- `Never`

For a detailed explanation about how the WebLogic Server EJB container responds to the `trans-attribute` setting, see section 17.6.2 in the EJB Specification 2.0.

The WebLogic Server EJB container automatically sets the transaction timeout if a timeout value is not defined in the deployment descriptor. The container uses the value of the `Timeout Seconds` configuration parameter. The default timeout value is 30 seconds.

For more information on transaction configuration parameters, see Configuring and Managing Transactions, in this guide and in the Administration Console Online Help.

For EJBs with container-managed transactions, the EJBs have no access to the `javax.transaction.UserTransaction` interface, and the entering and exiting transaction contexts must match. In addition, EJBs with container-managed transactions have limited support for the `setRollbackOnly` and `getRollbackOnly` methods of the `javax.ejb.EJBContext` interface, where invocations are restricted by rules specified in Sections 16.4.4.2 and 16.4.4.3 of the EJB Specification 2.0.

## Transaction Attributes for Bean-Managed Transactions

For bean-managed transactions, the bean specifies transaction demarcations using methods in the `javax.transaction.UserTransaction` interface. Bean-managed transactions include any stateful or stateless session beans with a `transaction-type` set to `Bean`. Entity beans cannot use bean-managed transactions.

For stateless session beans, the entering and exiting transaction contexts must match. For stateful session beans, the entering and exiting transaction contexts may or may not match. If they do not match, the WebLogic Server EJB container maintains associations between the bean and the nonterminated transaction.

Session beans with bean-managed transactions cannot use the `setRollbackOnly` and `getRollbackOnly` methods of the `javax.ejb.EJBContext` interface.

# Participating in a Transaction

When the EJB Specification 2.0 uses the phrase "participating in a transaction," BEA interprets this to mean that the bean meets either of the following conditions:

- The bean is invoked in a transactional context (container-managed transaction).
- The bean begins a transaction using the UserTransaction API in a bean method invoked by the client (bean-managed transaction), and it does not suspend or terminate that transaction upon completion of the corresponding bean method invoked by the client.

# Transaction Semantics

This topic contains the following sections:

- Transaction Semantics for Container-Managed Transactions
- Transaction Semantics for Bean-Managed Transactions

The EJB Specification 2.0 describes semantics that govern transaction processing behavior based on the EJB type (entity bean, stateless session bean, or stateful session bean) and the transaction type (container-managed or bean-managed). These semantics describe the transaction context at the time a method is invoked and define whether the EJB can access methods in the `javax.transaction.UserTransaction` interface. EJB applications must be designed with these semantics in mind.

## Transaction Semantics for Container-Managed Transactions

For container-managed transactions, transaction semantics vary for each bean type.

### Transaction Semantics for Stateful Session Beans

Table 5-1 describes the transaction semantics for stateful session beans in container-managed transactions.

Table 5-1 Transaction Semantics for Stateful Session Beans in Container-Managed Transactions

Method | Transaction Context at the Time the Method Was Invoked | Can Access UserTransaction Methods?
--- | --- | ---
Constructor | Unspecified | No
`setSessionContext()` | Unspecified | No
`ejbCreate()` | Unspecified | No
`ejbRemove()` | Unspecified | No
`ejbActivate()` | Unspecified | No
`ejbPassivate()` | Unspecified | No
Business method | Yes or No based on transaction attribute | No
`afterBegin()` | Yes | No
`beforeCompletion()` | Yes | No
`afterCompletion()` | No | No

### Transaction Semantics for Stateless Session Beans

Table 5-2 describes the transaction semantics for stateless session beans in container-managed transactions.

Table 5-2 Transaction Semantics for Stateless Session Beans in Container-Managed Transactions

Method | Transaction Context at the Time the Method Was Invoked | Can Access UserTransaction Methods?
--- | --- | ---
Constructor | Unspecified | No
`setSessionContext()` | Unspecified | No
`ejbCreate()` | Unspecified | No
`ejbRemove()` | Unspecified | No
Business method | Yes or No based on transaction attribute | No

### Transaction Semantics for Entity Beans

Table 5-3 describes the transaction semantics for entity beans in container-managed transactions.

Table 5-3 Transaction Semantics for Entity Beans in Container-Managed Transactions

Method | Transaction Context at the Time the Method Was Invoked | Can Access UserTransaction Methods?
--- | --- | ---
Constructor | Unspecified | No
`setEntityContext()` | Unspecified | No
`unsetEntityContext()` | Unspecified | No
`ejbCreate()` | Determined by transaction attribute of matching create | No
`ejbPostCreate()` | Determined by transaction attribute of matching create | No
`ejbRemove()` | Determined by transaction attribute of matching remove | No
`ejbFind()` | Determined by transaction attribute of matching find | No
`ejbActivate()` | Unspecified | No
`ejbPassivate()` | Unspecified | No
`ejbLoad()` | Determined by transaction attribute of business method that invoked `ejbLoad()` | No
`ejbStore()` | Determined by transaction attribute of business method that invoked `ejbStore()` | No
Business method | Yes or No based on transaction attribute | No

## Transaction Semantics for Bean-Managed Transactions

For bean-managed transactions, the transaction semantics differ between stateful and stateless session beans. For entity beans, transactions are never bean-managed.

### Transaction Semantics for Stateful Session Beans

Table 5-4 describes the transaction semantics for stateful session beans in bean-managed transactions.

Table 5-4 Transaction Semantics for Stateful Session Beans in Bean-Managed Transactions

Method | Transaction Context at the Time the Method Was Invoked | Can Access UserTransaction Methods?
--- | --- | ---
Constructor | Unspecified | No
`setSessionContext()` | Unspecified | No
`ejbCreate()` | Unspecified | Yes
`ejbRemove()` | Unspecified | Yes
`ejbActivate()` | Unspecified | Yes
`ejbPassivate()` | Unspecified | Yes
Business method | Typically, no unless a previous method execution on the bean had completed while in a transaction context | Yes
`afterBegin()` | Not applicable | Not applicable
`beforeCompletion()` | Not applicable | Not applicable
`afterCompletion()` | Not applicable | Not applicable

### Transaction Semantics for Stateless Session Beans

Table 5-5 describes the transaction semantics for stateless session beans in bean-managed transactions.

Table 5-5 Transaction Semantics for Stateless Session Beans in Bean-Managed Transactions

Method | Transaction Context at the Time the Method Was Invoked | Can Access UserTransaction Methods?
--- | --- | ---
Constructor | Unspecified | No
`setSessionContext()` | Unspecified | No
`ejbCreate()` | Unspecified | Yes
`ejbRemove()` | Unspecified | Yes
Business method | No | Yes

# Session Synchronization

A stateful session bean using container-managed transactions can implement the `javax.ejb.SessionSynchronization` interface to provide transaction synchronization notifications. In addition, all methods on the stateful session bean must support one of the following transaction attributes: `REQUIRES_NEW`, `MANDATORY` or `REQUIRED`. For more information about the `javax.ejb.SessionSynchronization` interface, see Section 6.5.3 in the EJB Specification 2.0.

# Synchronization During Transactions

If a bean implements `SessionSynchronization`, the WebLogic Server EJB container will typically make the following callbacks to the bean during transaction commit time:

- `afterBegin()`
- `beforeCompletion()`
- `afterCompletion()`

The EJB container can call other beans or involve additional XA resources in the `beforeCompletion` method. The number of calls is limited by the `beforeCompletionIterationLimit` attribute. This attribute specifies how many cycles of callbacks are processed before the transaction is rolled back. A synchronization cycle can occur when a registered object receives a `beforeCompletion` callback and then enlists additional resources or causes a previously synchronized object to be reregistered. The iteration limit ensures that synchronization cycles do not run indefinitely.

# Setting Transaction Timeouts

Bean providers can specify the timeout period for transactions in EJB applications. If the duration of a transaction exceeds the specified timeout setting, then the Transaction Service rolls back the transaction automatically.

Note: You must set the timeout before you `begin()` the transaction. Setting a timeout does not affect transaction transactions that have already begun.

Timeouts are specified according to the transaction type:

- Container-managed transactions. The Bean Provider configures the `trans-timeout-seconds` attribute in the `weblogic-ejb-jar.xml` deployment descriptor. For more information, see the Administration Guide.

The Bean Provider should configure the trans-timeout-seconds attribute in the weblogic-ejb-jar.xml deployment descriptor.

- Bean-managed transactions. An application calls the `UserTransaction.setTransactionTimeout` method.

# Handling Exceptions in EJB Transactions

WebLogic Server EJB applications need to catch and handle specific exceptions thrown during transactions. For detailed information about handling exceptions, see Chapter 17, "Exception Handling," in the EJB Specification 2.0 published by Sun Microsystems, Inc.

For more information about how exceptions are thrown by business methods in EJB transactions, see the following tables in Section 17.3: Table 12 (for container-managed transactions) and Table 13 (for bean-managed transactions).

For a client's view of exceptions, see Section 17.4, particularly Section 12.4.1 (application exceptions), Section 17.4.2 (`java.rmi.RemoteException`), Section 17.4.2.1 (`javax.transaction.TransactionRolledBackException`), and Section 17.4.2.2 (`javax.transaction.TransactionRequiredException`).