7 Java Transaction API

Configure the Data Source

Use an emulated data source for a single phase commit. Refer to Chapter 4, "Data Sources", for information on emulated and nonemulated data source types.

If you can, use the default data source (data-sources.xml) that comes with a standard OC4J installation for the single-phase commit JTA transaction. After modifying this data source url attribute with your database URL information, retrieve the data source in your code using a JNDI lookup with the JNDI name configured in the ejb-location attribute. Configure a data source for each database involved in the transaction.

<data-source
  class="com.evermind.sql.DriverManagerDataSource"
  name="OracleDS"
  location="jdbc/OracleCoreDS"
  xa-location="jdbc/xa/OracleXADS"
  ejb-location="jdbc/OracleDS"
  connection-driver="oracle.jdbc.driver.OracleDriver"
  username="scott"
  password="tiger"
  url="jdbc:oracle:thin:@//localhost:1521/ORCL"
  inactivity-timeout="30"
/>

In the preceding example, myhost, myport, and mySID are entries that you must change. You must edit the example to provide meaningful values for myhost, myport, and mySID.

For information about the expected attribute definitions, see Chapter 4, "Data Sources".

Retrieve the Data Source Connection

Before executing any SQL statements against tables in the database, you must retrieve a connection to that database. For these updates to be included in the JTA transaction, perform the following two steps:

• Perform JNDI Lookup

• Retrieve a Connection

Perform JNDI Lookup

After the transaction has begun, look up the data source from the JNDI name space. Here are the two methods for retrieving the data source:

• Perform JNDI Lookup on Data Source Definition

• Perform JNDI Lookup Using Environment

Context ic = new InitialContext();
DataSource ds = (DataSource) ic.lookup("jdbc/OracleDS");
Connection conn = ds.getConnection();

<resource-ref>
     <res-ref-name>jdbc/OracleMappedDS</res-ref-name>
     <res-type>javax.sql.DataSource</res-type>
     <res-auth>Container</res-auth>
</resource-ref>

<resource-ref-mapping name="jdbc/OracleMappedDS" location="jdbc/OracleDS" />

InitialContext ic = new InitialContext();
DataSource ds = ic.lookup("java:comp/env/jdbc/OracleMappedDS");
Connection conn = ds.getConnection();

Retrieve a Connection

Retrieve a connection off this data source object using the getConnection method. You can do this in one of two ways:

• Use ds.getConnection() Use the method with no arguments.

• Use ds.getConnection(username, password). Use the method supplying a user name and password.

Use the method with no arguments when the data source definition contains the user name and password that you want.

Use the other method when the data source definition does not contain a user name and password, or when you want to use a user name and password that is different from what is specified in the data source.

Container-Managed Transactional Demarcation

If you define your bean to use CMTs, then you must specify how the container manages the JTA transaction for this bean in the <trans-attribute> element in the deployment descriptor (shown in Example 7-2). Table 7-1 briefly describes the transaction attribute types that you should specify in the deployment descriptor.

Example 7-2 shows the <container-transaction> portion of the deployment descriptor. It demonstrates how this bean specifies the RequiresNew transaction attribute for all (*) methods of the myEmployee EJB.

   <assembly-descriptor>
      <container-transaction>
         <description>no description</description>
         <method>
            <ejb-name>myEmployee</ejb-name>
            <method-name>*</method-name>
         </method>
        <trans-attribute>RequiresNew</trans-attribute>
      </container-transaction>
   </assembly-descriptor>

Bean-Managed Transactions

If you declare the bean as bean-managed transactional (BMT) within the <transaction-type>, then the bean implementation must demarcate the start, commit, or rollback for the global transaction. In addition, you must be careful to retrieve the data source connection after you start the transaction, not before.

JTA Transactions

The Web component or bean writer must explicitly issue begin, commit, and rollback methods of the UserTransaction interface, as follows:

Context initCtx = new Initial Context(); 
ut = (UserTransaction)  initCtx.lookup("java:comp/UserTransaction"); 
… 
ut.begin(); 
// Commit the transaction started in ejbCreate. 
Try { 
        ut.commit(); 
} catch (Exception ex) { …..} 

Database Configuration Steps

Designate and configure an Oracle9i Database Server database as the two-phase commit engine with the following steps:

1. Create the user (for example, COORDUSR) on the two-phase commit engine that facilitates the transaction, and perform the following three actions:

   1. The user must open a session from the two-phase commit engine to each of the involved databases.

   2. Grant the user the CONNECT, RESOURCE, CREATE SESSION privileges to be able to connect to each of these databases. The FORCE ANY TRANSACTION privilege allows the user to commit or roll back the transaction.

   3. Create this user and grant these permissions on all databases involved in the transaction.

   For example, if the user that is needed for completing the transaction is COORDUSR, do the following on the two-phase commit engine and each database involved in the transaction:

   CONNECT SYSTEM/MANAGER;
   CREATE USER COORDUSR IDENTIFIED BY COORDUSR;
   GRANT CONNECT, RESOURCE, CREATE SESSION TO COORDUSR;
   GRANT FORCE ANY TRANSACTION TO COORDUSR;
   
   

2. Configure fully qualified public database links (using the CREATE PUBLIC DATABASE LINK command) from the two-phase commit engine to each database that can be involved in the global transaction. This step is necessary for the two-phase commit engine to communicate with each database at the end of the transaction. The COORDUSR must be able to connect to all participating databases using these links.

   Figure 7-1 shows two databases involved in the transaction. The database link from the two-phase commit engine to each database is provided on each OrionCMTDataSource definition in a <property> element in the data-sources.xml file. See the next step for the "dblink" <property> element.

Figure 7-1 Two-Phase Commit Diagram

Description of the illustration O_1000.gif

OC4J Configuration Steps

1. To configure two-phase commit coordination: First, define the database that is to act as the two-phase commit engine, then configure it as follows:

   Define a nonemulated data source, using OrionCMTDataSource, for the two-phase commit engine database in the data-sources.xml file. The following code defines the two-phase commit engine OrionCMTDataSource in the data-sources.xml file.

   <data-source
     class="com.evermind.sql.OrionCMTDataSource"
     name="OracleCommitDS"
     location="jdbc/OracleCommitDS"
     connection-driver="oracle.jdbc.driver.OracleDriver"
     username="coordusr"
     password="coordpwd"
     url="jdbc:oracle:thin:@//localhost:1521/ORCL"
     inactivity-timeout="30"
   />
   
   

   Refer to the two-phase commit engine data source in the global application.xml file, which resides in the config directory.

   Configure the two-phase commit engine as follows:

   <commit-coordinator>
    <commit-class class="com.evermind.server.OracleTwoPhaseCommitDriver" />
    <property name="datasource" value="jdbc/OracleCommitDS" />
    <property name="username" value="coordusr" />
    <property name="password" value="coordpwd" />
   </commit-coordinator>
   

   
   

   Note: The password attribute of the <commit-coordinator> element supports password indirection. For more information, refer to the Oracle Application Server Containers for J2EE Security Guide.

   
   

   The parameters are as follows:

   Specify the JNDI name of "jdbc/OracleCommitDS" for the OrionCMTDataSource that is defined in the data-sources.xml file. This identifies the data source to use as the two-phase commit engine.

   Specify the two-phase commit engine user name and password. This step is optional, because you could also specify it in the data source configuration. These are the user name and password to use as the login authorization to the two-phase commit engine. This user must have the FORCE ANY TRANSACTION database privilege, or all session users must be identical to the user that is the commit coordinator.

   Specify the <commit-class>. This class is always OracleTwoPhaseCommitDriver for two-phase commit engines.

   The JNDI name for the OrionCMTDataSource is identified in the <property> element whose name is "datasource".

   The user name is identified in the <property> element "username".

   The password is identified in the <property> element "password".

2. To configure databases that will participate in a global transaction, configure nonemulated data source objects of the type OrionCMTDataSource for each database involved in the transaction with the following information:

   1. The JNDI bound name for the object.

   2. The URL for creating a connection to the database.

   3. The fully qualified database link from the two-phase commit engine to this database (for example, LINK1.machine1.COM). This is provided in a <property> element within the data source definition in the data-sources.xml file.

   The following OrionCMTDataSource objects specify the two databases involved in the global transaction. Notice that each of them has a <property> element named "dblink" that denotes the database link from the two-phase commit engine to itself.

   <data-source
     class="com.evermind.sql.OrionCMTDataSource"
     name="OracleCMTDS1"
     location="jdbc/OracleDS1"
     connection-driver="oracle.jdbc.driver.OracleDriver"
     username="scott"
     password="tiger"
       url="jdbc:oracle:thin:@//localhost:1521/db1.ORCL"
     inactivity-timeout="30">
     <property name="dblink" 
      value="LINK1.machine1.COM"/> 
   </data-source>
   
   <data-source
     class="com.evermind.sql.OrionCMTDataSource"
     name="OracleCMTDS2"
     location="jdbc/OracleDS2"
     connection-driver="oracle.jdbc.driver.OracleDriver"
     username="scott"
     password="tiger"
        url="jdbc:oracle:thin:@//localhost:1521/db2.ORCL"
     inactivity-timeout="30">
     <property name="dblink" 
      value="LINK2.machine2.COM"/> 
   </data-source>
   
   

   
   

   Note: If you change the two-phase commit engine, then you must update all database links—both within the new two-phase commit engine as well as within the OrionCMTDataSource <property> definitions.

   
   

After the two-phase commit engine and all the databases involved in the transaction are configured, you can start and stop a transaction in the same manner as the single-phase commit. See "Single-Phase Commit" for more information.

MDBs that Use Container-Managed Transactions

If you define your MDB with container-managed transactions you can set a retry count and interval for re-establishing the JMS session. Then, if your transaction fails while interacting with a database, the container automatically retries (within the specified interval) until the count is reached. To set the automatic retry count and interval, set the following optional attributes in the <message-driven-deployment> element in the MDB orion-ejb-jar.xml file:

• dequeue-retry-count—Specifies how often the listener thread tries to re-acquire the JMS session over a new database connection once database failover has occurred. The default is "0."

• dequeue-retry-interval—Specifies the interval between retries. The default is 60 seconds.

MDBs that Use Bean-Managed Transactions and JMS Clients

The container does not manage bean-managed transactional MDBs or JMS clients. Thus, when they receive an exception denoting that the JDBC connection has failed, each must understand if this is a scenario where the method within the transaction can be retried. To determine if this is a retry scenario, input the database connection and the SQL exception as parameters in the DbUtil.oracleFatalError() method.

You must retrieve the database connection from the JMS session object, and the SQL exception from the returned JMS exception, as follows:

1. Retrieve the underlying SQL exception from the JMS exception.

2. Retrieve the underlying database connection from the JMS session.

3. Execute the DbUtil.oracleFatalError() method to determine if the exception indicates an error that you can retry. If this method returns true, then create a new JMS connection, session, and possible sender to continue the JMS activity.

The following code demonstrates how to process the JMS exception, jmsexc, to pull out the SQL exception, sql_ex. In addition, the database connection, db_conn, is retrieved from the JMS session, session. The SQL exception and database connection are input parameters for the DbUtil.oracleFatalError method.

try 
{ 
 .. 
} 
catch(Exception e ) 
{ 
 if (exc instanceof JMSException) 
 { 
  JMSException  jmsexc = (JMSException) exc; 
  sql_ex = (SQLException)(jmsexc.getLinkedException()); 
  db_conn = (oracle.jms.AQjmsSession)session.getDBConnection(); 

  if ((DbUtil.oracleFatalError(sql_ex, db_conn)) 
  { 
    // Since the DBUtil function returned true, regain the JMS objects
    // Look up the Queue Connection Factory. 
    QueueConnectionFactory qcf = (QueueConnectionFactory)
               ctx.lookup ("java:comp/resource/" + resProvider + 
               "/QueueConnectionFactories/myQCF"); 

    // Lookup the Queue.  
    Queue queue = (Queue) ctx.lookup ("java:comp/resource/" + resProvider +
                                       "/Queues/rpTestQueue");
      
    // Retrieve a connection and a session on top of the connection. 
    // Create queue connection using the connection factory. 
    QueueConnection qconn = qcf.createQueueConnection();

    // We're receiving msgs, so start the connection.  
    qconn.start();

 // Create a session over the queue connection. 
    QueueSession qsess = qconn.createQueueSession(false,
                                                   Session.AUTO_ACKNOWLEDGE);

    //Since this is for a queue, create a sender on top of the session. 
    //This is used to send out the message over the queue.
    QueueSender snd = sess.createSender (q);
 
  } 
 } 
}