Getting Started with BEA Tuxedo CORBA Applications

Developing BEA Tuxedo CORBA Applications

This topic includes the following sections:

For an in-depth discussion of creating BEA Tuxedo CORBA client and server applications, see the following in the BEA Tuxedo online documentation:

Overview of the Development Process for BEA Tuxedo CORBA Applications

Table 3-1 outlines the development process for BEA Tuxedo CORBA applications.

The steps in the development process are described in the following sections.

Figure 3-1 illustrates the process for developing BEA Tuxedo CORBA applications.

The Simpapp Sample Application

Throughout this topic, the Simpapp sample application is used to demonstrate the development steps.

The CORBA server application in the Simpapp sample application provides an implementation of a CORBA object that has the following two methods:

Figure 3-2 illustrates how the Simpapp sample application works.

The source files for the Simpapp sample application are located in the $TUXDIR\samples\corba\simpapp directory of the BEA Tuxedo software. Instructions for building and running the Simpapp sample applications are in the Readme.txt file in the same directory.

BEA Tuxedo offers a suite of sample applications that demonstrate and aid in the development of BEA Tuxedo CORBA applications. For an overview of the available sample applications, see Samples in the BEA Tuxedo online documentation.

Step 1: Write the OMG IDL Code

The first step in writing a BEA Tuxedo CORBA application is to specify all of the CORBA interfaces and their methods using the Object Management Group (OMG) Interface Definition Language (IDL). An interface definition written in OMG IDL completely defines the CORBA interface and fully specifies each operation's arguments. OMG IDL is a purely declarative language. This means that it contains no implementation details. Operations specified in OMG IDL can be written in and invoked from any language that provides CORBA bindings.

The Simpapp sample application implements the CORBA interfaces listed in Table 3-2.

Listing 3-1 shows the simple.idl file that defines the CORBA interfaces in the Simpapp sample application.

#pragma prefix "beasys.com"

interface Simple
{
     //Convert a string to lower case (return a new string)
     string to_lower(in string val);

     //Convert a string to upper case (in place)
     void to_upper(inout string val);
};

interface SimpleFactory
{
     Simple find_simple();
};

Step 2: Generate CORBA client Stubs and Skeletons

The interface specification defined in OMG IDL is used by the IDL compiler to generate CORBA client stubs for the CORBA client application, and skeletons for the CORBA server application. The CORBA client stubs are used by the CORBA client application for all operation invocations. You use the skeleton, along with the code you write, to create the CORBA server application that implements the CORBA objects.

During the development process, use one of the following commands to compile the OMG IDL file and produce CORBA client stubs and skeletons for BEA Tuxedo CORBA client and server applications:

Table 3-3 lists the files that are created by the idl command.

Step 3: Write the CORBA Server Application

The BEA Tuxedo software supports CORBA C++ server applications. The steps for creating CORBA server applications are:

Writing the Methods That Implement the Operations for Each Interface

After you compile the OMG IDL file, you need to write methods that implement the operations for each interface in the file. An implementation file contains the following:

You can write the implementation file manually. The idl command provides an option for generating a template for implementation files.

Listing 3-2 includes the C++ implementation of the Simple and SimpleFactory interfaces in the Simpapp sample application.

// Implementation of the Simple_i::to_lower method which converts
// a string to lower case.

char* Simple_i::to_lower(const char* value)
{
     CORBA::String_var var_lower = CORBA::string_dup(value);
     for (char* ptr = var_lower; ptr && *ptr; ptr++) {
         *ptr = tolower(*ptr);
     }
     return var_lower._retn();
}

// Implementation of the Simple_i::to_upper method which converts
// a string to upper case.

void Simple_i::to_upper(char*& valuel)
{
     CORBA::String_var var_upper = value1;
     var_upper = CORBA::string_dup(var_upper.in());
     for (char* ptr = var_upper; ptr && *ptr; ptr++) {
         *ptr = toupper(*ptr);
     }
     value = var_upper._retn();
}
// Implementation of the SimpleFactory_i::find_simple method which
// creates an object reference to a Simple object.

Simple_ptr SimpleFactory_i::find_simple()
{
     CORBA::Object_var var_simple_oref =
         TP::create_object_reference(
             _tc_Simple->id(),    
             "simple",             
             CORBA::NVList::_nil()
         );
     }

Creating the CORBA server Object

The Server object performs the following tasks:

In CORBA server applications, the Server object is already instantiated and a header file for the Server object is available. You implement methods that initialize and release the server application, and, if desired, create servant objects.

Listing 3-3 includes the C++ code from the Simpapp sample application for the Server object.

static CORBA::Object_var static_var_factory_reference;

// Method to start up the server

CORBA::Boolean Server::initialize(int argc, char* argv[])
{
	// Create the Factory Object Reference

	static_var_factory_reference =
	    TP::create_object_reference(
		_tc_SimpleFactory->id(), 
		"simple_factory",        
		CORBA::NVList::_nil()    
	    );
	// Register the factory reference with the FactoryFinder

	TP::register_factory(
	     static_var_factory_reference.in(),      
	    _tc_SimpleFactory->id() 
	);
	return CORBA_TRUE;
}
// Method to shutdown the server

void Server::release()
{
// Unregister the factory.

  try {
	TP::unregister_factory(
	    static_var_factory_reference.in(),      
	    _tc_SimpleFactory->id() 
	);
  }
  catch (...) {
	TP::userlog("Couldn't unregister the SimpleFactory");
  }
}
// Method to create servants

Tobj_Servant Server::create_servant(const char*
 interface_repository_id)
{
	if (!strcmp(interface_repository_id, 
	_tc_SimpleFactory->id())) {
		return new SimpleFactory_i();
	}
	if (!strcmp(interface_repository_id, 
	_tc_Simple->id())) {
		return new Simple_i();
	}
	return 0; 
}

Defining an Object's Activation Policies

As part of CORBA server development, you determine what events cause an object to be activated and deactivated by assigning object activation policies.

For CORBA server applications, specify object activation policies in the Implementation Configuration File (ICF). A template ICF file is created by the genicf command.

The BEA Tuxedo software supports the activation policies listed in Table 3-4.

The Simple interface in the Simpapp sample application is assigned the default activation policy of method. For more information about managing object state and defining object activation policies, see Creating CORBA Server Applications in the BEA Tuxedo online documentation.

Creating and Registering a Factory

If your CORBA server application manages a factory that you want CORBA client applications to be able to locate easily, you need to write the code that registers that factory with the FactoryFinder object.

To write the code that registers a factory managed by your CORBA server application, you do the following:

Listing 3-4 includes the code from the Simpapp sample application that creates and registers a factory.

...
CORBA::Object_var v_reg_oref =
	TP:create_object_reference(
		_tc.SimpleFactory->id(),    //Factory Interface ID
		"simplefactory",            //Object ID
		CORBA::NVList::_nil()				//Routing Criteria
	);

	TP::register_factory(
		CORBA::Object_var v_reg_oref.in(),
		_tc_SimpleFactory->id(),
	);
...

In Listing 3-4, notice the following:

Releasing the CORBA Server Application

You need to include code in your CORBA server application to perform a graceful shutdown of the CORBA server application. The release()method is provided for that purpose. Within the release() method, you may perform any application-specific cleanup tasks that are specific to the CORBA server application, such as:

Once a CORBA server application receives a request to shut down, the CORBA server application can no longer receive requests from other remote objects. This has implications on the order in which CORBA server applications should be shut down, which is an administrative task. For example, do not shut down one server process if a second server process contains an invocation in its release() method to the first server process.

During server shutdown, you may want to unregister each of the server application's factories. The invocation of the unregister_factory() method should be one of the first actions in the release() implementation. The unregister_factory() method unregisters the server application's factories. This operation requires the following input arguments:

Listing 3-5 includes C++ code that releases a server application and unregisters the factories in the CORBA server application.

...
public void release()
{
	TP::unregister_factory(
		factory_reference.in(),
		SimpleFactoryHelper->id
		);
}

...

Step 4: Write the CORBA Client Application

The BEA Tuxedo software supports the following types of CORBA client applications:

The steps for creating CORBA client applications are as follows:

The CORBA client development steps are illustrated in Listing 3-6 which include code from the Simpapp sample application. In the Simpapp sample application, the CORBA client application uses a factory to get an object reference to the Simple object and then invokes the to_upper() and to_lower() methods on the Simple object.

int main(int argc, char* argv[])
{
    try {
	// Initialize the ORB 
	CORBA::ORB_var var_orb = CORBA::ORB_init(argc, argv, "");

	// Create the Bootstrap object
	Tobj_Bootstrap bootstrap(var_orb.in(), "");

	// Use the Bootstrap object to find the FactoryFinder
	CORBA::Object_var var_factory_finder_oref =
	  bootstrap.resolve_initial_references("FactoryFinder");

	// Narrow the FactoryFinder
	Tobj::FactoryFinder_var var_factory_finder_reference =
	 Tobj::FactoryFinder::_narrow
	 (var_factory_finder_oref.in());

	// Use the factory finder to find the Simple factory
	CORBA::Object_var var_simple_factory_oref =
	var_factory_finder_reference->find_one_factory_by_id(
	_tc_SimpleFactory->id()
	);

	// Narrow the Simple factory
	SimpleFactory_var var_simple_factory_reference =
	  SimpleFactory::_narrow(
	                         var_simple_factory_oref.in());

	// Find the Simple object
	Simple_var var_simple =
	  var_simple_factory_reference->find_simple();

	// Get a string from the user 
	cout << "String?";
	char mixed[256];
	cin >> mixed;

	// Convert the string to upper case :
	CORBA::String_var var_upper = CORBA::string_dup(mixed);
	var_simple->to_upper(var_upper.inout());
	cout << var_upper.in() << endl;

	// Convert the string to lower case 
	CORBA::String_var var_lower = var_simple->to_lower(mixed);
	cout << var_lower.in() << endl;
	
	return 0;
	}
}

Step 5: Create an XA Resource Manager

When using transactions in a BEA Tuxedo CORBA application, you need to create a CORBA server process for the resource manager that interacts with a database on behalf of the BEA Tuxedo CORBA application. The resource manager you use must conform to the X/OPEN XA specification and you need the following information about the resource manager:

When integrating a new XA resource manager into the BEA Tuxedo system, the file $TUXDIR/udataobj/RM must be updated to include information about the XA resource manager. The information is used to include the correct libraries for the XA resource manager and to set up the interface between the transaction manager and the XA resource manager automatically and correctly. The format of this file is as follows:

rm_name:rm_structure_name:library_names

where rm_name is the name of the XA resource manager, rm_structure_name is the name of the xa_switch_t structure that defines the name of the XA resource manager, and library_names is the list of the object files for the XA resource manager. White space (tabs and/or spaces) is allowed before and after each of the values and may be embedded within the library_names. The colon (:) character may not be embedded within any of the values. Lines beginning with a pound sign (#) are treated as comments and are ignored.

Use the buildtms command to build a server process for the XA resource manager. The files that result from the buildtms command need to be installed in the $TUXDIR/bin directory.

For more information about the buildtms command, see the BEA Tuxedo Command Reference in the BEA Tuxedo online documentation.

Step 6: Create a Configuration File

Because the BEA Tuxedo software offers great flexibility and many options to application designers and programmers, no two CORBA applications are alike. An application, for example, may be small and simple (a single client and server running on one machine) or complex enough to handle transactions among thousands of client and server applications. For this reason, for every BEA Tuxedo CORBA application being managed, the system administrator must provide a configuration file that defines and manages the components (for example, domains, server applications, client applications, and interfaces) of that application.

When system administrators create a configuration file, they are describing the BEA Tuxedo CORBA application using a set of parameters that the BEA Tuxedo software interprets to create a runnable version of the application. During the setup phase of administration, the system administrator's job is to create a configuration file. The configuration file contains the sections listed in Table 3-5.

Listing 3-7 shows the configuration file for the Simpapp sample application.

*RESOURCES                               
	IPCKEY    55432                  
	DOMAINID  simpapp                   
	MASTER    SITE1                     
	MODEL     SHM                       
	LDBAL     N                         

*MACHINES                               
	"PCWIZ"                            
	LMID         = SITE1            
	APPDIR       = "C:\TUXDIR\MY_SIM~1"       
	TUXCONFIG    = "C:\TUXDIR\MY_SIM~1\results\tuxconfig"    
	TUXDIR       = "C:\TUXDIR"       
	MAXWSCLIENTS = 10               

*GROUPS                                 
	SYS_GRP                             
	LMID    = SITE1                 
	GRPNO   = 1                     
	APP_GRP                             
	LMID    = SITE1                 
	GRPNO   = 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"            
	simple_server                       
	   SRVGRP  = APP_GRP               
          SRVID   = 1                     
	   RESTART = N                     
	ISL                                 
	   SRVGRP  = SYS_GRP               
	   SRVID   = 5                     
	   CLOPT   = "-A -- -n //PCWIZ:2468" 

*SERVICES

Step 7: Create the TUXCONFIG File

There are two forms of the configuration file:

For more information about the tmloadcf command, see the BEA Tuxedo Command Reference in the BEA Tuxedo online documentation.

Step 8: Compile the CORBA Server Application

You use the buildobjserver command to compile and link C++ server applications. The buildobjserver command has the following format:

buildobjserver [-o servername] [options]

In the buildobjserver command syntax:

When you create a server application to support multithreading, you must specify the -t option on the buildobjserver command when you build the application. For complete information on creating a server application to support multithreading, see Creating CORBA Server Applications.

Step 9: Compile the CORBA Client Application

The final step in the development of the CORBA client application is to produce the executable client application. To do this, you need to compile the code and then link against the client stub.

When creating CORBA C++ client applications, use the buildobjclient command to construct a BEA Tuxedo CORBA client application executable. The command combines the CORBA client stubs for interfaces that use static invocation, and the associated header files, with the standard BEA Tuxedo libraries to form a CORBA client executable. For the syntax of the buildobjclient command, see the BEA Tuxedo Command Reference in the BEA Tuxedo online documentation.

Step 10: Start the BEA Tuxedo CORBA Application

Use the tmboot command to start the server processes in your BEA Tuxedo CORBA application. The CORBA application is usually booted from the machine designated as the MASTER in the RESOURCES section of the UBBCONFIG file.

For the tmboot command to find executables, the BEA Tuxedo system processes must be located in the $TUXDIR/bin directory. Server applications should be in APPDIR, as specified in the configuration file.

When booting server applications, the tmboot command uses the CLOPT, SEQUENCE, SRVGRP, SRVID, and MIN parameters from the configuration file. Server applications are booted in the order in which they appear in the configuration file.

For more information about using the tmboot command, see File Formats, Data Descriptions, MIBs, and System Processes Reference in the BEA Tuxedo online documentation.

Additional BEA Tuxedo CORBA Sample Applications

Sample applications demonstrate the tasks involved in developing a BEA Tuxedo CORBA application, and provide sample code that can be used by CORBA client and server programmers to build their own BEA Tuxedo CORBA application. Code from the sample applications are used throughout the information topics in the BEA Tuxedo product to illustrate the development and administrative steps.

Table 3-6 describes the additional BEA Tuxedo CORBA sample applications.