Getting Started with Oracle Tuxedo CORBA Applications

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Developing Oracle Tuxedo CORBA Applications

This topic includes the following sections:

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

Note: 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.
Note: 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.

 


Overview of the Development Process for Oracle Tuxedo CORBA Applications

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

Table 3-1 Development Process for Oracle Tuxedo CORBA Applications
Step
Description
1
Write the Object Management Group (OMG) Interface Definition Language (IDL) code for each CORBA interface you want to use in your Oracle Tuxedo application.
2
Generate the CORBA client stubs and the skeletons.
3
Write the CORBA server application.
4
Write the CORBA client application.
5
Create an XA resource manager.
6
Create a configuration file.
7
Create a TUXCONFIG file.
8
Compile the CORBA server application.
9
Compile the CORBA client application.
10
Start the Oracle Tuxedo CORBA application.

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

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

Figure 3-1 Development Process for Oracle Tuxedo CORBA Applications

Development Process for Oracle 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.

Figure 3-2 Simpapp Sample Application

Simpapp Sample Application

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

Note: The Simpapp sample applications demonstrate building CORBA C++ client and server applications.

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

 


Step 1: Write the OMG IDL Code

The first step in writing a Oracle 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.

Table 3-2 CORBA Interfaces for the Simpapp Sample Application 
Interface
Description
Operation
SimpleFactory
Creates object references to the Simple object
find_simple()
Simple
Converts the case of a string
to_upper()
to_lower()

Listing 3-1 shows the simple.idl file that defines the CORBA interfaces in 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 Oracle Tuxedo CORBA client and server applications:

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

Table 3-3 Files Created by the idl Command
File
Default Name
Description
CORBA client stub file
application_c.cpp
Contains generated code for sending a request.
CORBA client stub header file
application_c.h
Contains class definitions for each interface and type specified in the OMG IDL file.
Skeleton file
application_s.cpp
Contains skeletons for each interface specified in the OMG IDL file. During run time, the skeleton maps CORBA client requests to the appropriate operation in the CORBA server application.
Skeleton header file
application_s.h
Contains the skeleton class definitions.
Implementation file
application_i.cpp
Contains signatures for the methods that implement the operations on the interfaces specified in the OMG IDL file.
Implementation header file
application_i.h
Contains the initial class definitions for each interface specified in the OMG IDL file.

 


Step 3: Write the CORBA Server Application

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

  1. Write the methods that implement the operations for each interface.
  2. Create the CORBA server object.
  3. Define object activation policies.
  4. Create and register a factory.
  5. Release the CORBA server application.
Note: Oracle Tuxedo uses the new style of std C++ header files on Linux/HP-UX/Solaris, and uses the older style of files on AIX. You can check the"OBB_ANSI_CPP" macro to decide which type of header to use.
Note: If "OBB_ANSI_CPP" is defined, the standard C++ headers are included.
Note: If "OBB_ANSI_CPP" is undefined, the old C headers are included.

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.

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 includes the C++ code from the Simpapp sample application for the Server object.

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.

Note: You also define transaction policies in the ICF file. For information about using transactions in your Oracle Tuxedo CORBA application, see Using CORBA Transactions in the Oracle Tuxedo online documentation.

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

Table 3-4 Activation Policies 
Activation Policy
Description
method
Causes the object to be active only for the duration of the invocation on one of the object’s operations. This is the default activation policy.
transaction
Causes the object to be activated when an operation is invoked on it. If the object is activated within the scope of a transaction, the object remains active until the transaction is either committed or rolled back.
process
Causes the object to be activated when an operation is invoked on it, and to be deactivated only when one of the following occurs:
  • The process in which the server application exists is shut down.
  • The method TP::deactivateEnable() (C++) has been invoked on the object.

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

  1. Create an object reference to the factory.
  2. You include an invocation to the create_object_reference() method, specifying the Interface Repository ID of the factory’s OMG IDL interface or the object ID (OID) in string format. In addition, you can specify routing criteria.

  3. Register the factory with the Oracle Tuxedo domain.
  4. Use the register_factory() method to register the factory with the FactoryFinder object in the Oracle Tuxedo domain. The register_factory() method requires the object reference for the factory and a string identifier.

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

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(),
);
...

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.

Listing 3-5 Example of Releasing a Oracle Tuxedo CORBA server Application
...
public void release()
{
TP::unregister_factory(
factory_reference.in(),
SimpleFactoryHelper->id
);
}
...

 


Step 4: Write the CORBA Client Application

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

The steps for creating CORBA client applications are as follows:

  1. Initialize the ORB.
  2. Use the Bootstrap object or the CORBA INS bootstrapping mechanism to establish communication with the Oracle Tuxedo domain.
  3. Resolve initial references to the FactoryFinder environmental object.
  4. Use a factory to get an object reference for the desired CORBA object.
  5. Invoke methods on the CORBA object.

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.

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

 


Step 5: Create an XA Resource Manager

When using transactions in a Oracle Tuxedo CORBA application, you need to create a CORBA server process for the resource manager that interacts with a database on behalf of the Oracle 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 Oracle 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 Oracle Tuxedo Command Reference in the Oracle Tuxedo online documentation.

 


Step 6: Create a Configuration File

Because the Oracle 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 Oracle 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 Oracle Tuxedo CORBA application using a set of parameters that the Oracle 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.

Listing 3-7 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:

For more information about the tmloadcf command, see the Oracle Tuxedo Command Reference in the Oracle 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 Oracle 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 Oracle Tuxedo libraries to form a CORBA client executable. For the syntax of the buildobjclient command, see the Oracle Tuxedo Command Reference in the Oracle Tuxedo online documentation.

 


Step 10: Start the Oracle Tuxedo CORBA Application

Use the tmboot command to start the server processes in your Oracle 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 Oracle 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 Oracle Tuxedo online documentation.

 


Additional Oracle Tuxedo CORBA Sample Applications

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

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

Table 3-6 The Oracle Tuxedo CORBA Sample Applications 
Oracle Tuxedo CORBA
Sample Application
Description
Simpapp
Provides a CORBA C++ client application and a C++ server application. The C++ server application contains two operations that manipulate strings received from the C++ client application.
Basic
Describes how to develop Oracle Tuxedo CORBA client and server applications and configure the Oracle Tuxedo application. Building C++ server applications and CORBA C++ applications, CORBA client applications are demonstrated.
Security
Demonstrates adding Oracle Tuxedo authentication to a Oracle Tuxedo CORBA application. For information about building and running the Security sample application, see Using Security in CORBA Applications in the Oracle Tuxedo online documentation.
Transactions
Adds transactional objects to the CORBA C++ server application and CORBA client applications in the Basic sample application. The Transactions sample application demonstrates how to use the Implementation Configuration File (ICF) to define transaction policies for CORBA objects. For information about building and running the Transactions sample application, see Using CORBA Transactions in the Oracle Tuxedo online documentation.
Wrapper
Demonstrates how to wrap an existing Oracle Tuxedo ATMI application as a CORBA object.
Production
Demonstrates replicating server applications, creating stateless objects, and implementing factory-based routing in server applications.
Secure Simpapp
Implements the necessary development and administrative changes to the Simpapp sample application to support certificate authentication. For information about building and running the Secure Simpapp sample application, see Using Security in CORBA Applications in the Oracle Tuxedo online documentation.
Introductory Events
Demonstrates how to use joint CORBA client/server applications and callback objects to implement events in a Oracle Tuxedo CORBA application. The C++ version uses the Oracle Simple Events API. For information about building and running the Introductory Events sample application, see Using the CORBA Notification Service in the Oracle Tuxedo online documentation.
Advanced Events
Provides a more complex implementation of events in a Oracle Tuxedo CORBA application with transient and persistent subscriptions and data filtering. The C++ version uses the Advanced CosNotification API. For information about building and running the Advanced Events sample application, see Using the CORBA Notification Service in the Oracle Tuxedo online documentation.


  Back to Top       Previous  Next