![]() |
![]() |
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 |
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.
Overview of Transactions in the WebLogic Enterprise System
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 WebLogic Enterprise system supports two transaction API models:
Integrating Transactions in a WebLogic Enterprise Client and Server Application
org.omg.CosTransactions.Current.
In this document, we refer generically to these mappings as the TransactionCurrent object. For specifics about The WebLogic Enterprise system supports transactions in the following ways:
org.omg.CosTransactions.Current
and javax.transaction.UserTransaction
, see the Java API Reference and the Java Programming Reference.
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 The WebLogic Enterprise system provides the Assigning the com.beasys.Tobj.TP.open_xa_rm
and com.beasys.Tobj.TP.close_xa_rm
methods. For more information about database connections, see the section "Opening an XA Resource Manager" on page 3-9.
Making an Object Automatically Transactional
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.
always
transactional policy to an object's interface is appropriate when:
If you want an object to be automatically transactional, assign the following policies to that object's interface in the XML-based Server Description File:
Note:
Database cursors cannot span transactions. For an example, see Creating C++ Server Applications.
If you want an object to be able to be invoked within the scope of a transaction, you can assign the You can use the following policies, when they are specified in the XML-based Server Description File for that object's interface, to make an object optionally transactional:
When the transaction policy is If the object does perform database write operations, and you want the object to be able to participate in a transaction, assigning the
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.
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 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 XML-based Server Description File:
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 The To prevent any transaction from being propagated to an object, assign the following policies to that object's interface in the Server Description File:
For information about how to create a Server Description File and specify policies on objects, see the section "Step 5: Define the object activation and transaction policies." on page 2-13.
The XA Bankapp sample application in the
Activation Policy
Transaction Policy
process
, method
, or transaction
always
Enabling an Object to Participate in a Transaction
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.
Activation Policy
Transaction Policy
process
, method
, or transaction
optional
optional
, if the AUTOTRAN
parameter is enabled in the application's UBBCONFIG
file, the implementation is transactional. Servers containing transactional objects must be configured within a group associated with an XA-compliant resource manager.
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.
Preventing an Object from Being Invoked While a Transaction Is Scoped
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.
Activation Policy
Transaction Policy
process
or method
never
Excluding an Object from an Ongoing Transaction
ignore
transaction policy for this purpose.
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.
Activation Policy
Transaction Policy
process
or method
ignore
Assigning Policies
Using an XA Resource Manager
drive:\M3dir\samples\corba\bankapp_java\XA
directory uses the Oracle7 Transaction Manager Server (TMS) as an example of a relational database management service (RDBMS). TMS 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:
DBaccess
object need to be scoped within a transaction because this object reads from a database. The transaction can be started either by the client or by the WebLogic Enterprise system.
If an object's interface has the In the The resource manager is opened using the information provided in the
Note:
Using a resource manager (except the NULL resource manager) disables the multithreading feature. If an XA-enabled version of JavaServer is built using If you have an object that participates in a transaction but does not actually perform database operations (the object typically has the If your Server object's If you need transactions in your WebLogic Enterprise 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 and object state management.
Using an XA resource manager, such as Oracle7, 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.
The Opening an XA Resource Manager
always
or optional
transaction policy, you must invoke the com.beasys.Tobj.TP.open_xa_rm
method in the com.beasys.Tobj.Server.initialize
method in the Server object that supports this object. You must build a special version of the JavaServer by using the buildXAJS
command, if your object performs database operations.
SERVERS
section of the application's UBBCONFIG
file, you must use the JavaServerXA
element in place of JavaServer
to associate the XA resource manager with a specified server group. (JavaServer
uses the null RM.)
OPENINFO
parameter, which is in the GROUPS
section of the UBBCONFIG
file. Note that the default version of the com.beasys.Tobj.Server.initialize
method automatically opens the resource manager.
buildXAJS
, the server supports only the single-threaded mode; in this case, the WebLogic Enterprise system ignores the -M number
command line argument for multithreading (if specified).
optional
transaction policy), you still need to include an invocation to the com.beasys.Tobj.TP.open_xa_rm
method.
Closing an XA Resource Manager
com.beasys.Tobj.Server.initialize
method opens an XA resource manager, you must include the following invocation in the com.beasys.Tobj.Server.release
method:
com.beasys.Tobj.TP.
close_xa_rm();Transactions and Object State Management
Delegating Object State Management to an XA Resource Manager
Waiting Until Transaction Work Is Complete Before Writing to the Database
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:
When the transaction work is complete, the WebLogic Enterprise system invokes each transaction-bound object's Assigning the com.beasys.Tobj_Servant.deactivate_object
method, passing a reason
code that can be either DR_TRANS_COMMITTING
or DR_TRANS_ABORTED
. If the variable is DR_TRANS_COMMITTING
, the object can invoke its database write operations. If the variable is DR_TRANS_ABORTED
, the object skips its write operations.
transaction
activation policy to an object may be appropriate in the following situations:
This introduces a performance efficiency because it reduces the number of database write operations that may need to be rolled back.
If the WebLogic Enterprise system passes the reason DR_TRANS_COMMITTING
, the object can, if necessary, invoke the rollback_only
method on the TransactionCurrent object. Note that if you do make an invocation to the rollback_only
method from within the com.beasys.Tobj_Servant.deactivate_object
method, the deactivate_object
method is not invoked again.
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 XML-based Server Description File:
Note:
Transaction-bound objects cannot start a transaction or invoke other objects from inside the
Activation Policy
Transaction Policy
transaction
always
or optional
com.beasys.Tobj_Servant.deactivate_object
method. The only valid invocations transaction-bound objects can make inside the deactivate_object
method are write operations to the database.
Note the following about integrating transactions into your WebLogic Enterprise client/server applications:
Notes on Using Transactions in the WebLogic Enterprise 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.)
A transactional object cannot call a second object, which in turn calls the first object.
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:
org.omg.CORBA.OBJ_ADAPTER
org.omg.CORBA.INVALID_TRANSACTION
com.beasys.Tobj_Servant.deactivate_object
method. 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 com.beasys.Tobj_Servant.deactivate_object
method is invoked.
optional
transaction policy.
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.