Oracle WebLogic Tuxedo Connector Programmer's Guide

      

Oracle WebLogic Tuxedo Connector JATMI Transactions

The following sections provide information on global transactions and how to define and manage them in your applications:

 

Global Transactions

A global transaction is a transaction that allows work involving more than one resource manager and spanning more than one physical site to be treated as one logical unit. A global transaction is always treated as a specific sequence of operations that is characterized by the following four properties:

 

JTA Transaction API

For more detailed information, see the JTA API.

The Oracle WebLogic Tuxedo Connector uses the Java Transaction API (JTA) to manage transactions.

 

Types of JTA Interfaces

JTA offers three types of transaction interfaces:

Transaction

The Transaction interface allows operations to be performed against a transaction in the target Transaction object. A transaction object is created to correspond to each global transaction created. Use the Transaction interface to enlist resources, synchronize registration, and perform transaction completion and status query operations.

TransactionManager

The TransactionManager interface allows the application server to communicate to the Transaction Manager for transaction boundaries demarcation on behalf of the application. Use the TransactionManager interface to communicate to the transaction manager on behalf of container-managed EJB components.

UserTransaction

The UserTransaction interface is a subset of the TransactionManager interface. Use the UserTransaction interface when it is necessary to restrict access to Transaction object.

 

JTA Transaction Primitives

The following table maps the functionality of Oracle Tuxedo transaction primitives to equivalent JTA transaction primitives.

Table 5-1 Mapping Oracle Tuxedo Transaction Primitives to JTA Equivalents
Oracle Tuxedo Oracle Tuxedo Functionality JTA Equivalent
tpabort Use to end a transaction. setRollbackOnly or rollback
tpcommit Use to complete a transaction. commit
tpgetlev Use to determine if a service routine is in transaction mode. getStatus
tpbegin Use to begin a transaction. setTransactionTimeout begin

 

Defining a Transaction

Transactions can be defined in either client or server processes. A transaction has three parts: a starting point, the program statements that are in transaction mode, and a termination point.

To explicitly define a transaction, call the begin() method. The same process that makes the call, the initiator, must also be the one that terminates it by invoking a commit(), setRollbackOnly(), or rollback(). Any service subroutines that are called between the transaction delimiter become part of the current transaction.

 

Starting a Transaction

Setting setTransactionTimeout() to unrealistically large values delays system detection and reporting of errors. Use time-out values to ensure response to service requests occur within a reasonable time and to terminate transactions that have encountered problem, such as a network failure. For productions environments, adjust the time-out value to accommodate expected delays due to system load and database contention.

A transaction is started by a call to begin(). To specify a time-out value, precede the begin() statement with a setTransactionTimeout(int seconds) statement.

To propagate the transaction to Oracle Tuxedo, do the following:

Using TPNOTRAN

Service routines that are called within the transaction delimiter are part of the current transaction. However, if tpcall() or tpacall() have the flags parameter set to TPNOTRAN, the operations performed by the called service do not become part of that transaction. As a result, services performed by the called process are not affected by the outcome of the current transaction.

 

Terminating a Transaction

A transaction is terminated by a call to commit(), rollback(), or setRollbackOnly(). When commit() returns successfully, all changes to the resource as a result of the current transaction become permanent. In order for a commit() to succeed, the following two conditions must be met:

If either condition is not true, the call fails and an exception is thrown.

setRollbackOnly() and rollback() are used to indicate an abnormal condition and to roll back any call descriptors to their original state.

 

Oracle WebLogic Tuxedo Connector Transaction Rules

You must follow certain rules while in transaction mode to insure successful completion of a transaction. The basic rules of etiquette that must be observed while in a transaction mode follow:

 

Example Transaction Code

The following provides a code example for a transaction: Listing 5-1 Example Transaction Code 

public class TransactionSampleBean implements SessionBean {



.....



public int transaction_sample () {



     int ret = 0;

     try {

          javax.naming.Context myContext = new InitialContext();

          TransactionManager tm = (javax.transaction.TransactionManager)

          myContext.lookup("javax.transaction.TransactionManager");



// Begin Transaction

          tm.begin ();



          TuxedoConnectionFactory tuxConFactory = (TuxedoConnectionFactory) 

          ctxt.lookup("tuxedo.services.TuxedoConnection");



// You could do a local JDBC/XA-database operation here

// which will be part of this transaction.

.....



// NOTE 1: Get the Tuxedo Connection only after 

// you begin the transaction if you want the 

// Tuxedo call to be part of the transaction!



// NOTE 2: If you get the Tuxedo Connection before

// the transaction was started, all calls made from

// that Tuxedo Connection are out of scope of the 

// transaction.



          TuxedoConnection myTux = tuxConFactory.getTuxedoConnection();



// Do a tpcall. This tpcall is part of the transaction.

          TypedString depositData = new TypedString("somecharacters,5000.00");



          Reply depositReply = myTux.tpcall("DEPOSIT", depositData, 0);



// You could also do tpcalls which are not part of 

// transaction (For example, Logging all attempted 

// operations etc.) by setting the TPNOTRAN Flag!

          TypedString logData = 

          new TypedString("DEPOSIT:somecharacters,5000.00");



          Reply logReply = myTux.tpcall("LOGTRAN", logData, 

          ApplicationToMonitorInterface.TPNOTRAN);



// Done with the Tuxedo Connection. Do tpterm.

          myTux.tpterm ();



// Commit Transaction...

          tm.commit ();



// NOTE: The TuxedoConnection object which has been

// used in this transaction, can be used after the

// transaction only if TPNOTRAN flag is set.

}

          catch (NamingException ne) {

          System.out.println ("ERROR: Naming Exception looking up JNDI: " + ne);

          ret = -1;

}

          catch (RollbackException re) {

          System.out.println("ERROR: TRANSACTION ROLLED BACK: " + re);

          ret = 0;

}

          catch (TPException te) {

          System.out.println("ERROR: tpcall failed: TpException: " + te);

          ret = -1;

}

          catch (Exception e) {

          log ("ERROR: Exception: " + e);

          ret = -1;

}



          return ret;

}