BEA Systems, Inc.

weblogic.transaction
Interface TransactionManager

All Superinterfaces:
ClientTransactionManager, TransactionManager
All Known Subinterfaces:
ServerTransactionManager

public interface TransactionManager
extends ClientTransactionManager

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


Field Summary
static String ASYNC_TIMEOUT_DELIST
          A constant that is used as the name of the registration property that controls whether an enlisted resource is delisted by a different thread that is processing the transaction timeout prior to the timeout thread's invocation of XAResource.rollback.
static String CALL_SET_DELIST_TMSUCCESS_ALWAYS
          A constant that is used as the name of the registration property that controls whether the transaction manager sets the delistment flag .
static String CALL_SET_TRANSACTION_TIMEOUT
          A constant that is used as the name of the registration property that controls whether the transaction manager sets the resource timeout.
static String ENLISTMENT_DYNAMIC
          This enlistment mode requires the resource to dynamically enlist with the transaction manager when accessed by the application.
static String ENLISTMENT_STANDARD
          Allows an application or XAResource adaptor to register a XA resource dynamically, typically before the resource is made available to the application.
static String ENLISTMENT_STATIC
          Registering the XA resource statically means that the transaction service always enlists the resource when a transaction is attached to a thread.
static String ENLISTMENT_TYPE
          A constant that is used as the name of the resource registration property that determines the enlistment style of the resource being registered.
static String INTERLEAVING_ENLISTMENTS
          A constant that is used as the name of the registration property that controls interleaving enlistments.
static String LOCAL_ASSIGNMENT_OF_REMOTE_RESOURCES
          A constant that is used as the name of the registration property that controls how participating resources are assigned to servers.
static String RECOVER_RETRY_DURATION_SECONDS
          A constant that is used as the name of the registration property that controls whether recover will be retried for the specified duration in seconds.
static String RECOVER_RETRY_INTERVAL_SECONDS
          A constant that is used as the name of the registration property that controls the frequency in seconds at which the recover operation is performed on the resource.
static String THREAD_AFFINITY
          A constant that is used as the name of the registration property that controls whether an enlisted resource needs thread affinity.
 
Method Summary
 void begin(int timeoutseconds)
          Create a new transaction with the specified timeout value, and associate the transaction with the current thread.
 void begin(String name)
          Create a new transaction, set the transaction name property and associate the transaction with the current thread.
 void begin(String name, int timeoutseconds)
          Create a new transaction with the specified timeout value, set the transaction name property and associate the transaction with the current thread.
 Transaction getTransaction(Xid xid)
          Given an XID returns the corresponding transaction object, if any.
 void registerDynamicResource(String name, NonXAResource nxar)
          Register the NonXAResource with the transaction manager.
 void registerDynamicResource(String name, 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 registerResource(String name, 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 registerResource(String name, XAResource xar, Hashtable properties)
          Registers a resource under a specified name.
 void registerStaticResource(String name, 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(String name)
          unregisterResource removes a prior resource registration.
 void unregisterResource(String name, boolean blocking)
          When the blocking argument is true, unregisterResource will block until either all in-progress transactions for which the specified resource is a participant completes, or until the grace period expires.
 
Methods inherited from interface weblogic.transaction.ClientTransactionManager
forceResume, forceSuspend
 
Methods inherited from interface javax.transaction.TransactionManager
begin, commit, getStatus, getTransaction, resume, rollback, setRollbackOnly, setTransactionTimeout, suspend
 

Field Detail

ENLISTMENT_TYPE

static final String ENLISTMENT_TYPE
A constant that is used as the name of the resource registration property that determines the enlistment style of the resource being registered.

See Also:
TransactionManager.registerResource(String, XAResource, Hashtable), ENLISTMENT_DYNAMIC, ENLISTMENT_STATIC, ENLISTMENT_STANDARD, Constant Field Values

ENLISTMENT_DYNAMIC

static final String ENLISTMENT_DYNAMIC
This enlistment mode requires the resource to dynamically enlist with the transaction manager when accessed by the application.

See Also:
TransactionManager.registerResource(String, XAResource, Hashtable), ENLISTMENT_TYPE, Constant Field Values

ENLISTMENT_STATIC

static final String ENLISTMENT_STATIC
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.

See Also:
TransactionManager.registerResource(String, XAResource, Hashtable), ENLISTMENT_TYPE, Constant Field Values

ENLISTMENT_STANDARD

static final String ENLISTMENT_STANDARD
Allows an application or XAResource adaptor to register a XA resource dynamically, typically before the resource is made available to the application. The resource should enlist itself once with the transaction that it participates in. The Transaction Manager will perform subsequent re-enlistment of the resource in the transaction if necessary. Delistment is optional.

See Also:
TransactionManager.registerResource(String, XAResource, Hashtable), ENLISTMENT_TYPE, Constant Field Values

INTERLEAVING_ENLISTMENTS

static final String INTERLEAVING_ENLISTMENTS
A constant that is used as the name of the registration property that controls interleaving enlistments. When set to false, only a single thread will be allowed to be enlisted with a particular XAResource instance at any given time. Other threads attempting to enlist with an XAResource instance that is already enlisted will be blocked until the other application thread delists the resource from its transaction. The default value is true.

See Also:
TransactionManager.registerResource(String, XAResource, Hashtable), Constant Field Values

CALL_SET_TRANSACTION_TIMEOUT

static final String CALL_SET_TRANSACTION_TIMEOUT
A constant that is used as the name of the registration property that controls whether the transaction manager sets the resource timeout. When set to true, the transaction manager will call XAResource.setTransactionTimeout for each resource enlistment with a value approximately equal to that of the global transaction timeout. The default value is false.

See Also:
TransactionManager.registerResource(String, XAResource, Hashtable), Constant Field Values

LOCAL_ASSIGNMENT_OF_REMOTE_RESOURCES

static final String LOCAL_ASSIGNMENT_OF_REMOTE_RESOURCES
A constant that is used as the name of the registration property that controls how participating resources are assigned to servers. When set to true, a resource enlisted in the transaction on a non-coordinating server will be assigned to the coordinating server to perform XAResource operation if that resource is registered on the coordinating server. Setting this option to false will cause the transaction manager to always assign resources to a server where the resource was enlisted. The default value is true.

See Also:
TransactionManager.registerResource(String, XAResource, Hashtable), Constant Field Values

ASYNC_TIMEOUT_DELIST

static final String ASYNC_TIMEOUT_DELIST
A constant that is used as the name of the registration property that controls whether an enlisted resource is delisted by a different thread that is processing the transaction timeout prior to the timeout thread's invocation of XAResource.rollback.

See Also:
TransactionManager.registerResource(String, XAResource, Hashtable), Constant Field Values

THREAD_AFFINITY

static final String THREAD_AFFINITY
A constant that is used as the name of the registration property that controls whether an enlisted resource needs thread affinity. i.e, XA.start and XA.end should happen on the same thread.

See Also:
TransactionManager.registerResource(String, XAResource, Hashtable), Constant Field Values

RECOVER_RETRY_DURATION_SECONDS

static final String RECOVER_RETRY_DURATION_SECONDS
A constant that is used as the name of the registration property that controls whether recover will be retried for the specified duration in seconds. The default value is 0.

See Also:
Constant Field Values

RECOVER_RETRY_INTERVAL_SECONDS

static final String RECOVER_RETRY_INTERVAL_SECONDS
A constant that is used as the name of the registration property that controls the frequency in seconds at which the recover operation is performed on the resource. The default value is 30. Setting this registration option has no effect unless there is a positive value assigned for the RECOVER_RETRY_DURATION_SECONDS registration option.

See Also:
TransactionManager.RECOVER_RETRY_DURATION_SECONDS, Constant Field Values

CALL_SET_DELIST_TMSUCCESS_ALWAYS

static final String CALL_SET_DELIST_TMSUCCESS_ALWAYS
A constant that is used as the name of the registration property that controls whether the transaction manager sets the delistment flag . When set to true, the transaction manager will call delistment with the XAResource.TMSUCCESS flag before prepare.

See Also:
TransactionManager.registerResource(String, XAResource, Hashtable), Constant Field Values
Method Detail

registerStaticResource

void registerStaticResource(String name,
                            XAResource xar)
                            throws 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.

Throws:
SystemException

registerDynamicResource

void registerDynamicResource(String name,
                             XAResource xar)
                             throws 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.

Throws:
SystemException

registerResource

void registerResource(String name,
                      XAResource xar)
                      throws SystemException
Allows an application or XAResource adaptor to register a XA resource dynamically, typically before the resource is made available to the application. The resource should enlist itself once with the transaction that it participates in. The Transaction Manager will perform subsequent re-enlistment of the resource in the transaction if necessary. Delistment is optional.

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 registerResource 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.

Throws:
SystemException

unregisterResource

void unregisterResource(String name)
                        throws 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.

Throws:
SystemException

unregisterResource

void unregisterResource(String name,
                        boolean blocking)
                        throws SystemException
When the blocking argument is true, unregisterResource will block until either all in-progress transactions for which the specified resource is a participant completes, or until the grace period expires.

Throws:
SystemException
See Also:
TransactionManager.unregisterResource(String), JTAMBean.getUnregisterResourceGracePeriod()

getTransaction

Transaction getTransaction(Xid xid)
Given an XID returns the corresponding transaction object, if any.


begin

void begin(String name)
           throws NotSupportedException,
                  SystemException
Create a new transaction, set the transaction name property and associate the transaction with the current thread.

Parameters:
name - The descriptive name to be associated with the new transaction.
Throws:
NotSupportedException - Thrown if the thread is already associated with a transaction.
SystemException - Thrown if the transaction manager encounters an unexpected error condition.
See Also:
Transaction.setName(String)

begin

void begin(int timeoutseconds)
           throws NotSupportedException,
                  SystemException
Create a new transaction with the specified timeout value, and associate the transaction with the current thread.

Parameters:
timeoutseconds - The timeout value for the transaction. This value will override the default timeout value associated with the current thread. If a value of zero is specified the default timeout will be used.
Throws:
NotSupportedException - Thrown if the thread is already associated with a transaction.
SystemException - Thrown if the transaction manager encounters an unexpected error condition.
See Also:
TransactionManager.setTransactionTimeout(int)

begin

void begin(String name,
           int timeoutseconds)
           throws NotSupportedException,
                  SystemException
Create a new transaction with the specified timeout value, set the transaction name property and associate the transaction with the current thread.

Parameters:
name - The descriptive name to be associated with the new transaction.
timeoutseconds - The timeout value for the transaction. This value will override the default timeout value associated with the current thread. If a value of zero is specified the default timeout will be used.
Throws:
NotSupportedException - Thrown if the thread is already associated with a transaction.
SystemException - Thrown if the transaction manager encounters an unexpected error condition.
See Also:
Transaction.setName(String)

registerDynamicResource

void registerDynamicResource(String name,
                             NonXAResource nxar)
                             throws SystemException
Register the NonXAResource with the transaction manager.

Throws:
SystemException

registerResource

void registerResource(String name,
                      XAResource xar,
                      Hashtable properties)
                      throws SystemException
Registers a resource under a specified name. The enlistment type and other behavioral options for the resource may be specified.

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.

properties - Properties that control how the resource will be controlled by the transaction manager.
Throws:
SystemException
See Also:
ENLISTMENT_TYPE, ENLISTMENT_DYNAMIC, ENLISTMENT_STATIC, ENLISTMENT_STANDARD, INTERLEAVING_ENLISTMENTS, CALL_SET_TRANSACTION_TIMEOUT, LOCAL_ASSIGNMENT_OF_REMOTE_RESOURCES, THREAD_AFFINITY, CALL_SET_DELIST_TMSUCCESS_ALWAYS

Documentation is available at
http://download.oracle.com/docs/cd/E13222_01/wls/docs100
Copyright 2006 BEA Systems Inc.