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 Development Process for BEA Tuxedo CORBA Applications

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

Figure 3-1 Development Process for 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 Simpapp Sample Application

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.

Table 3-2 CORBA Interfaces for the Simpapp Sample Application

Listing 3-1 OMG IDL Code for 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 Files Created by the idl Command

Table 3-4 Files Created by the idltojava 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 C++ Implementation of the Simple and SimpleFactory Interfaces

// 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 CORBA C++ 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.

Table 3-5 Activation Policies

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 Example of Creating and Registering 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(),
	);
...

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 Example of Releasing a BEA Tuxedo 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:

Listing 3-6 CORBA Client Application from the Simpapp Sample Application

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

Listing 3-7 Java Client Application from the Simpapp Sample Application

public class SimpleClient
{
	public static void main(String args[])

	// Initialize the ORB.
	ORB orb = ORB.init(args, null);

	// Create the Bootstrap object
	Tobj_Bootstrap bootstrap = new Tobj_Bootstrap(orb, "");

	// Use the Bootstrap object to locate the FactoryFinder
	org.omg.CORBA.Object factory_finder_oref =
	bootstrap.resolve_initial_references("FactoryFinder");

	// Narrow the FactoryFinder
	FactoryFinder factory_finder_reference =
	FactoryFinderHelper.narrow(factory_finder_oref);

	// Use the FactoryFinder to find the Simple factory.
	org.omg.CORBA.Object simple_factory_oref =
	factory_finder_reference.find_one_factory_by_id
	(SimpleFactoryHelper.id());

	// Narrow the Simple factory
	SimpleFactory simple_factory_reference =
	SimpleFactoryHelper.narrow(simple_factory_oref);

	// Find the Simple object.
	Simple simple = simple_factory_reference.find_simple();

	// Get a string from the user.
	System.out.println("String?");
	String mixed = in.readLine();

	// Convert the string to upper case.
	org.omg.CORBA.StringHolder buf = new 
	org.omg.CORBA.StringHolder(mixed);
	     simple.to_upper(buf);
	System.out.println(buf.value);

	// Convert the string to lower case.
	String lower = simple.to_lower(mixed);
	System.out.println(lower);
        }
}

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.

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.

Table 3-6 Sections in the Configuration File for BEA Tuxedo CORBA Applications

Listing 3-8 Configuration File for 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:

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:

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 Java client applications, use the javac command to construct a CORBA client application executable program. You need to include the tuxdir\udataobj\java\jdk\m3envobj.jar file in your CLASSPATH when you compile the Java client application. The m3envobj.jar file contains the Java classes for the BEA Tuxedo environmental objects.

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.

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-7 The BEA Tuxedo CORBA Sample Applications