Transactions in CORBA Client Applications

This topic includes the following sections:

•	Overview of Oracle Tuxedo CORBA Transactions

•	Summary of the Development Process for Transactions

•	Step 1: Using the Bootstrap Object to Obtain the TransactionCurrent Object

•	JStep 2: Using the TransactionCurrent Methods

This topic describes how to use transactions in CORBA C++ client applications for the Oracle Tuxedo CORBA software. Before you begin, you should read Chapter 1, “Introducing Transactions.”

Notes:

The Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported. All Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB text references, associated code samples, should only be used to help implement/run third party Java ORB libraries, and for programmer reference only.

Technical support for third party CORBA Java ORBs should be provided by their respective vendors. Oracle Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs.

For an example of how transactions are implemented in working client applications, see the The Transaction Sample Application in the Oracle Tuxedo online documentation. For an overview of the TransactionCurrent object, see “Client Application Development Concepts” in Creating CORBA Client Applications.

Overview of Oracle Tuxedo CORBA Transactions

Client applications use transaction processing to ensure that data remains correct, consistent, and persistent. The transactions in the Oracle Tuxedo software allow client applications to begin and terminate transactions and to get the status of transactions. The Oracle Tuxedo software uses transactions as defined in the CORBA services Object Transaction Service, with extensions for ease of use.

Transactions are defined on interfaces. The application designer decides which interfaces within an Oracle Tuxedo client/server application will handle transactions. Transaction policies are defined in the Implementation Configuration File (ICF) for server applications. Generally, the ICF file for the available interfaces is provided to the client programmer by the application designer.

Summary of the Development Process for Transactions

To add transactions to a client application, complete the following steps:

•	Step 1: Using the Bootstrap Object to Obtain the TransactionCurrent Object

•	JStep 2: Using the TransactionCurrent Methods

The rest of this topic describes these steps using portions of the client applications in the Transactions University sample application. For information about the Transactions University sample application, see The Transactions Sample Application in the Oracle Tuxedo online documentation.

The Transactions University sample application is located in the following directory on the Oracle Tuxedo software kit:

•	For Microsoft Windows systems: drive:\tuxdir\samples\corba\university\transactions

•	For UNIX systems: drive:/tuxdir/samples/corba/university/transactions

Step 1: Using the Bootstrap Object to Obtain the TransactionCurrent Object

If you are using the Oracle Tuxedo CORBA client software, you should use the Bootstrap object to obtain an object reference to the TransactionCurrent object for the specified Oracle Tuxedo domain. For more information about the TransactionCurrent object, see “Client Application Development Concepts” in Creating CORBA Client Applications.

Note:

If you are using a third-party client ORB, you should the CORBA Interoperable Naming Service (INS) CORBA::ORB::resolve_initial_references operation to obtain an object reference to the FactoryFinder object for the specified Oracle Tuxedo domain. For information on how to use INS to get initial object references for transaction clients, see “CORBA Bootstrapping Programming Reference” in the CORBA Programming Reference.

The following C++ examples illustrate how the Bootstrap object is used to return the TransactionCurrent object.

C++ Example

CORBA::Object_var var_transaction_current_oref =
Bootstrap.resolve_initial_references(“TransactionCurrent”);
CosTransactions::Current_var transaction_current_oref=
CosTransactions::Current::_narrow(
var_transaction_current_oref.in());

JStep 2: Using the TransactionCurrent Methods

The TransactionCurrent object has methods that allow a client application to manage transactions. These methods can be used to begin and end transactions and to obtain information about the current transaction.

Table 4‑1 describes the methods in the TransactionCurrent object.

 

Table 4‑1 Methods in the TransactionCurrent Object 

Method	Description
begin	Creates a new transaction. Future operations take place within the scope of this transaction. When a client application begins a transaction, the default transaction timeout is 300 seconds. You can change this default, using the set_timeout method.
commit	Ends the transaction successfully. Indicates that all operations on this client application have completed successfully.
rollback	Forces the transaction to roll back.
rollback_only	Marks the transaction so that the only possible action is to roll back. Generally, this method is used only in server applications.
suspend	Suspends participation in the current transaction. This method returns an object that identifies the transaction and allows the client application to resume the transaction later.
resume	Resumes participation in the specified transaction.
get_status	Returns the status of a transaction with a client application.
get_transaction_name	Returns a printable string describing the transaction.
set_timeout	Modifies the timeout period associated with transactions. The default transaction timeout value is 300 seconds. If a transaction is automatically started instead of explicitly started with the begin method, the timeout value is determined by the value of the TRANTIME parameter in the UBBCONFIG file. For more information about setting the TRANTIME parameter, see Chapter , “Administering Transactions.”
get_control	Returns a control object that represents the transaction.

A basic transaction works in the following way:

1.	A client application begins a transaction using the Tobj::TransactionCurrent::begin method. This method does not return a value.

2.	The operations on the CORBA interface execute within the scope of a transaction. If a call to any of these operations raises an exception (either explicitly or as a result of a communications failure), the exception can be caught and the transaction can be rolled back.

3.	Use the Tobj::TransactionCurrent::commit method to commit the current transaction. This method ends the transaction and starts the processing of the operation. The transaction is committed only if all of the participants in the transaction agree to commit.

The association between the transaction and the client application ends when the client application calls the Tobj::TransactionCurrent:commit method or the Tobj::TransactionCurrent:rollback method.The following C++ examples illustrate using a transaction to encapsulate the operation of a student registering for a class.

C++ Example

//Begin the transaction
transaction_current_oref->begin();
try {
//Perform the operation inside the transaction
   pointer_Registar_ref->register_for_courses(student_id, course_number_list);
    ...
//If operation executes with no errors, commit the transaction:
     CORBA::Boolean report_heuristics = CORBA_TRUE;
     transaction_current_ref->commit(report_heuristics);
}
catch (CORBA::Exception &) {
//If the operation has problems executing, rollback the
//transaction. Then throw the original exception again.
//If the rollback fails, ignore the exception and throw the
//original exception again.
try {
     transaction_current_ref->rollback();
}
catch (CORBA::Exception &) {
            TP::userlog("rollback failed");

throw;
}