Skip Headers
Oracle® Fusion Middleware WebLogic Tuxedo Connector Programmer's Guide for Oracle WebLogic Server
12c Release 1 (12.1.1)

Part Number E24979-01
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

5 Oracle WebLogic Tuxedo Connector JATMI Transactions

This chapter describes how to define and manage Oracle WebLogic Tuxedo Connector global transactions using the Java Transaction API (JTA).

This chapter includes the following sections:

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

Note:

For more detailed information, see the JTA API at http://www.oracle.com/technetwork/java/javaee/jta/index.html.

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

  • TransactionManager

  • UserTransaction

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.

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

Note:

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, you must 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:

  • The calling process must be the same one that initiated the transaction with a begin()

  • The calling process must have no transaction replies outstanding

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.

  • Use setRollbackOnly() if further processing or cleanup is needed before rolling back the transaction.

  • Use rollback() if no further processing or cleanup is required before rolling back the transaction.

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:

Example 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;
}