With stateless session beans, transactions that are managed using UserTransaction must be started and completed within the same method. In other words, UserTransaction transactions cannot be started in one method and ended in another. This makes sense because stateless session bean instances are shared across many clients; while one stateless instance may service a client’s first request, a completely different instance may service a subsequent request by the same client. With stateful session beans, however, a transaction can begin in one method and be committed in another because a stateful session bean is used by only one client. Therefore, a stateful session bean can associate itself with a transaction across several different client-invoked methods. As an example, imagine the TravelAgent EJB as a BMT bean. In the following code, the transaction is started in the setCruiseID( ) method and completed in the bookPassage( ) method. This allows the TravelAgent EJB’s methods to be associated with the same transaction. The definition of the TravelAgentBean class looks like this:

import com.titan.reservation.*;

import java.sql.*;
import javax.sql.DataSource;
import java.util.Vector;
import java.rmi.RemoteException;
import javax.naming.NamingException;
import javax.ejb.EJBException;

public class TravelAgentBean implements javax.ejb.SessionBean {
    ...
    public void setCruiseID(Integer cruiseID)
        throws javax.ejb.FinderException { 
        try { 
            ejbContext.getUserTransaction( ).begin( );
            CruiseHomeLocal home = (CruiseHomeLocal)
                jndiContext.lookup("java:comp/env/ejb/CruiseHome");
           
            cruise = home.findByPrimaryKey(cruiseID);
        } catch(RemoteException re) {
            throw new EJBException(re);
        }
        
    }
    public TicketDO bookPassage(CreditCardDO card, double price)
        throws IncompleteConversationalState {

        try {
                              if (ejbContext.getUserTransaction( ).getStatus( ) != 
                                  javax.transaction.Status.STATUS_ACTIVE) {

                                  throw new EJBException("Transaction is not active");
                              }

                          } catch(javax.transaction.SystemException se) {
                               throw new EJBException(se);
                          }
                   
        if (customer == null || cruise == null || cabin == null) 
        {
            throw new IncompleteConversationalState( );
        }
        try {
            ReservationHomeLocal resHome = (ReservationHomeLocal)
                jndiContext.lookup("java:comp/env/ejb/ReservationHomeLocal");
            
            ReservationLocal reservation =
                resHome.create(customer, cruise, cabin, price);
                
            Object ref = 
                jndiContext.lookup("java:comp/env/ejb/ProcessPaymentHomeRemote");

            ProcessPaymentHomeRemote ppHome = (ProcessPaymentHomeRemote)
                PortableRemoteObject.narrow(ref, ProcessPaymentHomeRemote.class);
            
            ProcessPaymentRemote process = ppHome.create( );
            process.byCredit(customer, card, price);

            TicketDO ticket = new TicketDO(customer,cruise,cabin,price);

            ejbContext.getUserTransaction( ).commit( );

            return ticket;
        } catch(Exception e) {
            throw new EJBException(e);
        }
    }
    ...
}

Repeated calls to the EJBContext.getUserTransaction( ) method return a reference to the same UserTransaction object. The container is required to retain the association between the transaction and the stateful bean instance across multiple client calls until the transaction terminates.

In the bookPassage( ) method, we can check the status of the transaction to ensure that it is still active. If the transaction is no longer active, we throw an exception. The use of getStatus( ) is covered in more detail later in this chapter.

When a client that is already involved in a transaction invokes a bean-managed transaction method, the client’s transaction is suspended until the method returns. This suspension occurs regardless of whether the BMT bean explicitly started its own transaction within the method or the transaction was started in a previous method invocation. The client transaction is always suspended until the BMT method returns.

<ejb-jar>
    <enterprise-beans>
    ...
        <message-driven>
        ...
          <transaction-type>Bean</transaction-type>
        ...

public class ReservationProcessorBean implements javax.ejb.MessageDrivenBean,
    javax.jms.MessageListener {

     MessageDrivenContext ejbContext;
    Context jndiContext;

    public void onMessage(Message message) {
        try {

            ejbContext.getUserTransaction( ).begin( );

            MapMessage reservationMsg = (MapMessage)message;

            Integer customerPk = (Integer)reservationMsg.getObject("CustomerID");
            Integer cruisePk = (Integer)reservationMsg.getObject("CruiseID");
            Integer cabinPk = (Integer)reservationMsg.getObject("CabinID");
            double price = reservationMsg.getDouble("Price");

            //get the credit card
            Date expirationDate = 
                new Date(reservationMsg.getLong("CreditCardExpDate"));
            String cardNumber = reservationMsg.getString("CreditCardNum");
            String cardType = reservationMsg.getString("CreditCardType");

            CreditCardDO card = 
                new CreditCardDO(cardNumber,expirationDate,cardType);
            CustomerRemote customer = getCustomer(customerPk);
            CruiseLocal cruise = getCruise(cruisePk);
            CabinLocal cabin = getCabin(cabinPk);

            ReservationHomeLocal resHome = (ReservationHomeLocal)
                jndiContext.lookup("java:comp/env/ejb/ReservationHomeLocal");
            ReservationLocal reservation =
                resHome.create(customer,cruise,cabin,price,new Date( ));

            Object ref = 
                jndiContext.lookup("java:comp/env/ejb/ProcessPaymentHomeRemote");
            ProcessPaymentHomeRemote ppHome = (ProcessPaymentHomeRemote)
                PortableRemoteObject.narrow(ref,ProcessPaymentHomeRemote.class);
            ProcessPaymentRemote process = ppHome.create( );

            process.byCredit(customer,card,price);
            TicketDO ticket = new TicketDO(customer,cruise,cabin,price);
            deliverTicket(reservationMsg,ticket);

            ejbContext.getUserTransaction.commit( );

        } catch(Exception e) {
            throw new EJBException(e);
        }
    }
    ...

Transactions are normally controlled by a transaction manager (often the EJB server) that manages the ACID characteristics across several enterprise beans, databases, and servers. The transaction manager uses a two-phase commit (2-PC) to manage transactions. 2-PC is a protocol for managing transactions that commits updates in two stages. 2-PC is complex, but basically it requires that servers and databases cooperate through an intermediary—the transaction manager—in order to ensure that all the data is made durable together. Some EJB servers support 2-PC, while others do not, and the value of this transaction mechanism is a source of some debate. The important point to remember is that a transaction manager controls the transaction; based on the results of a poll against the resources (databases, JMS providers, and other resources), it decides whether all the updates should be committed or rolled back. A heuristic decision takes place when one of the resources makes a unilateral decision to commit or roll back without permission from the transaction manager. When a heuristic decision has been made, the atomicity of the transaction is lost and data-integrity errors can occur.

UserTransaction, discussed in the next section, throws a few different exceptions related to heuristic decisions; these are included in the following discussion.

EJB servers are required to support UserTransaction, but not required to support the rest of JTA, nor are they required to use JTS for their transaction service. The UserTransaction is defined as:

public interface javax.transaction.UserTransaction {

    public abstract void begin( ) throws IllegalStateException, SystemException;
    public abstract void commit( ) throws IllegalStateException, SystemException, 
        TransactionRolledbackException, HeuristicRollbackException, 
        HeuristicMixedException;
    public abstract int getStatus( );
    public abstract void rollback( ) throws IllegalStateException, SecurityException,
        SystemException;
    public abstract void setRollbackOnly( ) throws IllegalStateException, 
        SystemException;
    public abstract void setTransactionTimeout(int seconds) throws SystemException;

}

Here’s what the methods defined in this interface do:

Status is a simple interface that contains no methods, only constants. Its sole purpose is to provide a set of constants that describe the current status of a transactional object—in this case, the UserTransaction:

interface javax.transaction.Status
{
    public final static int STATUS_ACTIVE;
    public final static int STATUS_COMMITTED;
    public final static int STATUS_COMMITTING;
    public final static int STATUS_MARKED_ROLLBACK;
    public final static int STATUS_NO_TRANSACTION;
    public final static int STATUS_PREPARED;
    public final static int STATUS_PREPARING;
    public final static int STATUS_ROLLEDBACK;
    public final static int STATUS_ROLLING_BACK;
    public final static int STATUS_UNKNOWN;
}

The value returned by getStatus( ) tells the client using the UserTransaction the status of a transaction. Here’s what the constants mean:

Only BMT beans have access to the UserTransaction from the EJBContext and JNDI ENC. Container-managed transaction (CMT) beans cannot use the UserTransaction. CMT beans use the setRollbackOnly( ) and getRollbackOnly( ) methods of the EJBContext to interact with the current transaction instead.

The setRollbackOnly( ) method gives an enterprise bean the power to veto a transaction. This power can be used if the enterprise bean detects a condition that would cause inconsistent data to be committed when the transaction completes. Once an enterprise bean invokes the setRollbackOnly( ) method, the current transaction is marked for rollback and cannot be committed by any other participant in the transaction—including the container.

The getRollbackOnly( ) method returns true if the current transaction has been marked for rollback. This information can be used to avoid executing work that would not be committed anyway. If, for example, an exception is thrown and captured within an enterprise bean method, getRollbackOnly( ) can be used to determine whether the exception caused the current transaction to be rolled back. If it did, there is no sense in continuing the processing. If it did not, the EJB has an opportunity to correct the problem and retry the task that failed. Only expert EJB developers should attempt to retry tasks within a transaction. Alternatively, if the exception did not cause a rollback (getRollbackOnly( ) returns false), a rollback can be forced using the setRollbackOnly( ) method.

BMT beans must not use the setRollbackOnly( ) and getRollbackOnly( ) methods of the EJBContext. BMT beans should use the getStatus( ) and rollback( ) methods on the UserTransaction object to check for rollback and force a rollback, respectively.