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

Integrating Transactions into a WebLogic Enterprise Server Application

This chapter describes how to integrate transactions into a WebLogic Enterprise server application, using the Transactions University sample application as an example. The Transactions sample application encapsulates the process of a student registering for a set of courses. The Transactions sample application does not show all the possible ways to integrate transactions into a WebLogic Enterprise server application, but it does show two models of transactional behavior, showing the impact of transactional behavior on the application in general and on the durable state of objects in particular.

This chapter discusses the following topics:

This chapter also presents a section on user-defined exceptions. The Transactions sample application introduces a user-defined exception, which can be returned to the client application and that potentially causes a client-initiated transaction to be rolled back.

Overview of Transactions in the WebLogic Enterprise System

The WebLogic Enterprise system provides transactions as a means to guarantee that database transactions are completed accurately and that they take on all the ACID properties (atomicity, consistency, isolation, and durability) of a high-performance transaction. That is, you have a requirement to perform multiple write operations on durable storage, and you must be guaranteed that the operations succeed; if any one of the operations fails, the entire set of operations is rolled back.

Transactions typically are appropriate in the situations described in the following list. Each situation encapsulates a transactional model supported by the WebLogic Enterprise system.

The client application needs to make invocations on several different objects, which may involve write operations to one or more databases. If any one invocation is unsuccessful, any state that is written (either in memory or, more typically, to a database) must be rolled back.

For example, consider a travel agent application. The client application needs to arrange for a journey to a distant location; for example, from Strasbourg, France, to Alice Springs, Australia. Such a journey would inevitably require multiple individual flight reservations. The client application works by reserving each individual segment of the journey in sequential order; for example, Strasbourg to Paris, Paris to New York, New York to Los Angeles. However, if any individual flight reservation cannot be made, the client application needs a way to cancel all the flight reservations made so far. For example, if the client application cannot book a flight from Los Angeles to Honolulu on a given date, the client application needs to cancel the flight reservations made up to that point.
The client needs a conversation with an object managed by the server application, and the client needs to make multiple invocations on a specific object instance. The conversation may be characterized by one or more of the following:
Within the scope of a single client invocation on an object, the object performs multiple edits to data in a database. If one of the edits fails, the object needs a mechanism to roll back all the edits. (And in this situation, the individual database edits are not necessarily CORBA invocations.)

For example, consider a banking application. The client invokes the transfer operation on a teller object. The transfer operation requires the teller object to make the following invocations on the bank database:
- Invoking the debit method on one account
- Invoking the credit method on another account
  
  If the credit invocation on the bank database fails, the banking application needs a way to roll back the previous debit invocation.

Designing and Implementing Transactions in a WebLogic Enterprise Server Application

This section explains how to design and implement transactions in a WebLogic Enterprise server application using the Transactions University sample application as an example. This section also describes how the Transactions sample application works, and discusses the design considerations for implementing transactions in it. For additional general information about transactions, see the section "Integrating Transactions in a WebLogic Enterprise Client and Server Application" on page 5-10.

The Transactions sample application uses transactions to encapsulate the task of a student registering for a set of courses. The transactional model used in this application is a combination of the conversational model and the model in which a single invocation makes multiple individual operations on a database, as described in the preceding section.

The Transactions sample application builds on the Security sample application by adding the following capabilities:

Students can submit a list of courses for which they want to register. (Each course is represented by a number.)
For each course in the list, the University server application checks the following:
If the course passes the checks in the preceding list, the University server application registers the student for the course.
If the server application cannot register the student for a course because the course does not exist in the database or because the student is already registered for the course, the server application returns to the client application a list of courses for which the registration process failed. The client application can then choose whether to commit the transaction to register the student for the courses for which the registration process succeeds, or to roll back the entire transaction.
If a course registration fails because the student exceeds the maximum number of credits he or she can take, the server application returns a CORBA exception to the client application that provides a brief message explaining why the registration for the course was not successful. (The server application does not mark the transaction for rollback only.)

The Transactions sample application shows two ways in which a transaction can be rolled back:

Nonfatal. If the registration for a course fails because the course is not in the database, or because the student is already registered for the course, the server application returns the numbers of those courses to the client application. The decision to roll back the transaction lies with the user of the client application (and the Transaction client application code rolls back the transaction automatically in this case).
Fatal. If the registration for a course fails because the student exceeds the maximum number of credits he or she can take, the server application generates a CORBA exception and returns it to the client. The decision to roll back the transaction also lies with the client application.

Thus, the Transactions sample application also shows how to implement user-defined CORBA exceptions. For example, if the student tries to register for a course that would exceed the maximum number of courses for which the student can register, the server application returns the TooManyCredits exception. When the client application receives this exception, the client application rolls back the transaction automatically.

The sections that follow explain:


Activation Policy	Transaction Policy
`process`	`always`

Object Policies Defined for the RegistrarFactory Object

To exclude the RegistrarFactory object from transactions, the ICF file specifies the ignore transaction policy for the Registrar interface. Therefore, in the Transaction sample application, the ICF file specifies the following object policies for the RegistrarFactory interface:


Activation Policy	Transaction Policy
`process`	`ignore`

Using an XA Resource Manager in the Transactions Sample Application

The Transactions sample application uses the Oracle7 Transaction Manager Server (TMS), which handles object state data automatically. Using any XA resource manager imposes specific requirements on how different objects managed by the server application may read and write data to that database, including the following:

Some XA resource managers (for example, Oracle7) require that all database operations be scoped within a transaction. This means that the CourseSynopsisEnumerator object needs to be scoped within a transaction because this object reads from a database.
When a transaction is committed or rolled back, the XA resource manager automatically handles the durable state implied by the commit or rollback. That is, if the transaction is committed, the XA resource manager ensures that all database updates are made permanent. Likewise, if there is a rollback, the XA resource manager automatically restores the database to its state prior to the beginning of the transaction.

This characteristic of XA resource managers actually makes the design problems associated with handling object state data in the event of a rollback much simpler. Transactional objects can always delegate the commit and rollback responsibilities to the XA resource manager, which greatly simplifies the task of implementing a server application.

Configuration Requirements for the Transactions Sample Application

The University sample applications use an Oracle7 transaction manager server (TMS). To use the Oracle7 database, you must include specific Oracle-provided files in the server application build process.

For details about building, configuring, and running the Transactions sample application, see the Guide to the University Sample Applications. That online document also contains the UBBCONFIG files for each sample application and explains the entries in that file.

Integrating Transactions in a WebLogic Enterprise Client and Server Application

The WebLogic Enterprise system supports transactions in the following ways:

The client or the server application can begin and end transactions explicitly by using calls on the TransactionCurrent object. For information about the TransactionCurrent object, see Creating Client Applications.
You can assign transactional policies to an object's interface so that when the object is invoked, the WebLogic Enterprise system can start a transaction automatically for that object, if a transaction has not already been started, and commit or roll back the transaction when the method invocation is complete. You use transactional policies on objects in conjunction with an XA resource manager and database when you want to delegate all the transaction commit and rollback responsibilities to that resource manager.
Objects involved in a transaction can force a transaction to be rolled back. That is, after an object has been invoked within the scope of a transaction, the object can invoke the rollback_only() operation on the TransactionCurrent object to mark the transaction for rollback only. This prevents the current transaction from being committed. An object may need to mark a transaction for rollback if an entity, typically a database, is otherwise at risk of being updated with corrupt or inaccurate data.
Objects involved in a transaction can be kept in memory from the time they are first invoked until the moment when the transaction is ready to be committed or rolled back. In the case of a transaction that is about to be committed, these objects are polled by the WebLogic Enterprise system immediately before the resource managers prepare to commit the transaction. (In this sense, polling means invoking the object's Tobj_ServantBase::deactivate_object() operation and passing a reason value.)

When an object is polled, the object may veto the current transaction by invoking the rollback_only() operation on the TransactionCurrent object. In addition, if the current transaction is to be rolled back, objects have an opportunity to skip any writes to a database. If no object vetos the current transaction, the transaction is committed.

The following sections explain how you can use object activation policies and transaction policies to get the transactional behavior you want in your objects. Note that these policies apply to an interface and, therefore, to all operations on all objects implementing that interface.

Note: If a server application manages an object that you want to be able to participate in a transaction, the Server object for that application must invoke the TP::open_xa_rm() and TP::close_xa_rm() operations. For more information about database connections, see "Opening an XA Resource Manager" on page 5-15.

Making an Object Automatically Transactional

The WebLogic Enterprise system provides the always transactional policy, which you can define on an object's interface to have the WebLogic Enterprise system start a transaction automatically when that object is invoked and a transaction has not already been scoped. When an invocation on that object is completed, the WebLogic Enterprise system commits or rolls back the transaction automatically. Neither the server application, nor the object implementation, needs to invoke the TransactionCurrent object in this situation; the WebLogic Enterprise system automatically invokes the TransactionCurrent object on behalf of the server application.

Assigning the always transactional policy to an object's interface is appropriate when:

The object writes to a database and you want all the database commit or rollback responsibilities delegated to an XA resource manager whenever this object is invoked.
You want to give the client application the opportunity to include the object in a larger transaction that encompasses invocations on multiple objects, and the invocations must all succeed or be rolled back if any one invocation fails.

If you want an object to be automatically transactional, assign the following policies to that object's interface in the Implementation Configuration File (ICF file):


Activation Policy	Transaction Policy
`process`, `method`, or `transaction`	`always`

Note: Database cursors cannot span transactions. The CourseSynopsisEnumerator object in the WebLogic Enterprise University sample applications uses a database cursor to find matching course synopses from the University database. Because database cursors cannot span transactions, the activate_object() operation on the CourseSynopsisEnumerator object reads all matching course synopses into memory. Note that the cursor is managed by an iterator class and is thus not visible to the CourseSynopsisEnumerator object.

Enabling an Object to Participate in a Transaction

If you want an object to be able to be invoked within the scope of a transaction, you can assign the optional transaction policies to that object's interface. The optional transaction policy may be appropriate for an object that does not perform any database write operations, but that you want to have the ability to be invoked during a transaction.

You can use the following policies, when specified in the ICF file for that object's interface, to make an object optionally transactional:


Activation Policy	Transaction Policy
`process`, `method`, or `transaction`	`optional`

If the object does perform database write operations, and you want the object to be able to participate in a transaction, assigning the always transactional policy is generally a better choice. However, if you prefer, you can use the optional policy and encapsulate any write operations within invocations on the TransactionCurrent object. That is, within your operations that write data, scope a transaction around the write statements by invoking the TransactionCurrent object to, respectively, begin and commit or roll back the transaction, if the object is not already scoped within a transaction. This ensures that any database write operations are handled transactionally. This also introduces a performance efficiency: if the object is not invoked within the scope of a transaction, all the database read operations are nontransactional, and therefore more streamlined.

Note: Some XA resource managers used in the WebLogic Enterprise system require that any object participating in a transaction scope their database read operations, in addition to write operations, within a transaction. (However, you can still scope your own transactions.) For example, using the Oracle7 TMS with the WebLogic Enterprise system has this requirement. When choosing the transaction policies to assign to your objects, make sure you are familiar with the requirements of the XA resource manager you are using.

Preventing an Object from Being Invoked While a Transaction Is Scoped

In many cases, it may be critical to exclude an object from a transaction. If such an object is invoked during a transaction, the object returns an exception, which may cause the transaction to be rolled back. The WebLogic Enterprise system provides the never transaction policy, which you can assign to an object's interface to specifically prevent that object from being invoked within the course of a transaction, even if the current transaction is suspended.

This transaction policy is appropriate for objects that write durable state to disk that cannot be rolled back; for example, for an object that writes data to a disk that is not managed by an XA resource manager. Having this capability in your client/server application is crucial if the client application does not or cannot know if some of its invocations are causing a transaction to be scoped. Therefore, if a transaction is scoped, and an object with this policy is invoked, the transaction can be rolled back.

To prevent an object from being invoked while a transaction is scoped, assign the following policies to that object's interface in the ICF file:


Activation Policy	Transaction Policy
`process` or `method`	`never`

Excluding an Object from an Ongoing Transaction

In some cases, it may be appropriate to permit an object to be invoked during the course of a transaction but also keep that object from being a part of the transaction. If such an object is invoked during a transaction, the transaction is automatically suspended. After the invocation on the object is completed, the transaction is automatically resumed. The WebLogic Enterprise system provides the ignore transaction policy for this purpose.

The ignore transaction policy may be appropriate for an object such as a factory that typically does not write data to disk. By excluding the factory from the transaction, the factory can be available to other client invocations during the course of a transaction. In addition, using this policy can introduce an efficiency into your server application because it minimizes the overhead of invoking objects transactionally.

To prevent any transaction from being propagated to an object, assign the following policies to that object's interface in the ICF file:


Activation Policy	Transaction Policy
`process` or `method`	`ignore`

Assigning Policies

For information about how to create an ICF file and specify policies on objects, see the section "Step 4: Define the in-memory behavior of objects." on page 2-14.

Opening an XA Resource Manager

If an object's interface has the always or optional transaction policy, you must invoke the TP::open_xa_rm() operation in the Server::initialize() operation in the Server object. The resource manager is opened using the information provided in the OPENINFO parameter, which is in the GROUPS section of the UBBCONFIG file. Note that the default version of the Server::initialize() operation automatically opens the resource manager.

If you have an object that does not write data to disk and that participates in a transaction -- the object typically has the optional transaction policy -- you still need to include an invocation to the TP::open_xa_rm() operation. In that invocation, specify the NULL resource manager.

Closing an XA Resource Manager

If your Server object's Server::initialize() operation opens an XA resource manager, you must include the following invocation in the Server::release() operation:

TP::close_xa_rm();

Transactions and Object State Management

If you need transactions in your WLE client and server application, you can integrate transactions with object state management in a few different ways. In general, the WebLogic Enterprise system can automatically scope the transaction for the duration of an operation invocation without requiring you to make any changes to your application's logic or the way in which the object writes durable state to disk.

The following sections address some key points regarding transactions an object state management.

Delegating Object State Management to an XA Resource Manager

Using an XA resource manager, such as Oracle7, which is used in the WebLogic Enterprise University sample applications, generally simplifies the design problems associated with handling object state data in the event of a rollback. Transactional objects can always delegate the commit and rollback responsibilities to the XA resource manager, which greatly eases the task of implementing a server application. This means that process- or method-bound objects involved in a transaction can write to a database during transactions, and can depend on the resource manager to undo any data written to the database in the event of a transaction rollback.

Waiting Until Transaction Work is Complete Before Writing to the Database

The transaction activation policy is a good choice for objects that maintain state in memory that you do not want written, or that cannot be written, to disk until the transaction work is complete. When you assign the transaction activation policy to an object, the object:

Is brought into memory when it is first invoked within the scope of a transaction
Remains in memory until the transaction is either committed or rolled back

When the transaction work is complete, the WebLogic Enterprise system invokes each transaction-bound object's Tobj_ServantBase::deactivate_object() operation, passing a reason code that can be either DR_TRANS_COMMITTING or DR_TRANS_ABORT. If the variable is DR_TRANS_COMMITTING, the object can invoke its database write operations. If the variable is DR_TRANS_ABORT, the object skips its write operations.

Assigning the transaction activation policy to an object may be appropriate in the following situations:

You want the object to write its durable state to disk at the time that the transaction work is complete.

This introduces a performance efficiency because it reduces the number of database write operations that may need to be rolled back.
You want to provide the object with the ability to veto a transaction that is about to be committed.

If the WebLogic Enterprise system passes the reason DR_TRANS_COMMITTING, the object can, if necessary, invoke the rollback_only() operation on the TransactionCurrent object. Note that if you do make an invocation to the rollback_only() operation from within the Tobj_ServantBase::deactivate_object() operation, the Tobj_ServantBase::deactivate_object() operation is not invoked again.
You have an object that is likely to be invoked multiple times during the course of a single transaction, and you want to avoid the overhead of continually activating and deactivating the object during that transaction.

To give an object the ability to wait until the transaction is committing before writing to a database, assign the following policies to that object's interface in the ICF file:


Activation Policy	Transaction Policy
`transaction`	`always` or `optional`

Note: Transaction-bound objects cannot start a transaction or invoke other objects from inside the Tobj_ServantBase::deactivate_object() operation. The only valid invocations transaction-bound objects can make inside the Tobj_ServantBase::deactivate_object() operation are write operations to the database. Also, if you have an object that is involved in a transaction, the Server object that manages that object must include invocations to open and close, respectively, the XA resource manager, even if the object does not write any data to disk. (If you have a transactional object that does not write data to disk, you specify the NULL resource manager.) For more information about opening and closing an XA resource manager, see the sections "Opening an XA Resource Manager" on page 5-15 and "Closing an XA Resource Manager" on page 5-15.

Notes on Using Transactions in the WebLogic Enterprise System

Note the following about integrating transactions into your WebLogic Enterprise client/server applications:

The following transactions are not permitted in the WebLogic Enterprise system:
- Nested transactions
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.)
- Recursive transactions
A transactional object cannot call a second object, which in turn calls the first object.
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.
Objects can be involved with only one transaction at one time. The WebLogic Enterprise system does not support concurrent transactions.
The WebLogic Enterprise system does not queue requests to objects that are currently involved in a transaction. If a nontransactional client application attempts to invoke an operation on an object that is currently in a transaction, the client application receives the following error message:
```
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:
```
CORBA::INVALID_TRANSACTION
```
For transaction-bound objects, you might consider doing all state handling in the Tobj_ServantBase::deactivate_object() operation. This makes it easier for the object to handle its state properly, since the outcome of the transaction is known at the time that the Tobj_ServantBase::deactivate_object() operation is invoked.
For method-bound objects that have several operations, but only a few that affect the object's durable state, you may want to consider 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 WebLogic Enterprise system, and not the client application, note the following:

If an exception is raised inside an operation on that object, the client application receives an OBJ_ADAPTER exception. In this situation, the WebLogic Enterprise system automatically rolls back the transaction. However, the client application is completely unaware that a transaction has been scoped in the WebLogic Enterprise domain.
If the client application initiates a transaction, and the server application marks the transaction for a rollback and returns a CORBA exception, the client application receives only a transaction rollback exception but not the CORBA exception.

In the WLE version 4.2 software, no workaround exists for this situation. We recommend that applications perform as much data validation as possible before starting a transaction.

User-Defined Exceptions

The Transactions sample application includes an instance of a user-defined exception, TooManyCredits. This exception is thrown by the server application when the client application tries to register a student for a course, and the student has exceeded the maximum number of courses for which he or she can register. When the client application catches this exception, the client application rolls back the transaction that registers a student for a course. This section explains how you can define and implement user-defined exceptions in your WebLogic Enterprise client/server application, using the TooManyCredits exception as an example.

Including a user-defined exception in a WebLogic Enterprise client/server application involves the following steps:

In your OMG IDL file, define the exception and specify the operations that can use it.
In the implementation file, include code that throws the exception.
In the client application source file, include code that catches and handles the exception.

The sections that follow explain and give examples of the first two steps.

Defining the Exception

In the OMG IDL file for your client/server application:

Define the exception and define the data sent with the exception. For example, the TooManyCredits exception is defined to pass a short integer representing the maximum number of credits for which a student can register. Therefore, the definition for the TooManyCredits exception contains the following OMG IDL statements:
```
exception TooManyCredits
{
    unsigned short maximum_credits;
};
```
In the definition of the operations that throw the exception, include the exception. The following example shows the OMG IDL statements for the register_for_courses() operation on the Registrar interface:
```
NotRegisteredList register_for_courses(
    in StudentId        student,
    in CourseNumberList courses
) raises (
    TooManyCredits
);
```

Throwing the Exception

In the implementation of the operation that uses the exception, write the code that throws the exception, as in the following example.

if ( ... ) {
    UniversityZ::TooManyCredits e;
    e.maximum_credits = 18;
    throw e;

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 01, 1999.