Developing an Application That Uses the CORBA Name Service

This topic includes the following sections:

•	Development Steps

•	Step 1: Obtain the OMG IDL for the CosNaming Interfaces

•	Step 2: Include the Declarations and Prototypes for the CosNaming Interfaces

•	Step 3: Connect to the Oracle Tuxedo Namespace

•	Step 4: Bind an Object to the Oracle Tuxedo Namespace

•	Step 5: Use a Name to Locate an Object in the Oracle Tuxedo Namespace

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.

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.

Development Steps

Table 5‑1 outlines the process for developing Oracle Tuxedo CORBA applications that use the CORBA Name Service.

 

Table 5‑1 Development Process

Step	Description
1	Obtain the OMG IDL for the CosNaming interfaces.
2	Include the declarations and prototypes for the CosNaming interfaces.
3	Connect to the Oracle Tuxedo namespace.
4	Bind an object to the Oracle Tuxedo namespace.
5	Use a name to locate an object in the Oracle Tuxedo namespace.

Before performing the steps in this topic, you need to start the server process for the CORBA Name Service. For more information, see “Starting the Server Process for the CORBA Name Service” on page 3‑2.

After performing the development steps in this topic, use the buildobjclient and buildobjserver commands to compile server and client applications that use the CORBA Name Service. For more information about the buildobjclient and buildobjserver commands, see the Oracle Tuxedo Command Reference.

Step 1: Obtain the OMG IDL for the CosNaming Interfaces

An Oracle Tuxedo CORBA application accesses the CORBA Name Service using the interfaces defined in CosNaming.idl. This Object Management Group (OMG) Interface Definition Language (IDL) file defines the interfaces, COSnaming data structures, and exceptions used by the CORBA Name Service. The CosNaming.idl file is located in the following directory locations:

Windows

drive:\%TUXDIR%\include\CosNaming.idl

UNIX

/usr/local/$TUXDIR/include/CosNaming.idl

Listing 5‑1 shows the OMG IDL for CosNaming.idl. The same OMG IDL file is used by both CORBA C++ applications.

Listing 5‑1 CosNaming.idl

#ifndef _COSNAMING_IDL_
#define _COSNAMING_IDL_

module CosNaming {

#pragma prefix "omg.org/CosNaming"
       ytypedef string Istring;

       struct NameComponent {
              Istring id;
              Istring kind;
       };

       typedef sequence<NameComponent> Name;

       enum BindingType { nobject, ncontext };

       struct Binding {
              Name binding_name;
              BindingType binding_type;
       };

       typedef sequence <Binding> BindingList;

       interface BindingIterator;
       
       interface NamingContext {
              enum NotFoundReason { missing_node,
                                   not_context,
                                   not_object };

              exception NotFound {
                     NotFoundReason why;
                     Name rest_of_name;
              };

              exception CannotProceed {
                     NamingContext cxt;
                     Name rest_of_name;
              };

              exception InvalidName{};

              exception AlreadyBound {};

              exception NotEmpty{};

              void bind(in Name n, in Object obj)
                     raises(NotFound,
                            CannotProceed,
                            InvalidName,
                            AlreadyBound);

              void rebind(in Name n, in Object obj)
                     raises(NotFound,
                            CannotProceed,
                            InvalidName);

              void bind_context(in Name n, in NamingContext nc)
                     raises(NotFound,
                            CannotProceed,
                            InvalidName,
                            AlreadyBound);

              void rebind_context(in Name n, in NamingContext nc)
                     raises(NotFound,
                            CannotProceed,
                            InvalidName);

              Object resolve (in Name n)
                     raises(NotFound,
                            CannotProceed,
                            InvalidName);

              void unbind(in Name n)
                     raises(NotFound,
                            CannotProceed,
                            InvalidName);

              NamingContext new_context();
              NamingContext bind_new_context(in Name n)
                     raises(NotFound,
                            AlreadyBound,
                            CannotProceed,
                            InvalidName);

              void destroy() raises(NotEmpty);
              void list(in unsigned long how_many,
                           out BindingList bl,
                           out BindingIterator bi);

       };

       interface BindingIterator {
              boolean next_one(out Binding b);
              boolean next_n(in unsigned long how_many,
                            out BindingList bl);
              void destroy();
       };

       interface NamingContextExt:NamingContext {
              typedef string StringName;
              typedef string Address;
              typedef string URLString;

       StringName to_string(in Name n) raises(InvalidName);
       Name to_name(in StringName sn)
                            raises(InvalidName);
       exception InvalidAddress {};

       URLString to_url(in Address addr, in StringName sn)
                            raises(InvalidAddress, InvalidName);

       Object resolve_str(in StringName n)
                            raises(NotFound,
                                   CannotProceed,
                                   InvalidName,
                                   AlreadyBound
                     );
              };
};

#pragma ID CosNaming "IDL:omg.org/CosNaming:1.0"
#endif // _COSNAMING_IDL_

 

Step 2: Include the Declarations and Prototypes for the CosNaming Interfaces

The declarations and prototypes for the CosNaming interfaces are provided as part of the software kit for the CORBA Name Service.

•	For CORBA C++ client applications, include the declarations and prototypes for the naming interfaces by adding this statement to your Oracle Tuxedo CORBA client application:

#include "CosNaming_c.h"

The include files for an Oracle Tuxedo CORBA C++ client application are located in the $TUXDIR/include directory on UNIX systems and the %TUXDIR%\include directory on Windows systems.

•	If you are using a third-party Object Request Broker (ORB), you need to include or import the CosNaming interfaces in your client source stub programs before compiling.

Step 3: Connect to the Oracle Tuxedo Namespace

The Bootstrap object supports a NameService environmental object for connecting to the root of the namespace. When using the NameService environmental object, the Object Request Broker (ORB) locates the root of the namespace. The object reference can then be narrowed to CosNaming::NamingContext or CosNamingContextExt. You need to connect to the Oracle Tuxedo namespace before binding objects into the namespace and resolving names in the namespace.

Use the Bootstrap object or the CORBA Interoperable Naming Service (INS) bootstrapping mechanism to get an initial reference to the NameService environmental object. Use the Oracle proprietary mechanism if you are using the Oracle client ORB. Use the CORBA INS mechanism if you are using a client ORB from another vendor. For more information about bootstrapping the Oracle Tuxedo domain see Chapter 4, “CORBA Bootstrapping Programming Reference,” in the CORBA Programming Reference in the Oracle Tuxedo online documentation.

Listing 5‑2 illustrates C++ code that establishes communication with an Oracle Tuxedo namespace.

Listing 5‑2 C++ Example of Connecting to a Namespace

...
Tobj_Bootstrap * bootstrap = new Tobj_Bootstrap (v_orb.in(), "");
CORBA::Object_var var_nameservice_oref=
       bootstrap.resolve_initial_references("NameService");
root = CosNaming::NamingContext::_narrow (obj);
...

 

A stringified object reference for the root of the namespace can also be used to connect to a namespace in an Oracle Tuxedo domain. In order to use a stringified object reference, the -f command-line option must be specified when starting the server process for the CORBA Name Service. The -f command-line option writes the stringified object reference to the CNS_ROOT_FILE environment variable or to one of the following locations:

Windows

%APPDIR%\cnsroot.dat

UNIX

$APPDIR/cnsroot.dat

The stringified object reference for the root of the namespace does not change when the server process for the CORBA Name Service is started and stopped because stringified object reference is associated with a particular host machine rather than a particular server process. A stringified object reference that has been retrieved to communicate with one Oracle Tuxedo namespace cannot be used to communicate with another Oracle Tuxedo namespace.

Listing 5‑3 includes C++ code that establishes communication with an Oracle Tuxedo namespace using a stringified object reference.

Listing 5‑3 C++ Example of Using a Stringified Object Reference

...
Tobj_Bootstrap * bootstrap;
bootstrap = new Tobj_Bootstrap (v_orb.in(), "");
CORBA::Object_var obj = GetRefFromFile ("cnsroot.dat", v_orb);
root = CosNaming::NamingContext::_narrow (obj);
...

 

If you choose to use a stringified object reference in an Oracle Tuxedo CORBA application that also employs security and transactions, please note the following restrictions:

1.

The Oracle Tuxedo CORBA application must create a Bootstrap object and connect to the IIOP Listener/Handler before using the stringified object reference to connect to an Oracle Tuxedo namespace. By calling the Bootstrap object first, the Oracle Tuxedo application establishes an official connection to the IIOP Listener/Handler.

If an Oracle Tuxedo application does not first create a Bootstrap object, transactions and security cannot be used with any object retrieved from the namespace. Transactions and security require the use of an official connection.

2.	If more than one IIOP Listener/Handler is defined in the UBBCONFIG file, the Oracle Tuxedo CORBA application must use the first IIOP Listener/Handler defined in the UBBCONFIG file by the TOBJADDR environment variable.

The CORBA Name Service creates the stringified object reference for the root of the namespace, using the default IIOP Listener/Handler’s host and port. The first IIOP Listener/Handler defined in a UBBCONFIG file is considered the default IIOPListener/Handler. Using the default IIOP Listener/Handler causes all object references retrieved by the CORBA Name Service to be official connections. Transactions and security require the use of official connections.

Step 4: Bind an Object to the Oracle Tuxedo Namespace

There are two ways to bind an object to the Oracle Tuxedo namespace:

•	The cnsbind command

•	The bind() method of the CosNaming::NamingContext object

The cnsbind command can be used to bind application objects or naming context objects to the Oracle Tuxedo namespace. The server process for the CORBA Name Service must be started before using the cnsbind command. For a complete description of the cnsbind command, see Chapter 2, “CORBA Name Service Reference.”

Listing 5‑4 show the C++ code implementations of the bind() method of the CosNaming::NamingContext object. The code examples accept two parameters, representing the id and kind fields for a Name. These parameters initialize a Name for the SimpleFactory object and bind the SimpleFactory object to the namespace.

Listing 5‑4 C++ Example of Binding a Name to the Oracle Tuxedo Namespace

...
//Establish the Name used to identify the SimpleFactory object
//in the namespace.

CosNaming::Name_var factory_name = new CosNaming::Name(1);
       factory_name->length(1);
       factory_name[(CORBA::ULong) 0].id =
                                   (const char * "simple_factory";
       factory_name[(CORBA::ULong) 0].kind =
                                   (const char *) "";
//Create an object reference for the SimpleFactory object

s_v_factory_refer = TP::create_object_reference(
                                   _tc_SimpleFactory->id(),
                                   "simple_factory",
                                   CORBA::NVList::_nil()
);
//Get the NameService object reference. See Listing 4-2.
//Place the object reference for SimpleFactory in the namespace

root->bind(factory_name, s_v_fact_ref);
...

 

Step 5: Use a Name to Locate an Object in the Oracle Tuxedo Namespace

Use the resolve() method of the CosNaming::NamingContext object to locate an object in a namespace in an Oracle Tuxedo domain. Listing 5‑5 shows the C++ code that accepts two parameters, representing the id and kind fields for a Name. The code example then binds to a naming context, resolves the name, and obtains an object reference for the specified object.

Listing 5‑5 C++ Example of Locating a Name in the Oracle Tuxedo Namespace

...
//Establish the Name used to identify the SimpleFactory object
//in the namespace.
CosNaming::Name_var         factory_name = new CosNaming::Name(1);
       factory_name->length(1);
       factory_name[(CORBA::ULong) 0].id =
                                   (const char * "simple_factory";
       factory_name[(CORBA::ULong) 0].kind =
                                   (const char *) "";

//Locate the SimpleFactory object in the namespace
CORBA::Object_var v_simple_factory_oref =
              root->resolve( *factory_name);
SimpleFactory_var v_simple_factory_ref =
              SimpleFactory::_narrow(v_simple_factory_oref.in());

// Use the reference obtained from the Oracle Tuxedo CORBA Name Service // to find the Simple object
Simple_var v_simple = v_simple_factory_ref->find_simple();
...