Introducing Transactions

This topic includes the following sections:

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

Support for Business Transactions

OTS provides the following support for your business transactions:

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.

How to Use Transactions in BEA Tuxedo CORBA Applications

Figure 1-1 Transactions in a BEA Tuxedo CORBA Application

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:

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:

Note: All operations on the CORBA interface execute within the scope of a transaction.

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:

Figure 1-2 Transactions Sample Application

Development Steps

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

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 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

Table 1-1 CORBA Transaction Policies

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.

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:

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:

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