Transaction Handling

Transaction Management for EJBs

The previous sections focused on general aspects of transaction management for distributed objects, and on transaction management for CORBA applications using the JTS.

An EJB application can also use JTS--on the client side only--to manage transactions. More typically an EJB application uses declarative transaction management, letting the EJB container provide the transaction control. You do this by specifying the appropriate value for the TransactionAttribute of the EJB deployment descriptor, either for the whole EJB, or on a method-by-method basis, where applicable.

For example, if the deployment descriptor for a bean declares that the bean has the transaction attribute TX_REQUIRES_NEW, then the bean container starts a transaction before each invocation of bean method, and attempts to commit the transaction when the method completes.

The following sections describe the values that you can set for the EJB transaction attribute.

Declarative Transactions

The bean deployer declares the transaction handling characteristics of a bean in the deployment descriptor. This is specified in the transaction attribute, which has six possible values:

TX_NOT_SUPPORTED
TX_REQUIRED
TX_SUPPORTS
TX_REQUIRES_NEW
TX_MANADATORY
TX_BEAN_MANAGED

The semantics of these attribute values are described in this section. See "Programming Restrictions" for more information about the EJB deployment descriptor itself.

TX_NOT_SUPPORTED

When TX_NOT_SUPPORTED is declared for the bean itself, it means that Oracle8i does not invoke transaction support for the bean methods. However, a method declaration in the deployment descriptor can over-ride this declaration. If the client is in a transaction (has established an active transaction context), then the bean container suspends transaction support during delegation of method calls on the bean, and resumes the transaction context when the method call completes.

The suspended transaction context is not propagated to other objects that are invoked from within the bean code.

A bean that is running under TX_NOT_SUPPORTED cannot perform any SQL operations. An exception is thrown by the EJB server if this is attempted.

TX_REQUIRED

If the client invokes a bean method with the TX_REQUIRED attribute, there are two possibilities:

The client had not started a transaction

If the client has not established a transaction context, the bean starts a new transaction for each method call. The transaction is committed, if possible, after each call completes. The commit protocol is completed before the bean results are sent to the client.

Oracle8i sends the transaction context for the transaction that it has established to other resources or EJBs that are invoked from the current bean.

The client had started a transaction

The bean container delegates calls to the bean methods using the client transaction context.

The transaction context is passed to other Enterprise JavaBean objects that are invoked from the enterprise Bean object, as long as they are in the same session.

TX_SUPPORTS

If the client has established a transaction context, then the bean container uses that context. If the client has no established transaction context, then the EJB methods are invoked with no transaction support.

TX_REQUIRES_NEW

The container always invokes the bean methods with a new transaction. The container commits the transaction, if possible, before sending the method results to the client.

If the client has established a transaction content, the client transaction is suspended before the bean transaction is started, and is resumed when the bean transaction completes (at the end of each method call).

If the client has established a transaction context, the association is suspended before the new transaction is started and is resumed when the new transaction has completed.

The container-managed transaction context is passed to the resources or other EJB objects that the bean invokes.

An enterprise Bean that has the TX_REQUIRES_NEW transaction attribute is always invoked in the scope of a new transaction. The container starts a new transaction before delegating a method call to the enterprise Bean object, and attempts to commit the transaction when the method call on the enterprise Bean object has completed. The container performs the commit protocol before the method result is sent to the client.

The new transaction context is passed to the resources or other enterprise Bean objects that are invoked from the enterprise Bean object.

TX_MANDATORY

If an EJB method is invoked with the TX_MANADATORY attribute, the client transaction context is always used. If the client has not established a transaction context, the container throws the TransactionRequired exception to the client.

The client transaction context is propagated to the resources or other enterprise Bean objects that are invoked from the enterprise Bean object.

TX_BEAN_MANAGED

The bean-managed attribute value is the one that lets the bean get access to the transaction service on its own behalf. Session beans get access to the transaction service through the session context that is supplied to the bean at initialization, as a parameter in the setSessionContext() call. The SessionContext interface subclasses EJBContext.

The bean implementation must use the javax.jts.UserTransaction interface methods to manage transactions on its own. See "Using The Java Transaction Service" for a description of these methods.

The TX_BEAN_MANAGED attribute value cannot be mixed with other transaction attribute values. For example, if the bean-level descriptor, or one of the method-level descriptors, specifies TX_BEAN_MANAGED, then all method-level descriptors present must specify TX_BEAN_MANAGED. When using bean-managed transactions, the transaction boundaries span bean methods. You can begin a transaction in one method, and the transaction can be rolled back or committed in a separate method, called later.

The container makes the javax.jts.UserTransaction interface available to the enterprise Bean though the EJBContext.getUserTransaction() method, as illustrated in the following example.

import javax.jts.UserTransaction;
...
EJBContext ic = ...;
...
UserTransaction tx = ic.getUserTransaction();
tx.begin();
... // do work
tx.commit();

The container must manage transactions on a TX_BEAN_MANAGED Bean as follows.

When a client invokes a stateful TX_BEAN_MANAGED Bean, the container suspends any incoming transaction. The container allows the session instance to initiate a transaction using the javax.jts.UserTransaction interface. The instance becomes associated with the transaction and remains associated until the transaction terminates.

When a Bean-initiated transaction is associated with the instance, methods on the instances run under that transaction.

It is possible that a business method that initiated the transaction completes without committing or rolling back the transaction. The container must retain the association between the transaction and the instance across multiple client calls until the transaction terminates.

Table 5-1 Effect of declarative transaction attribute

Transaction Attribute Value	Client Transaction	Transaction of EJB Method
TX_NOT_SUPPORTED	none	none
	T1	none
TX_REQUIRED	none	new transaction - T2
	T1	T1
TX_SUPPORTS	none	none
	T1	T1
TX_REQUIRES_NEW	none	new transaction - T2
	T1	T2
TX_MANDATORY	none	TransactionRequired exception thrown
	T1	T1

session Synchronization

An EJB can optionally implement the session synchronization interface, to be notified by the container of the transactional state of the bean. The following methods are specified in the javax.ejb.SessionSynchronization interface:

afterBegin

public abstract void afterBegin() throws RemoteException

The afterBegin() method notifies a session Bean instance that a new transaction has started, and that the subsequent methods on the instance are invoked in the context of the transaction.

A bean can use this method to read data from a database and cache the data in the bean's fields.

This method executes in the proper transaction context.

beforeCompletion

public abstract void beforeCompletion() throws RemoteException

The container calls the beforeCompletion() method to notify a session bean that a transaction is about to be committed. You can implement this method to, for example, write any cached data to the database.

afterCompletion

public abstract void afterCompletion(boolean committed) throws RemoteException

The container calls afterCompletion() to notify a session bean that a transaction commit protocol has completed. The parameter tells the bean whether the transaction has been committed or rolled back.

This method executes with no transaction context.

JDBC

If you are using JDBC calls in your bean to update a database, you should not also use JDBC to perform transaction services, by calling methods on the JDBC connection. Do not code JDBC calls on a connection, for example:

Connection conn = ...
...
conn.commit();  // DO NOT DO THIS!!

You also avoid doing direct SQL commits or rollbacks through JDBC. Code the bean to either handle transactions directly using the javax.jts.UserTransactions interface (if the TransactionAttribute value is TX_BEAN_MANAGED), or let the bean container manage the bean transactions.

AuroraUserTransaction

You use the UserTransaction interface to manage transactions in Enterprise JavaBeans. The UserTransaction interface is a higher-level interface than the raw JTS, although its functionality is almost identical. However, EJB developers must use the UserTransaction interface for EJB bean-managed transaction support. The UserTransaction interface is used only for bean-managed EJBs.

See "serversideJTS" for a complete example of bean-managed transaction control.

To incorporate UserTransaction methods in your bean implementation code, follow these steps:

Import the javax.jts.UserTransaction package.
Be sure to get the session context, using the setSessionContext() SessionBean method. See the example.
Invoke the UserTransaction methods on the transaction context. See the example.

Methods


public void begin()

begin() creates a new transaction and associates it with the current bean.

Throws IllegalStateException if you attempt to invoke it in the context of an existing transaction.

public void commit()

commit() commits the transaction results, and completes the transaction associated with the current bean. When the commit() method completes, the bean is no longer associated with a transaction.

commit() can throw any of the following exceptions:

TransactionRolledbackException
HeuristicMixedException
HeuristicRollbackException
SecurityException
IllegalStateException
```
public int getStatus()
```

Returns the status of the current transaction. See "Java Transaction Service Methods" for more information about the status values that can be returned.

public void resume()

Resumes a suspended transaction.

public void rollback()

Rolls back the effects of the current transaction.

rollback() can throw the following exceptions:

IllegalStateException
SecurityException
```
public void setRollbackOnly()
```

The effect of a setRollbackOnly() invocation is that the only possible conclusion to the current transaction is a roll back operation. Any attempt to perform a commit() after setRollbackOnly() is invoked results in a exception.

setRollBackOnly() throws an IllegalStateException, if not in a transaction.

public void setTransactionTimeout(int arg1)

This method is implemented, but has no effect in this release. The timeout value is always 60 seconds.

Session Synchronization

An EJB can optionally implement the session synchronization interface, to be notified by the server of the state of the transaction. The following methods are specified in the javax.ejb.SessionSynchronization interface: