WebLogic Server 6.1 API Reference

weblogic.transaction
Interface TransactionManager

public interface TransactionManager

extends javax.transaction.TransactionManager

Allows XA resources to register and unregister themselves with the Transaction Manager on startup. It also allows a transaction to be suspended and resumed.

Author:

Copyright © 2001 BEA Systems, Inc. All Rights Reserved.

Method Summary

void	forceResume(javax.transaction.Transaction suspendedTx) If the transaction is active, resume automatically enlists statically registered resources and associates the transaction with the thread.
javax.transaction.Transaction	forceSuspend() suspend dissociates the transaction from the thread delists enlisted resources and marks the transaction for rollback in the event of any failures (for example, while delisting statically registered resources).
javax.transaction.Transaction	getTransaction(javax.transaction.xa.Xid xid) Given an XID returns the corresponding transaction object, if any.
void	registerDynamicResource(java.lang.String name, javax.transaction.xa.XAResource xar) Allows an application or XAResource adaptor to register a XA resource dynamically, typically before the resource is made available to the application.
void	registerStaticResource(java.lang.String name, javax.transaction.xa.XAResource xar) Allows an application or XAResource adaptor to register a XA resource statically, typically before the resource is made available to the application.
void	unregisterResource(java.lang.String name) unregisterResource removes a prior resource registration.

Methods inherited from interface javax.transaction.TransactionManager

begin, commit, getStatus, getTransaction, resume, rollback, setRollbackOnly, setTransactionTimeout, suspend

Method Detail

registerStaticResource

public void registerStaticResource(java.lang.String name,
                                   javax.transaction.xa.XAResource xar)
                            throws javax.transaction.SystemException

Allows an application or XAResource adaptor to register a XA resource statically, typically before the resource is made available to the application. Registering the XA resource statically means that the transaction service always enlists the resource when a transaction is attached to a thread. In other words, the resource is not expected to enlist itself when used. It is important to emphasize the fact that once a resource is registered statically, it gets automatically enlisted in every transaction.

While optional, this call improves performance during an enlistResource operation. If an enlistResource call is made and the resource (or another instance of its type) has not previously been registered, the transaction service automatically registers the new resource dynamically using the class name of the resource as the name. See below for description of registering a XA resource dynamically.

The registerStaticResource method has the following parameters:

Parameters:

name - The name of the resource. This name is used in error messages as well as in the branch qualifier part of all transaction ids supplied to the resource.

xar - A reference to a XAResource object that is subsequently used to handle recovery. It can also be the weblogic extension weblogic.transaction.XAResource.

registerDynamicResource

public void registerDynamicResource(java.lang.String name,
                                    javax.transaction.xa.XAResource xar)
                             throws javax.transaction.SystemException

Allows an application or XAResource adaptor to register a XA resource dynamically, typically before the resource is made available to the application. Registering the XA resource dynamically means that the transaction service does not enlist the resource at all. In other words, the resource is expected to enlist itself before every usage appropriately.

While optional, this call improves performance during an enlistResource operation. If an enlistResource call is made and the resource (or another instance of its type) has not previously been registered, the transaction service automatically registers the new resource dynamically using the class name of the resource as the name. See below for description of registering a XA resource dynamically.

The registerDynamicResource method has the following parameters:

Parameters:

name - The name of the resource. This name is used in error messages as well as in the branch qualifier part of all transaction ids supplied to the resource.

xar - A reference to a XAResource object that is subsequently used to handle recovery. It can also be the weblogic extension weblogic.transaction.XAResource.

unregisterResource

public void unregisterResource(java.lang.String name)
                        throws javax.transaction.SystemException

unregisterResource removes a prior resource registration. It is typically called when a system administrator decides not to host a resource on a particular server.

getTransaction

public javax.transaction.Transaction getTransaction(javax.transaction.xa.Xid xid)

Given an XID returns the corresponding transaction object, if any.

forceResume

public void forceResume(javax.transaction.Transaction suspendedTx)

If the transaction is active, resume automatically enlists statically registered resources and associates the transaction with the thread. It also checks to see if there's another transaction associated with the thread.

forceResume simply associates a transaction with a thread without further ado. It is used when you want to suspend a transaction in a thread and subsequently resume it without checking the state. This call is typically used by XA resource providers. Caution must be exercised when using this method because it bypasses all the sanity checks otherwise performed by resume.

The following example illustrates its use. Say, you want to make an RMI or JDBC call (or simply a call to a local object) without propagating the transaction, while ensuring that code after the RMI call sees the transaction in its original state. The following code illustrates the use of forceResume:

 import weblogic.transaction.TransactionManager;
 import weblogic.transaction.Transaction;

 TransactionManager tm = TxHelper.getTransaction();
 Transaction saveTx = null;
 try {
   saveTx = tm.forceSuspend();
    .. make non-transactional call ...
 } finally {
   tm.forceResume(saveTx);
 }
 

Weblogic rmi supports a marker interface called "NonTransactionRemote" and an rmi compiler option "-nontransactional". For those remote interfaces extending this interface (or by using the rmic command-line option) the complier inserts this boiler-plate code in the RMI stub.

See Also:

forceSuspend

public javax.transaction.Transaction forceSuspend()

suspend dissociates the transaction from the thread delists enlisted resources and marks the transaction for rollback in the event of any failures (for example, while delisting statically registered resources). forceSuspend merely dissociates the transaction from the thread; it doesn't delist resources, nor does it throw any exceptions.