Using CORBA Transactions

Introducing Transactions

This topic includes the following sections:

Note: The BEA Tuxedo CORBA Java client and BEA Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported in Tuxedo 9.0.

All BEA Tuxedo CORBA Java client and BEA Tuxedo CORBA Java client ORB text references, associated code samples, etc. 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. BEA Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs.

Overview of Transactions in BEA Tuxedo CORBA Applications

This topic includes the following sections:

ACID Properties of Transactions

One of the most fundamental features of the BEA Tuxedo system is transaction management. Transactions are 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. BEA Tuxedo protects the integrity of your transactions by providing a complete infrastructure for ensuring that database updates are done accurately, even across a variety of resource managers (RMs). If any one of the operations fails, the entire set of operations is rolled back.

Resource Manager

A Resource Manager (RM) is a data repository, such as a database management system or the BEA Tuxedo system's Application Queuing Manager, with tools for accessing the data. The BEA Tuxedo system uses one or more RMs to maintain the state of an application. For example, bank records in which account balances are maintained are kept in an RM. When the state of the application changes through a service that allows a customer to withdraw money from an account, the new balance in the account is recorded in the appropriate RM.

The BEA Tuxedo system helps you manage transactions involving resource managers that support the XA interface. To coordinate all the operations performed and all the modules affected by a transaction, the BEA Tuxedo system plays the role of the Transaction Manager (TM).

The TM coordinates global transactions involving system-wide resources. Local resource managers (RMs) are responsible for individual resources. The Transaction Manager Server (TMS) begins, commits, and aborts transactions involving multiple resources. The application code uses the normal embedded SQL interface to the RM to perform reads and updates. The TMS uses the XA interface to the RM to perform the work of a global transaction.

Supported Programming Model

BEA Tuxedo supports the Object Management Group Common Object Request Broker (CORBA) in C++, in compliance with the The Common Object Request Broker: Architecture and Specification, Revision 2.4.2, January 2001.

Supported API Model

BEA Tuxedo supports the CORBA services Object Transaction Service (OTS). BEA Tuxedo provides a C++ interface to the OTS and is based on the OTS. The OTS is accessed through the org.omg.CosTransactions.Current environmental object. For information about using the TransactionCurrent environmental object, see the "CORBA Bootstrapping Programming Reference" in the CORBA Programming Reference.

Note: BEA Tuxedo also supports use of the CORBA Interoperable Naming Service (INS) bootstrapping mechanism. For information on INS, see the "CORBA Bootstrapping Programming Reference" in the CORBA Programming Reference.

Support for Business Transactions

OTS provides the following support for your business transactions:

Creates a global transaction identifier when a client application initiates a transaction.
Works with the BEA Tuxedo infrastructure to track objects that are involved in a transaction and, therefore, need to be coordinated when the transaction is ready to commit.
Notifies the resource managers—which are, most often, databases—when they are accessed on behalf of a transaction. Resource managers then lock the accessed records until the end of the transaction.
Orchestrates the two-phase commit when the transaction completes, which ensures that all the participants in the transaction commit their updates simultaneously. It coordinates the commit with any databases that are being updated using Open Group's XA protocol. Almost all relational databases support this standard.
Executes the rollback procedure when the transaction must be stopped.
Executes a recovery procedure when failures occur. It determines which transactions were active in the machine at the time of the crash, and then determines whether the transaction should be rolled back or committed.

Distributed Transactions and the Two-Phase Commit Protocol

BEA Tuxedo CORBA supports distributed transactions and the two-phase commit protocol for enterprise applications. A distributed transaction is a transaction that updates multiple resource managers (such as databases) in a coordinated manner. The two-phase commit protocol (2PC) is a method of coordinating a single transaction across one or more resource managers. It guarantees data integrity by ensuring that transactional updates are committed in all of the participating databases, or are fully rolled back out of all the databases, reverting to the state prior to the start of the transaction.

When to Use Transactions

Transactions are appropriate in the situations described in the following list. Each situation describes a transaction model supported by BEA Tuxedo CORBA.

The client application needs to make invocations on several 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 up to that point.

The client application needs a conversation with an object managed by the server application, and the client application needs to make multiple invocations on a specific object instance. The conversation may be characterized by one or more of the following:

Data is cached in memory or written to a database during or after each successive invocation.
Data is written to a database at the end of the conversation.
The client application needs the object to maintain an in-memory context between each invocation; that is, each successive invocation uses the data that is being maintained in memory across the conversation.
At the end of the conversation, the client application needs the ability to cancel all database write operations that may have occurred during or at the end of the conversation.

For example, consider an Internet-based online shopping cart application. Users of the client application browse through an online catalog and make multiple purchase selections. When the users are done choosing all the items they want to buy, they proceed to check out and enter their credit card information to make the purchase. If the credit card check fails, the shopping application needs a way to cancel all the pending purchase selections in the shopping cart, or roll back any purchase transactions made during the conversation.

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. (In this situation, the individual database edits are not necessarily CORBA.)

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.

How to Use Transactions in BEA Tuxedo CORBA Applications

Figure 1-1 illustrates transactions in a BEA Tuxedo CORBA application.

Figure 1-1 Transactions in a BEA Tuxedo CORBA Application

Transactions in a BEA Tuxedo CORBA Application

The way you use transactions differs depending on whether you use the BEA bootstrapping mechanism or the Interoperable Naming Service (INS) bootstrapping mechanism.

Note: You should use the BEA bootstrapping mechanism if you are using BEA Tuxedo CORBA client software. You should use the INS bootstrapping mechanism if you are using a third-party client.

How to Use Transactions When Using the BEA Bootstrapping Mechanism

When the BEA proprietary Bootstrapping mechanism is used, you use a basic transaction in the following way:

The client application uses the Bootstrap object to return an object reference to the TransactionCurrent object for the BEA Tuxedo domain.

A client application begins a transaction using the Tobj::TransactionCurrent::begin() operation, and issues a request to the CORBA interface through the TP Framework. All 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 communication failure), the exception can be caught.
If all the changes that need to occur have taken place successfully, and the state of the database (or objects) is consistent, then the transaction should be committed; otherwise, the transaction should be rolled back.
The client application commits the current transaction using the Tobj::TransactionCurrent::commit() operation. This operation 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 Tobj::TransactionCurrent:commit() operation causes the TP Framework to call the transaction manager to complete the transaction.

The transaction manager is responsible for coordinating with the resource managers to update the database.

How to Use Transactions When Using the INS Bootstrapping Mechanism

When you use CORBA services Interoperable Naming Service (INS) bootstrapping mechanism is used, you use a basic transaction in the following way:

The client application uses the ORB::resolve_initial_references() operation to get a FactoryFinder object for the BEA Tuxedo domain.

The client application uses the FactoryFinder to get a TransactionFactory.

Note: The TransactionFactory returns objects that adhere to the standard CORBA Services Transaction Service interfaces instead of the BEA delegated interfaces. This means that a third-party client can use their ORB's resolve_initial_references() function to get the TransactionFactory from a BEA Tuxedo CORBA server and use stubs generated from standard OMG IDL to act on the instances returned.

The client application then uses the create() operation on the TransactionFactory to begin a transaction and issues a request to the CORBA interface through the TP Framework.

From the Control object returned from the create() operation, the client application uses the get_terminator() operation to get the transaction Terminator interface.

The client application then uses the commit() or rollback() operation on the Terminator interface to end or abort the transaction. The commit() operation causes the TP Framework to call the transaction manager to complete the transaction.

The transaction manager is responsible for coordinating with the resource managers to update the database.

Note: All 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 communication failure), the exception can be caught.
If all the changes that need to occur have taken place successfully, and the state of the database (or objects) is consistent, then the transaction should be committed; otherwise, the transaction should be rolled back.
The client application commits the current transaction using the Terminator::commit() operation. This operation 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.

Note: For more information on INS, see the "CORBA Bootstrapping Programming Reference" in the CORBA Programming Reference.

Writing a Transactions Sample Application

This topic includes the following sections:

Workflow for the Transactions Sample Application

In the Transactions sample CORBA application, the operation of registering for courses is executed within the scope of a transaction. The transaction model used in the Transactions sample application is a combination of the conversational model and the model in which a single client invocation makes multiple individual operations on a database.

The Transactions sample application works in the following way:

Students submit a list of courses for which they want to be registered.

For each course in the list, the server application checks whether:

The course is in the database.
The student is already registered for a course.
The student exceeds the maximum number of credits the student can take.

One of the following occurs:

If the course meets all the criteria, the server application registers the student for the course.
If the course is not in the database or if the student is already registered for the course, the server application adds the course to a list of courses for which the student could not be registered. After processing all the registration requests, the server application returns the list of courses for which registration failed. The client application can then choose to either commit the transaction (thereby registering the student for the courses for which registration request succeeded) or to roll back the transaction (thus, not registering the student for any of the courses).
If the student exceeds the maximum number of credits the student can take, the server application returns a TooManyCredits user exception to the client application. The client application provides a brief message explaining that the request was rejected. The client application then rolls back the transaction.

Figure 1-2 illustrates how the Transactions sample application works.

Figure 1-2 Transactions Sample Application

Transactions Sample Application

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.

Note: For information about how transactions are implemented in BEA Tuxedo CORBA applications, see the Transactions Sample in the BEA Tuxedo online documentation.

Development Steps

This topic describes the following development steps for writing a BEA Tuxedo application that contains transaction processing code:

The Transactions sample application is used to demonstrate these development steps. The source files for the Transactions sample application are located in the \samples\corba\university directory of the BEA Tuxedo software. For information about building and running the Transactions sample application, see the Transactions Sample in the BEA Tuxedo online documentation.

Step 1: Writing the OMG IDL

You need to specify interfaces involved in transactions in Object Management Group (OMG) Interface Definition Language (IDL) just as you would any other CORBA interface. You must also specify any user exceptions that might occur from using the interface.

For the Transactions sample application, you would define in OMG IDL the Registrar interface and the register_for_courses() operation. The register_for_courses() operation has a parameter, NotRegisteredList, which returns to the client application the list of courses for which registration failed. If the value of NotRegisteredList is empty, then the client application commits the transaction. You also need to define the TooManyCredits user exception.

Listing 1-1 includes the OMG IDL for the Transactions sample application.

Listing 1-1 OMG IDL for the Transactions Sample Application

#pragma prefix "beasys.com"
module UniversityT

{
	typedef unsigned long CourseNumber;
	typedef sequence<CourseNumber> CourseNumberList;

	struct CourseSynopsis
	{
		CourseNumber   course_number;
		string         title;
	};
	typedef sequence<CourseSynopsis> CourseSynopsisList;

	interface CourseSynopsisEnumerator
	{
	//Returns a list of length 0 if there are no more entries
	CourseSynopsisList get_next_n(
		in  unsigned long number_to_get, // 0 = return all
		out unsigned long number_remaining
	);

	void destroy();
	};
	typedef unsigned short Days;
	const Days MONDAY    =  1;
	const Days TUESDAY   =  2;
	const Days WEDNESDAY =  4;
	const Days THURSDAY  =  8;
	const Days FRIDAY    = 16;
}
//Classes restricted to same time block on all scheduled days, 
//starting on the hour

struct ClassSchedule
{
	Days           class_days; // bitmask of days
	unsigned short start_hour; // whole hours in military time
	unsigned short duration;   // minutes
};

struct CourseDetails
{
	CourseNumber   course_number;
	double         cost;
	unsigned short number_of_credits;
	ClassSchedule  class_schedule;
	unsigned short number_of_seats;
	string         title;
	string         professor;
	string         description;
};
	typedef sequence<CourseDetails> CourseDetailsList;
	typedef unsigned long StudentId;

struct StudentDetails
{
	StudentId         student_id;
	string            name;
	CourseDetailsList registered_courses;
};

enum NotRegisteredReason
{
	AlreadyRegistered,
	NoSuchCourse
};

struct NotRegistered
{
	CourseNumber        course_number;
	NotRegisteredReason not_registered_reason;
};
	typedef sequence<NotRegistered> NotRegisteredList;

exception TooManyCredits
{
	unsigned short maximum_credits;
};

//The Registrar interface is the main interface that allows
//students to access the database.
interface Registrar
{
	CourseSynopsisList
	get_courses_synopsis(
		in string                    search_criteria,
	 	in unsigned long             number_to_get,
	 	out unsigned long            number_remaining,
		out CourseSynopsisEnumerator rest
);

   	CourseDetailsList get_courses_details(in CourseNumberList
	 courses);
	StudentDetails get_student_details(in StudentId student);
	NotRegisteredList register_for_courses(
		in StudentId        student,
		in CourseNumberList courses
	) raises (
		TooManyCredits
	);

};

// The RegistrarFactory interface finds Registrar interfaces.

interface RegistrarFactory
{
	Registrar find_registrar(
	);
};

Step 2: Defining Transaction Policies for the Interfaces

Transaction policies are used on a per-interface basis. During design, it is decided which interfaces within a BEA Tuxedo application will handle transactions. Table 1-1 describes the CORBA transaction policies.

Table 1-1 CORBA Transaction Policies

Transaction Policy	Description
`always`	The interface must always be part of a transaction. If the interface is not part of a transaction, a transaction will be automatically started by the TP Framework.
`ignore`	The interface is not transactional. However, requests made to this interface within a scope of a transaction are allowed. The AUTOTRAN parameter, specified in the UBBCONFIG file for this interface, is ignored.
`never`	The interface is not transactional. Objects created for this interface can never be involved in a transaction. The BEA Tuxedo system generates an exception (`INVALID_TRANSACTION`) if an interface with this policy is involved in a transaction.
`optional`	The interface may be transactional. Objects can be involved in a transaction if the request is transactional. This transaction policy is the default.

During development, you decide which interfaces will execute in a transaction by assigning transaction policies. You specify transaction policies in the Implementation Configuration File (ICF). A template ICF file is created by the genicf command. For more information about the ICFs, see "Implementation Configuration File (ICF)" in the CORBA Programming Reference.

In the Transactions sample application, the transaction policy of the Registrar interface is set to always.

Step 3: Writing the Server Application

When using transactions in server applications, you need to write methods that implement the interface's operations. In the Transactions sample application, you would write a method implementation for the register_for_courses() operation.

If your BEA Tuxedo application uses a database, you need to include in the server application code that opens and closes an XA resource manager. These operations are included in the Server::initialize() and Server::release() operations of the Server object. Listing 1-2 shows the portion of the code for the Server object in the Transactions sample application that opens and closes the XA resource manager.

Note: For a complete example of a CORBA server application that implements transactions, see the Transactions Sample in the BEA Tuxedo online documentation.

Listing 1-2 C++ Server Object in Transactions Sample Application

CORBA::Boolean Server::initialize(int argc, char* argv[])
{
	TRACE_METHOD("Server::initialize");
	try {
		open_database();
		begin_transactional();
		register_fact();
		return CORBA_TRUE;
}
	catch (CORBA::Exception& e) {
		LOG("CORBA exception : " <<e);
	}
	catch (SamplesDBException& e) {
		LOG("Can't connect to database");
	}
	catch (...) {
		LOG("Unexpected database error : " <<e);
	}
	catch (...) {
		LOG("Unexpected exception");
	}
	cleanup();
	return CORBA_FALSE;
}

void Server::release()
{
	TRACE_METHOD("Server::release");
	cleanup();
}

static void cleanup()
{
	unregister_factory();
	end_transactional();
	close_database();
}
//Utilities to manage transaction resource manager

CORBA::Boolean s_became_transactional = CORBA_FALSE;
static void begin_transactional()
{
	TP::open_xa_rm();
	s_became_transactional = CORBA_TRUE;
}
static void end_transactional()
{
	if(!s_became_transactional){
	return//cleanup not necessary
}
try {
	TP::close_xa_rm ();
}
	catch (CORBA::Exception& e) {
	       LOG("CORBA Exception : " << e);
	}
	catch (...) {
	       LOG("unexpected exception");
 	}

	s_became_transactional = CORBA_FALSE;
}

Step 4: Writing the Client Application

The client application needs code that performs the following tasks:

Obtains a reference to the TransactionCurrent object from the Bootstrap object.

Begins a transaction by invoking the Tobj::TransactionCurrent::begin() operation on the TransactionCurrent object.

Invokes operations on the object. In the Transactions sample application, the client application invokes the register_for_courses() operation on the Registrar object, passing a list of courses.

Listing 1-3 shows the portion of the CORBA C++ client applications in the Transactions sample application that illustrates the development steps for transactions.

Note: The sample code shown in Listing 1-3 illustrates how to use the BEA bootstrapping mechanism. For information on how to use the INS bootstrapping mechanism, see the "CORBA Bootstrapping Programming Reference" in the CORBA Programming Reference.

Listing 1-3 Transactions Code for CORBA C++ Client Applications

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());
//Begin the transaction
var_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;
     var_transaction_current_ref->commit(report_heuristics);
    }
catch (...) {
//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 {
     var_transaction_current_ref->rollback();
    }
catch (...) {
            TP::userlog("rollback failed");
            }
throw;
}

Step 5: Creating a Configuration File

You need to add the following information to the configuration file for a transactional BEA Tuxedo application:

In the GROUPS section:

In the OPENINFO parameter, include the information needed to open the resource manager for the database. You obtain this information from the product documentation for your database. Note that the default version of the com.beasys.Tobj.Server.initialize method automatically opens the resource manager.
In the CLOSEINFO parameter, include the information needed to close the resource manager for the database. By default, the CLOSEINFO parameter is empty.
Specify the TMSNAME and TMSCOUNT parameters to associate the XA resource manager with a specified server group.

In the SERVERS section, define a server group that includes both the server application that includes the interface and the server application that manages the database. This server group needs to be specified as transactional.
Include the pathname to the transaction log (TLOG) in the TLOGDEVICE parameter. For more information about the transaction log, see Administering Transactions.

Listing 1-4 includes the portions of the configuration file that define this information for the Transactions sample application.

Listing 1-4 Configuration File for Transactions Sample Application

*RESOURCES
	IPCKEY    55432
	DOMAINID  university
	MASTER    SITE1
	MODEL     SHM
	LDBAL     N
	SECURITY  APP_PW

*MACHINES
	BLOTTO
	LMID = SITE1
	APPDIR = C:\TRANSACTION_SAMPLE
	TUXCONFIG=C:\TRANSACTION_SAMPLE\tuxconfig
	TLOGDEVICE=C:\APP_DIR\TLOG
	TLOGNAME=TLOG
	TUXDIR="C:\tuxdir"
	MAXWSCLIENTS=10

*GROUPS
	SYS_GRP
	  LMID      = SITE1
	  GRPNO     = 1
	ORA_GRP
	  LMID      = SITE1
	  GRPNO     = 2

	OPENINFO  = "ORACLE_XA:Oracle_XA+SqlNet=ORCL+Acc=P
	/scott/tiger+SesTm=100+LogDir=.+MaxCur=5"
	CLOSEINFO = ""
	TMSNAME   = "TMS_ORA"
	TMSCOUNT  = 2

*SERVERS
	DEFAULT:
	RESTART = Y
	MAXGEN  = 5

	TMSYSEVT
	  SRVGRP  = SYS_GRP
	  SRVID   = 1

	TMFFNAME
	  SRVGRP  = SYS_GRP
	  SRVID   = 2
	  CLOPT   = "-A -- -N -M"

	TMFFNAME
	  SRVGRP  = SYS_GRP
	  SRVID   = 3
	  CLOPT   = "-A -- -N"

	TMFFNAME
	  SRVGRP  = SYS_GRP
	  SRVID   = 4
	  CLOPT   = "-A -- -F"

	TMIFRSVR
	  SRVGRP  = SYS_GRP
	  SRVID   = 5

	UNIVT_SERVER
	  SRVGRP  = ORA_GRP
	  SRVID   = 1
	  RESTART = N

   	ISL
	  SRVGRP  = SYS_GRP
	  SRVID   = 6
	  CLOPT   = -A -- -n //MACHINENAME:2500

*SERVICES

For information about the transaction log and defining parameters in the Configuration file, see Administering Transactions.