
	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	e-docs.beasys.com \| Site Map \| Search \| PDF Files \| Contact \| Glossary

WLE Doc Home \| Transactions & Related Topics \| Previous \| Next \| Contents \| Index

Transaction Service

This topic includes the following sections:

This topic provides the information that programmers need to write transactional applications for the WebLogic Enterprise (WLE) system. Before you begin, you should read Introducing Transactions.

About the Transaction Service

WLE provides a Transaction Service that supports transactions in CORBA, EJB, and RMI applications. The Transaction Service provides:

An implementation of the CORBAservices Object Transaction Service (OTS) 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.
In the WLE EJB Container, an implementation of the transaction services described in Sun Microsystem's Enterprise JavaBeans Specification 1.1 (Public Release 2 dated October 18, 1999).

For CORBA Java, EJB, and RMI applications, WLE also provides Sun Microsystems, Inc.'s javax.transaction package, which implements the Java Transaction API (JTA) for Java applications. For more information about the JTA, see Sun Microsystem's Java Transaction API (JTA) Specification (version1.0.1). For more information about the UserTransaction object that applications use to demarcate transaction boundaries, see UserTransaction API.

Capabilities and Limitations

This topic includes the following sections:

These sections describe the capabilities and limitations of the Transaction Service that supports CORBA and EJB applications:

Transaction Service in CORBA Applications

This topic includes the following sections:

These sections describe how WLE implements the OTS, with particular emphasis on the portion of the CORBAservices Object Transaction Service that is described as implementation-specific. They describe the OTS application programming interface (API) that you use to begin or terminate transactions, suspend or resume transactions, and get information about transactions.

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 complete the following operations:

Create a Bootstrap object. For more information about creating a Bootstrap object, see "C++ Bootstrap Object Programming Reference" in the CORBA C++ Programming Reference.
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 CORBA C++ Programming Reference.
If an application requires only the Transaction Service APIs, it should issue an org.omg.CosTransactions.Current.narrow() (in Java) or CosTransactions::Current::_narrow() (in C++) on the object pointer returned from step 2 above.
If an application requires the Transaction Service APIs with the extensions, it should issue a com.beasys.Tobj.TransactionCurrent.narrow() (in Java) or Tobj::TransactionCurrent::_narrow() (in C++) on the object pointer returned from step 2 above.

CORBA Transaction Service API

This topic includes the following sections:

These sections describe the CORBA-based components of the CosTransactions modules that WLE implements to support the Transaction Service. For more information about these components, see Chapter 10 of the CORBAservices: Common Object Services Specification.

Data Types

Listing 2-1 shows the supported data types.

Listing 2-1 Data Types Supported by the Transaction Service

enum Status {

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

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

Exceptions

Listing 2-2 shows the supported exceptions in IDL code.

Listing 2-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 2-1 describes the exceptions.

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

Table 2-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.

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 2-3).

Listing 2-3 Current Interface idl

// 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 comes from CORBAservices: Common Object
// Services Specification, p. 10-18. Revised Edition:
// March 31, 1995. Updated: November 1997. Used with permission by // OMG

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

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

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 standard system exception INVALID_TRANSACTION is raised. If the call was made in an improper context, the standard system exception BAD_INV_ORDER 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. The initial transaction timeout value is 300 seconds. Calling set_timeout() with an argument value larger than zero specifies a new timeout value. Calling set_timeout() with a zero argument sets the timeout value back to the default of 300 seconds. After calling set_timeout() , transactions created by subsequent invocations of begin are subject to being rolled back if they do not complete before the specified number of seconds after their creation. 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, see Administering Transactions.
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, the standard system exception TRANSACTION_ROLLEDBACK 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 standard system exception TRANSACTION_ROLLEDBACK 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 standard system exception TRANSACTION_ROLLEDBACK 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 standard system exception INVALID_TRANSACTION 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 standard system exception TRANSACTION_ROLLEDBACK .

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.

Listing 2-4 shows the Control interface, which is defined in the CosTransactions module.

Listing 2-4 Control Interface

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

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

The Control interface is used only in conjunction with the suspend and resume methods.

TransactionalObject Interface

The org.omg.CosTransactions.TransactionalObject interface (in Java) or CosTransactions::TransactionalObject (in C++) 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 "Server Description File" in the CORBA Java Programming Reference or "Implementation Configuration File (ICF)" in the CORBA C++ Programming Reference.

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

Listing 2-5 TransactionalObject Interface

interface TransactionalObject {
};

// This information comes 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.

CORBA Transaction Service API Extensions

This topic describes specific extensions to the CORBAservices Transaction Service API described earlier. The APIs in this topic 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 com.beasys.Tobj module (in Java) or Tobj module (in C++).

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 and is described in "Java Bootstrap Object Programming Reference" in the CORBA Java Programming Reference or in "C++ Bootstrap Object Programming Reference" in the CORBA C++ Programming Reference. Additionally, this interface supports APIs to open and close the Resource Manager.

Listing 2-6 shows the TransactionCurrent interface, which is defined in the Tobj module.

Listing 2-6 TransactionCurrent Interface

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

Table 2-3 describes APIs that are specific to the Resource Manager. For more information about these APIs, see the CORBA Java Programming Reference or the CORBA C++ Programming Reference.

Table 2-3 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 the standard system exception NO_IMPLEMENT .

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 the standard system exception NO_IMPLEMENT .

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 the standard system exception NO_IMPLEMENT .
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 the standard system exception NO_IMPLEMENT .

Notes on Using Transactions in WLE CORBA Applications

Consider the following guidelines when integrating transactions into your WLE CORBA client/server applications:

Nested transactions are not permitted in the WLE system.
You cannot start a new transaction if an existing transaction is already active. (You may start a new transaction if you first suspend the existing one; however, the object that suspends the transaction is the only object that can subsequently resume the transaction.)
The object that starts a transaction is the only entity that can end the transaction. (In a strict sense, the object can be the client application, the TP Framework, or an object managed by the server application.) An object that is invoked within the scope of a transaction may suspend and resume the transaction (and while the transaction is suspended, the object can start and end other transactions). However, you cannot end a transaction in an object unless you began the transaction there.
WLE does not support concurrent transactions. Objects can be involved with only one transaction at one time. An object is involved in a transaction for the duration of the entire transaction, and is available to be involved in a different transaction only after the current transaction is completed.
WLE does not queue requests to objects that are currently involved in a transaction. If a non-transactional client application attempts to invoke an operation on an object that is currently in a transaction, the client application receives the following error message:
Java:
org.omg.CORBA.OBJ_ADAPTER

C++:
CORBA::OBJ_ADAPTER

If a client that is in a transaction attempts to invoke an operation on an object that is currently in a different transaction, the client application receives the following error message:
Java:
org.omg.CORBA.INVALID_TRANSACTION

C++:
CORBA::INVALID_TRANSACTION
For transaction-bound objects, consider doing all state handling in the com.beasys.Tobj_Servant.deactivate_object method (in Java) or Tobj_ServantBase::deactivate_object() operation (in C++). This makes it easier for the object to handle its state properly, because the outcome of the transaction is known at the time that deactivate_object() is invoked.
For method-bound objects that have several operations, but only a few that affect the object's durable state, consider doing the following:
- Assign the optional transaction policy.
- Scope any write operations within a transaction, by making invocations on the TransactionCurrent object.
  If the object is invoked outside a transaction, the object does not incur the overhead of scoping a transaction for reading data. This way, regardless of whether the object is invoked within a transaction, all the object's write operations are handled transactionally.
Transaction rollbacks are asynchronous. Therefore, it is possible for an object to be invoked while its transactional context is still active. If you try to invoke such an object, you receive an exception.
If an object with the always transaction policy is involved in a transaction that is started by the WLE system, and not the client application, note the following:
- If the server application marks the transaction for rollback only and the server throws a CORBA exception, the client application receives the CORBA exception.
- If the server application marks the transaction for rollback only and the server does not throw a CORBA exception, the client application receives the OBJ_ADAPTER exception. In this case, the WLE system automatically rolls back the transaction. However, the client application is completely unaware that a transaction has been scoped in the WLE domain.
If the client application initiates a transaction, and the server application marks the transaction for a rollback, one of the following occurs:
- If the server throws a CORBA exception, the client application receives a CORBA exception.
- If the server does not throw a CORBA exception, the client application receives the TRANSACTION_ROLLEDBACK exception.

Transaction Service in EJB Applications

The WLE EJB Container provides a Transaction Service that supports the two types of transactions in WLE EJB applications:

Container-managed transactions. In container-managed transactions, the WLE EJB Container manages the transaction demarcation. Transaction attributes in the EJB deployment descriptor determine how the WLE EJB Container handles transactions with each method invocation.
Bean-managed transactions. In bean-managed transactions, the EJB manages the transaction demarcation. The EJB makes explicit method invocations on the UserTransaction object to begin, commit, and roll back transactions. For more information about UserTransaction methods, see UserTransaction API.

For an introduction to transaction management in EJB applications, see Transactions in WLE EJB Applications, and Transactions Sample EJB Code.

Transaction Service in RMI Applications

WLE provides a Transaction Service that supports transactions in WLE RMI applications. In RMI applications, the client or server application makes explicit method invocations on the UserTransaction object to begin, commit, and roll back transactions.

For more information about UserTransaction methods, see UserTransaction API. For an introduction to transaction management in RMI applications, see Transactions in WLE RMI Applications, and Transactions Sample RMI Code.

UserTransaction API

This topic includes the following sections:

WLE provides Sun Microsystems, Inc.'s javax.transaction package, which implements the Java Transaction API (JTA) for Java applications. The javax.UserTransaction interface supports transaction management for CORBA Java applications as well as for bean-managed transactions in EJB applications. For more information about the JTA, see Sun Microsystem's Java Transaction API (JTA) Specification (version1.0.1). For a detailed description of the javax.transaction interface, see the package description in the WLE Javadoc.

UserTransaction Methods

Table 2-4 describes the methods in the UserTransaction object.

Table 2-4 UserTransaction Methods

Method Name

Description

begin

Starts a transaction on the current thread.

commit

Commits the transaction associated with the current thread.

getStatus

Returns the transaction status, or STATUS_NO_TRANSACTION if no transaction is associated with the current thread.
One of the following values:

STATUS_ACTIVE
STATUS_COMMITTED
STATUS_COMMITTING
STATUS_MARKED_ROLLBACK
STATUS_NO_TRANSACTION
STATUS_PREPARED
STATUS_PREPARING
STATUS_ROLLEDBACK
STATUS_ROLLING_BACK
STATUS_UNKNOWN

rollback

Rolls back the transaction associated with the current thread.

setRollbackOnly

Marks the transaction associated with the current thread so that the only possible outcome of the transaction is to roll it back.

setTransactionTimeout

Specifies the timeout value for the transactions started by the current thread with the begin method. If an application has not called the begin method, then the Transaction Service uses a default value for the transaction timeout.

Method Name	Description
begin	Starts a transaction on the current thread.
commit	Commits the transaction associated with the current thread.
getStatus	Returns the transaction status, or STATUS_NO_TRANSACTION if no transaction is associated with the current thread. One of the following values: STATUS_ACTIVE STATUS_COMMITTED STATUS_COMMITTING STATUS_MARKED_ROLLBACK STATUS_NO_TRANSACTION STATUS_PREPARED STATUS_PREPARING STATUS_ROLLEDBACK STATUS_ROLLING_BACK STATUS_UNKNOWN
rollback	Rolls back the transaction associated with the current thread.
setRollbackOnly	Marks the transaction associated with the current thread so that the only possible outcome of the transaction is to roll it back.
setTransactionTimeout	Specifies the timeout value for the transactions started by the current thread with the begin method. If an application has not called the begin method, then the Transaction Service uses a default value for the transaction timeout.

Exceptions Thrown by UserTransaction Methods

Table 2-5 describes exceptions thrown by methods of the UserTransaction object.

Table 2-5 Exceptions Thrown by UserTransaction Methods

Exception

Description

HeuristicMixedException

Thrown to indicate that a heuristic decision was made and that some relevant updates have been committed while others have been rolled back.

HeuristicRollbackException

Thrown to indicate that a heuristic decision was made and that some relevant updates have been rolled back.

NotSupportedException

Thrown when the requested operation is not supported (such as a nested transaction).

RollbackException

Thrown when the transaction has been marked for rollback only or the transaction has been rolled back instead of committed.

IllegalStateException

Thrown if the current thread is not associated with a transaction.

SecurityException

Thrown to indicate that the thread is not allowed to commit the transaction.

SystemException

Thrown by the Transaction Manager to indicate that it has encountered an unexpected error condition that prevents future transaction services from proceeding.

Transaction Service

CORBA Transaction Service API

Exceptions

Table 2-1 Exceptions Supported by the Transaction Service

Table 2-2 Current Transaction Methods

Other CORBAservices Object Transaction Service Interfaces

Table 2-3 Resource Manager APIs for the Current Interface

Table 2-4 UserTransaction Methods

Table 2-5 Exceptions Thrown by UserTransaction Methods