Table of Contents Previous Next PDF


Developing Oracle Tuxedo CORBA Applications

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:
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.
 
Create a TUXCONFIG file.
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
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:
The upper method accepts a string from the CORBA client application and converts the string to uppercase letters.
The lower method accepts a string from the CORBA client application and converts the string to lowercase letters.
Figure 3‑2 illustrates how the Simpapp sample application works.
Figure 3‑2 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:
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.
 
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:
If you are creating CORBA C++ client and server applications, use the idl command. For a description of the idl command, see the Oracle Tuxedo Command Reference in the Oracle Tuxedo online documentation.
Table 3‑3 lists the files that are created by the idl command.
 
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.
2.
3.
4.
5.
Note:
If "OBB_ANSI_CPP" is defined, the standard C++ headers are included.
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:
The activate_object() and deactivate_object() methods (optional)
Within the activate_object() and deactivate_object() methods, you write code that performs any particular steps related to activating or deactivating the object. For more information, see Creating CORBA Server Applications in the Oracle Tuxedo online documentation.
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:
The Oracle Tuxedo software supports the activation policies listed in Table 3‑4.
 
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.
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.
2.
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:
tc.SimpleFactory->id() specifies the SimpleFactory object's Interface Repository ID by extracting it from its typecode.
CORBA::NVList::_nil() specifies that no routing criteria are used, with the result that an object reference created for the Simple object is routed to the same group as the SimpleFactory object that created the object reference.
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.
2.
3.
4.
5.
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:
The name of the structure of type xa_switch_t that contains the name of the XA resource manager.
The commands needed to open and close the XA resource manager. This information is specified in the OPENINFO and CLOSEINFO parameters in the UBBCONFIG configuration file.
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:
The TUXCONFIG file, a binary version of the UBBCONFIG file created using the tmloadcf command. When the tmloadcf command is executed, the environment variable TUXCONFIG must be set to the name and directory location of the TUXCONFIG file. The tmloadcf command converts the configuration file to binary form and writes it to the location specified in the command.
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:
-o servername represents the name of the server application to be generated by this command.
options represents the command-line options to the buildobjserver command.
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.
 
 

Copyright © 1994, 2017, Oracle and/or its affiliates. All rights reserved.