		BEA WebLogic Enterprise 4.2 Developer Center
		HOME \| SITE MAP \| SEARCH \| CONTACT \| GLOSSARY \| PDF FILES \| WHAT'S NEW
		C++ REFERENCE \| TABLE OF CONTENTS \| PREVIOUS TOPIC \| NEXT TOPIC

Transaction Service

The WLE software provides an implementation of the CORBAservices Object Transaction Service that is described in Chapter 10 of the CORBAservices: Common Object Services Specification. This specification defines the interfaces for an object service that provides transactional functions.

This chapter describes how the WLE software implements that portion of the CORBAservices Object Transaction Service that is described as implementation specific.

This chapter provides the information that programmers need to write transactional applications for the WLE system. It describes the application programming interface (API) that you use to begin or terminate transactions, suspend or resume transactions, and get information about transactions.

Capabilities and Limitations

The following sections describe the capabilities and limitations of the Transaction Service.

Getting Initial References to the TransactionCurrent Object

To access the Transaction Service API and the extension to the Transaction Service API as described later in this chapter, an application needs to issue the following commands.

Create a Bootstrap object.
For details on creating a Bootstrap object, see Chapter 4, "Bootstrap Object".
Invoke the resolve_initial_reference("TransactionCurrent") method on the Bootstrap object. The invocation returns a standard CORBA object pointer. For a description of this Bootstrap object method, see the section "Tobj_Bootstrap::resolve_initial_references" on page 4-15.
If an application is interested in only the Transaction Service APIs, a CosTransactions::Current::_narrow() should be issued on the object pointer returned from step 2 above. If an application is interested in the Transaction Service APIs with the extensions, a Tobj::TransactionCurrent::_narrow() should be issued on the object pointer returned from step 2 above.

Transaction Service API

The following sections describe the portions of the CosTransactions modules that are based on CORBA that are implemented in the WLE software to support the Transaction Service. For further details, refer to Chapter 10 of the CORBAservices: Common Object Services Specification.

The definitions and interfaces supported by the Transaction Service in the WLE software are as follows:

Data types
Exceptions
CORBA::Current interface
Control interface
CosTransactions::TransactionalObject interface

Data Types

Listing 7-1 shows the supported data types.

Listing 7-1 Data Types Supported by the Transaction Service

enum Status {

       StatusActive,
       StatusMarkedRollback,
       StatusPrepared,
       StatusCommitted,
       StatusRolledBack,
       StatusUnknown,
       StatusNoTransaction
       StatusPreparing,
       StatusCommitting,
       StatusRollingBack,
};

// This information is taken from CORBAservices: Common Object 
// Services Specification, p. 10-15. Revised Edition: 
// March 31, 1995. Updated: March 1997. Used with permission by OMG.

Exceptions

Listing 7-2 shows the supported exceptions.

Listing 7-2 Exceptions Supported by the Transaction Service

// Heuristic exceptions
exception HeuristicMixed {};
exception HeuristicHazard {};

// Other transaction-specific exceptions
exception SubtransactionsUnavailable {};
exception NoTransaction {};
exception InvalidControl {};
exception Unavailable {};

Table 7-1 describes the exceptions.

Note: This information is taken from CORBAservices: Common Object Services Specification, pp. 10-16, 19, 20. Revised Edition: March 31, 1995. Updated: March 1997. Used with permission by OMG.

**Table 7-1 **Exceptions** Supported by the Transaction Service**
Exception	Description
HeuristicMixed	A request raises this exception to report that a heuristic decision was made and that some relevant updates have been committed and others have been rolled back.
HeuristicHazard	A request raises this exception to report that a heuristic decision was made, that the disposition of all relevant updates is not known, and that for those updates whose disposition is known, either all have been committed or all have been rolled back. Therefore, the HeuristicMixed exception takes priority over the HeuristicHazard exception.
SubtransactionsUnavailable	This exception is raised for the Current interface `begin` method if the client already has an associated transaction.
NoTransaction	This exception is raised for the Current interface rollback and rollback_only methods if there is no transaction associated with the client thread.
InvalidControl	This exception is raised for the Current interface resume method if the parameter is not valid in the current execution environment.
Unavailable	This exception is raised for the Control interface get_terminator and get_coordinator methods if the Control interface cannot provide the requested object.

Current Interface

The Current interface defines methods that allow a client of the Transaction Service to explicitly manage the association between threads and transactions. The Current interface also defines methods that simplify the use of the Transaction Service for most applications. These methods can be used to begin and end transactions, to suspend and resume transactions, and to obtain information about the current transaction.

The CosTransactions module defines the Current interface (shown in Listing 7-3).

Listing 7-3 Current Interface

// Current transaction 
interface Current : CORBA::Current {
       void begin()
              raises(SubtransactionsUnavailable);
       void commit(in boolean report_heuristics)
              raises(
                     NoTransaction,
                     HeuristicMixed,
                     HeuristicHazard
             );
       void rollback()
               raises(NoTransaction);
       void rollback_only()
               raises(NoTransaction);
       Status get_status();
       string get_transaction_name();
       void set_timeout(in unsigned long seconds);
       Control get_control();
       Control suspend();
       void resume(in Control which)
               raises(InvalidControl);

};

// This information is taken from CORBAservices: Common Object 
// Services Specification, p. 10-18. Revised Edition: 
// March 31, 1995. Updated: November 1997. Used with permission by // OMG

Table 7-2 provides a description of the Current transaction methods.

Note: This information is taken from CORBAservices: Common Object Services Specification, pp. 10-18, 19, 20. Revised Edition: March 31, 1995. Updated: November 1997. Used with permission by OMG.

**Table 7-2 Current Transaction Methods**
Method	Description
begin	Creates a new transaction. The transaction context of the client thread is modified so that the thread is associated with the new transaction. If the client thread is currently associated with a transaction, the `SubtransactionsUnavailable` exception is raised. If the client thread cannot be placed in transaction mode due to an error while starting the transaction, the `INVALID_TRANSACTION` standard system exception is raised. If the call was made in an improper context, the `BAD_INV_ORDER` standard system exception is raised.
`commit`	If there is no transaction associated with the client thread, the `NoTransaction` exception is raised. If the call was made in an improper context, the standard system exception `BAD_INV_ORDER` is raised. If the system decides to roll back the transaction, the standard exception `TRANSACTION_ROLLEDBACK` is raised and the thread's transaction context is set to null. A `HeuristicMixed` exception is raised to report that a heuristic decision was made and that some relevant updates have been committed and others have been rolled back. A `HeuristicHazard` exception is raised to report that a heuristic decision was made, and that the disposition of all relevant updates is not known; for those updates whose disposition is known, either all have been committed or all have been rolled back. The `HeuristicMixed` exception takes priority over the `HeuristicHazard` exception. If a heuristic exception is raised or the operation completes normally, the thread's transaction exception context is set to null. If the operation completes normally, the thread's transaction context is set to null.
`rollback`	If there is no transaction associated with the client thread, the `NoTransaction` exception is raised. If the call was made in an improper context, the standard system exception `BAD_INV_ORDER` is raised. If the operation completes normally, the thread's transaction context is set to null.
`rollback_only`	If there is no transaction associated with the client thread, the NoTransaction exception is raised. Otherwise, the transaction associated with the client thread is modified so that the only possible outcome is to roll back the transaction.
`get_status`	If there is no transaction associated with the client thread, the `StatusNoTransaction` value is returned. Otherwise, this method returns the status of the transaction associated with the client thread.
`get_transaction_name`	If there is no transaction associated with the client thread, an empty string is returned. Otherwise, this method returns a printable string describing the transaction (specifically, the XID as specified by The Open Group). The returned string is intended to support debugging.
`set_timeout`	This method modifies a state variable associated with the target object that affects the time-out period associated with transactions created by subsequent invocations of the begin method. If the parameter has a nonzero value `n`, transactions created by subsequent invocations of `begin` are subject to being rolled back if they do not complete before n seconds after their creation. If the parameter is zero, no time-out specified by the application is established. Note: The initial transaction timeout value is 300 seconds. If a transaction is started via `AUTOTRAN` instead of the `begin` method, then the timeout value is determined by the `TRANTIME` value in the WLE configuration file. For more information, refer to the Administration Guide.
`get_control`	If the client is not associated with a transaction, a null object reference is returned. Otherwise, a Control object is returned that represents the transaction context currently associated with the client thread. This object may be given to the `resume` method to reestablish this context.
`suspend`	If the client thread is not associated with a transaction, a null object reference is returned. If the associated transaction is in a state such that the only possible outcome of the transaction is to be rolled back, a `TRANSACTION_ROLLEDBACK` standard system exception is raised and the client thread becomes associated with no transaction. If the call was made in an improper context, the standard system exception `BAD_INV_ORDER` is raised. The caller's state with respect to the transaction is not changed. Otherwise, an object is returned that represents the transaction context currently associated with the client thread. The same client can subsequently give this object to the resume method to reestablish this context. In addition, the client thread becomes associated with no transaction. Note: As defined in The Common Object Request Broker: Architecture and Specification, Revision 2.2, February 1998, the `TRANSACTION_ROLLEDBACK` standard system exception indicates that the transaction associated with the request has already been rolled back or has been marked to roll back. Thus, the requested method either could not be performed or was not performed because further computation on behalf of the transaction would be fruitless.
`resume`	If the client thread is already associated with a transaction which is in a state such that the only possible outcome of the transaction is to be rolled back, the `TRANSACTION_ROLLEDBACK` standard system exception is raised and the client thread becomes associated with no transaction. If the call was made in an improper context, the standard system exception `BAD_INV_ORDER` is raised. If the system is unable to resume the global transaction because the caller is currently participating in work outside any global transaction with one or more resource managers, the `INVALID_TRANSACTION` standard system exception is raised. If the parameter is a null object reference, the client thread becomes associated with no transaction. If the parameter is valid in the current execution environment, the client thread becomes associated with that transaction (in place of any previous transaction). Otherwise, the `InvalidControl` exception is raised. Note: See `suspend` for a definition of the `TRANSACTION_ROLLEDBACK` standard system exception.

Control Interface

The Control interface allows a program to explicitly manage or propagate a transaction context. An object that supports the Control interface is implicitly associated with one specific transaction.

The CosTransactions module defines the Control interface (shown in Listing 7-4).

Listing 7-4 Control Interface

interface Control {
       Terminator get_terminator()
              raises(Unavailable);
       Coordinator get_coordinator()
              raises(Unavailable);
};

// This information is taken from CORBAservices: Common Object 
// Services Specification, p. 10-21. Revised Edition: 
// March 31, 1995. Updated: November 1997. Used with permission by // OMG.

Table 7-3 provides descriptions of the Control interface methods.

Note: This information is taken from CORBAservices: Common Object Services Specification, p. 10-22. Revised Edition: March 31, 1995. Updated: March 1997. Used with permission by OMG.

**Table 7-3 Control Interface Methods**
Method	Description
`get_terminator`	Returns a Terminator object, which supports methods to end the transaction. The object can be used to roll back or commit the transaction associated with the Control interface. The current WLE implementation of the CORBAservices Object Transaction Service always raises the `Unavailable` exception.
`get_coordinator`	Returns a Coordinator object, which supports methods needed by resources to participate in the transaction. The object can be used to register resources for the transaction associated with the Control interface. The current WLE implementation of the CORBAservices Object Transaction Service always raises the `Unavailable` exception.

TransactionalObject Interface

The CosTransactions::TransactionalObject interface is used by an object to indicate that it is transactional. By supporting this interface, an object indicates that it wants the transaction context associated with the client thread to be propagated on requests to the object. However, this interface is no longer needed. For details on transaction policies that need to be set to infect objects with transactions, see the sections "ICF Syntax" on page 2-2 and "CosTransactions::TransactionalObject Interface Not Enforced" on page 3-68.

The CosTransactions module defines the TransactionalObject interface (shown in Listing 7-5). The CosTransactions::TransactionalObject interface defines no methods. It is simply a marker.

Listing 7-5 TransactionalObject Interface

interface TransactionalObject {
};

// This information is taken from CORBAservices: Common Object 
// Services Specification, p. 10-30. Revised Edition: 
// March 31, 1995. Updated: November 1997. Used with permission by // OMG.

Other CORBAservices Object Transaction Service Interfaces

All other CORBAservices Object Transaction Service interfaces are not supported. Note that the Current interface described earlier is supported only if it has been obtained from the Bootstrap object. The Control interface described earlier is supported only if it has been obtained using the get_control() and the suspend() methods on the Current object.

Transaction Service API Extensions

This section describes specific extensions to the COBRAservices Transaction Service API described earlier. The APIs in this section enable an application to open or close an Open Group Resource Manager.

The following APIs help facilitate participation of resource managers in a distributed transaction by allowing their two-phase commit protocol to be controlled via The Open Group XA interface.

The following definitions and interfaces are defined in the Tobj module.

Exception

The following exception is supported:

exception RMfailed {};

A request raises this exception to report that an attempt to open or close a resource manager failed.

TransactionCurrent Interface

This interface supports all the methods of the Current interface in the CosTransactions module as described in the previous section. Additionally, this interface supports APIs to open and close the resource manager.

The Tobj module defines the TransactionCurrent interface, as shown in Listing 7-6.

Listing 7-6 TransactionCurrent Interface

Interface TransactionCurrent: CosTransactions::Current { void open_xa_rm() raises(RMfailed); void close_xa_rm() raises(Rmfailed); }

Table 7-4 describes APIs that are specific to the resource manager. For more information about these APIs, see sections "TP::close_xa_rm()" on page 3-48 and "TP::open_xa_rm()" on page 3-60.

**Table 7-4 Resource Manager APIs for the Current Interface**
Method	Description
open_xa_rm	This method opens The Open Group Resource Manager to which this process is linked. A `RMfailed` exception is raised if there is a failure while opening the Resource Manager. Any attempts to invoke this method by remote clients or the native clients raises a `NO_IMPLEMENT` standard system exception.
close_xa_rm	This method closes The Open Group Resource Manager to which this process is linked. An `RMfailed` exception is raised if there is a failure while closing the Resource Manager. A `BAD_INV_ORDER` standard system exception is raised if the function was called in an improper context (for example, the caller is in transaction mode). Any attempts by the remote clients or the native clients to invoke this method raises a `NO_IMPLEMENT` standard system exception.

Copyright � 1999 BEA Systems, Inc. All Rights Reserved.
Required browser version: Netscape Communicator version 4.0 or higher, or Microsoft Internet Explorer version 4.0 or higher.
Last update: July 06, 1999.