WebLogic Server 8.1 API Reference

weblogic.transaction
Interface TransactionManager

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.

Author:

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

Field Summary

static int	ENLISTMENT_DYNAMIC This enlistment mode requires the resource to dynamically enlist with the transaction manager when accessed by the application.
static int	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 int	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 int	OPTIONS_CALL_SET_TRANSACTION_TIMEOUT This resource registration option will cause the transaction manager to call XAResource.setTransactionTimeout for each resource enlistment with a value approximately equal to that of the global transaction timeout.
static int	OPTIONS_NO_INTERLEAVING_ENLISTMENTS This registration option instructs the transaction manager to serialize interleaved enlistments with the resource.
static int	OPTIONS_NONE No resource registration options specified.

Method Summary

void	begin(java.lang.String name) Create a new transaction, set the transaction name property and associate the transaction with the current thread.
void	begin(java.lang.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.
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, weblogic.transaction.nonxa.NonXAResource nxar) Register the NonXAResource with the transaction manager.
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	registerResource(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	registerResource(java.lang.String name, javax.transaction.xa.XAResource xar, int enlistmentType, int options) Registers a resource under a specified name.
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 weblogic.transaction.ClientTransactionManager

forceResume, forceSuspend

Methods inherited from interface javax.transaction.TransactionManager

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

Field Detail

ENLISTMENT_DYNAMIC

public static final int ENLISTMENT_DYNAMIC

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

ENLISTMENT_STATIC

public static final int 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.

ENLISTMENT_STANDARD

public static final int 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.

OPTIONS_NONE

public static final int OPTIONS_NONE

No resource registration options specified. This flag can not be used in conjunction with other registration option flags.

OPTIONS_NO_INTERLEAVING_ENLISTMENTS

public static final int OPTIONS_NO_INTERLEAVING_ENLISTMENTS

This registration option instructs the transaction manager to serialize interleaved enlistments with the resource. 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.

OPTIONS_CALL_SET_TRANSACTION_TIMEOUT

public static final int OPTIONS_CALL_SET_TRANSACTION_TIMEOUT

This resource registration option will cause the transaction manager to call XAResource.setTransactionTimeout for each resource enlistment with a value approximately equal to that of the global transaction timeout.

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.

registerResource

public void registerResource(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. 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.

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.

begin

public void begin(java.lang.String name)
           throws javax.transaction.NotSupportedException,
                  javax.transaction.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:

javax.transaction.NotSupportedException - Thrown if the thread is already associated with a transaction.

javax.transaction.SystemException - Thrown if the transaction manager encounters an unexpected error condition.

See Also:

Transaction.setName(String)

begin

public void begin(java.lang.String name,
                  int timeoutseconds)
           throws javax.transaction.NotSupportedException,
                  javax.transaction.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:

javax.transaction.NotSupportedException - Thrown if the thread is already associated with a transaction.

javax.transaction.SystemException - Thrown if the transaction manager encounters an unexpected error condition.

See Also:

Transaction.setName(String)

registerDynamicResource

public void registerDynamicResource(java.lang.String name,
                                    weblogic.transaction.nonxa.NonXAResource nxar)
                             throws javax.transaction.SystemException

Register the NonXAResource with the transaction manager.

registerResource

public void registerResource(java.lang.String name,
                             javax.transaction.xa.XAResource xar,
                             int enlistmentType,
                             int options)
                      throws javax.transaction.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.

enlistmentType - Determines how the resource will be enlisted in global transactions. Valid values are ENLISTMENT_DYNAMIC, ENLISTMENT_STATIC or ENLISTMENT_STANDARD.

options - The options paramater is a bit-mask that provides control over how the transaction manager interacts with the resource. The only option is OPTIONS_NO_INTERLEAVING_ENLISTMENTS.