6 Java Transaction API and Oracle WebLogic Extensions

JTA API Overview

WebLogic Server supports the javax.transaction package and the javax.transaction.xa package, from Sun Microsystems, Inc., which implement the Java Transaction API (JTA) for Java applications. For more information about JTA, see the Java Transaction API (JTA) Specification published by Sun Microsystems, Inc., at http://java.sun.com/javaee/technologies/jta/index.jsp. For a detailed description of the javax.transaction and javax.transaction.xa interfaces, see the JTA Javadoc.

JTA includes the following components:

• An interface for demarcating and controlling transactions from an application, javax.transaction.UserTransaction. You use this interface as part of a Java client program or within an EJB as part of a bean-managed transaction.

• An interface for allowing a transaction manager to demarcate and control transactions for an application, javax.transaction.TransactionManager. This interface is used by an EJB container as part of a container-managed transaction and uses the javax.transaction.Transaction interface to perform operations on a specific transaction.

• Interfaces that allow the transaction manager to provide status and synchronization information to an applications server, javax.transaction.Status and javax.transaction.Synchronization. These interfaces are accessed only by the transaction manager and cannot be used as part of an applications program.

• Interfaces for allowing a transaction manager to work with resource managers for XA-compliant resources (javax.transaction.xa.XAResource) and to retrieve transaction identifiers (javax.transaction.xa.Xid). These interfaces are accessed only by the transaction manager and cannot be used as part of an applications program.

Oracle WebLogic Extensions to JTA

Extensions to the Java Transactions API are provided where the JTA specification does not cover implementation details and where additional capabilities are required.

Oracle WebLogic provides the following capabilities based on interpretations of the JTA specification:

• Client-initiated transactions—the JTA transaction manager interface (javax.transaction.TransactionManager) is made available to clients and bean providers through JNDI. This allows clients and EJBs using bean-managed transactions to suspend and resume transactions.

  Note:

  A suspended transaction must be resumed in the same server process in which it was suspended.

• Scope of transactions—transactions can operate within and between clusters and domains.

• Enhanced javax.transaction.TransactionSynchronizationRegistry support—WebLogic Server provides the ability to lookup the TransactionSynchronizationRegistry object in JNDI using the standard name of java:comp/TransactionSynchronizationRegistry. Oracle extends support by providing two additional global JNDI names: javax/transaction/TransactionSynchronizationRegistry and weblogic/transaction/TransactionSynchronizationRegistry. For more information, see javax.transaction.TransactionSynchronizationRegistry at http://java.sun.com/javaee/5/docs/api/index.html?javax/transaction/TransactionSynchronizationRegistry.html.

Oracle WebLogic Server provides the following classes and interfaces as extensions to JTA:

• weblogic.transaction.RollbackException (extends javax.transaction.RollbackException)

  This class preserves the original reason for a rollback for use in more comprehensive exception information.

• weblogic.transaction.TransactionManager (extends javax.transaction.TransactionManager)

  The WebLogic JTA transaction manager object supports this interface, which allows XA resources to register and unregister themselves with the transaction manager on startup. It also allows a transaction to be resumed after suspension.

  This interface includes the following methods:

  • registerStaticResource, registerDynamicResource, and unregisterResource

  • registerResource— (new in WebLogic Server 8.1) This method includes support for properties that determine how the resource is controlled by the transaction manager.

  • getTransaction

  • forceResume and forceSuspend

  • begin

• weblogic.transaction.Transaction (extends javax.transaction.Transaction)

  The WebLogic JTA transaction object supports this interface, which allows users to get and set transaction properties.

  This interface includes the following methods:

  • setName and getName

  • addProperties, setProperty, getProperty, and getProperties

  • setRollbackReason and getRollbackReason

  • getHeuristicErrorMessage

  • getXID and getXid

  • getStatusAsString

  • getMillisSinceBegin

  • getTimeToLiveMillis

  • isTimedOut

• weblogic.transaction.TransactionHelper

  This class enables you to obtain the current transaction manager and transaction. It replaces TxHelper.

  This interface includes the following static methods:

  • getTransaction

  • getUserTransaction

  • getTransactionManager

• weblogic.transaction.TxHelper (Deprecated, use TransactionHelper instead)

  This class enables you to obtain the current transaction manager and transaction.

  This interface includes the following static methods:

  • getTransaction, getUserTransaction, getTransactionManager

  • status2String

• weblogic.transaction.XAResource (extends javax.transaction.xa.XAResource)

  This class provides delistment capabilities for XA resources.

  This interface includes the following method:

  • getDelistFlag

• weblogic.transaction.nonxa.NonXAResource

  This interface enables resources that do not support the javax.transaction.xa.XAResource interface to easily integrate with the WebLogic Server transaction manager. The transaction manager supports a variation of the Last Agent two-phase commit optimization that allows a non-XA resource to participate in a distributed transaction. The protocol issues a one-phase commit to the non-XA resource and uses the result of the operation to base the commit decision for the transaction.

For a detailed description of the WebLogic extensions to the javax.transaction and javax.transaction.xa interfaces, see the weblogic.transaction package summary in the Oracle WebLogic Server API Reference.