Chapter 17 Creating CORBA C++ Clients

Using the CosNaming interface

Jaguar allows you to use the CORBA CosNaming interface to instantiate proxies in your client applications. This technique of instantiating proxies is not recommended, because it requires use of deprecated SessionManager::Session methods. "Instantiating stub instances" describes the recommended technique for stub instantiation.

You do not need to use the CosNaming API in clients to realize the benefits incurred by using logical component names. The Jaguar server uses the CosNaming API to resolve component names in the implementation of the Session::lookup and Session::create methods.

To use CosNaming, follow these steps:

Step	What it does	Detailed explanation
1	Configure ORB properties, including the ORB runtime driver class and the Jaguar naming server URL, then initialize the ORB runtime.	"Configure and initialize the ORB for CosNaming use"
2	Instantiate the CORBA CosNaming name service and obtain the initial naming context.	"Obtain an initial naming context"
3	Instantiate proxy objects and narrow them to the stub interface.	"Resolving component proxies"
4	Call the proxy objects to remotely invoke component methods.	"Invoking methods"

All examples in this section are taken from the arith.cpp file for the C++ client tutorial in Jaguar CTS Getting Started for your platform.

Configure and initialize the ORB for CosNaming use

"Configure and initialize the ORB runtime" describes how to initialize the ORB and configure run-time properties. One additional property is required in applications that use the CosNaming API.

You must set ORBNameServiceURL property to specify the IIOP URL to the Jaguar name service. This parameter can also be set in an environment variable, JAG_NAMESERVICEURL. Use the following syntax for values:

iiop://hostname:iiop-port/initial-context

where:

hostname is the host machine name for the Jaguar server that serves as the name server for your client. If omitted, the default host name applies.

iiop-port is the IIOP port number for the server.

initial-context is the initial naming context, which you set in the Jaguar server property Initial Context. This can be used to set a default prefix for name resolution. For example, if you specify USA/Sybase/ , all names that you resolve with the context are assumed to be relative to this location in the name hierarchy. When specifying the initial context, a trailing slash is optional; it is added automatically if you do not specify an initial context that ends with a slash.

If your application uses a cluster of Jaguar servers, the cluster may use multiple name servers. In this case, specify the URL (host machine name and IIOP port number) for each name server in a list separated by semicolons and no white space. Include the cluster's initial naming context only with the last URL. For example:

iiop://host1:9000;iiop://host2:9000/USA/Sybase/

Obtain an initial naming context

After initializing the ORB, call the resolve_initial_references method to obtain the initial naming context. The naming context is an object that implements the CosNaming::NamingContext IDL interface; it is used to resolve Jaguar component and service names to server-side objects.

Obtaining the initial context

The example below shows how the initial naming context is retrieved:

// Obtain the CORBA CosNaming initial naming context that
// we will use to resolve objects by name. The ORB retrieves
// the naming server address from command line arguments or
// the environment.

CORBA::Object_var obj =
  orb->resolve_initial_references("NameService");
CosNaming::NamingContext_var nc =
  CosNaming::NamingContext::_narrow(obj);
if (CORBA::is_nil(nc)) {
    cout << "Error: Null NamingContext instance. Exiting.";
    return -1;
    }

Introduction to CosNaming name resolution

The initial NamingContext will have the name context that was specified in the NameServiceURL ORB initialization property. The client invokes the NamingContext::resolve operation to obtain an instance of the Jaguar authentication service as well as component instances.

The NamingContext::resolve operation takes a CosNaming::Name parameter, which is a sequence of CosNaming::NameComponent structures.

A name is represented by a sequence of NameComponent instances, with the id field of each instance set to a node of the name.

As a convenience, the Jaguar name service allows you to specify multiple nodes of a name in one NameComponent instance, using a forward slash (/) to separate nodes.

NamingContext::resolve resolves a name to an object; this method either returns a CORBA::Object instance or throws one of the exceptions described below:

NotFound indicates that the name is not bound to an object, the name does not exist, or some node in the indicated hierarchy does not exist; the why field contains an enumeration that encodes the reason why the name was not found.
InvalidName indicates that the name is malformed.
CannotProceed or a CORBA SystemException indicates that an error has occurred. "Handling exceptions" describes CORBA system exceptions.

Resolving component proxies

Proxy objects are instantiated as follows:

Create a NameComponent array that names the component. Component names are composed as follows:
```
server-context/package/component
```
where
- server-context is the root naming context for the server where the component is installed. You can view and edit this setting in the Naming Services tab of the Server Properties window. The default for a new server is "/". If you specify an initial name context when initializing the ORB properties, then resolved names are assumed to be relative to the initial name context.
- package is the Jaguar package name in which the component is installed, as displayed in Jaguar Manager.
- component is the component name, as displayed in Jaguar Manager.
Call the NamingContext::resolve method to instantiate a factory object for the component.
Narrow the CORBA Object reference to a SessionManager::Factory instance.
Call the factory's create method and narrow the return value by calling the _narrow method in the class for the interface. The create method requires a username and password to authenticate the end user.

The example below instantiates a component "CPPArithmetic," installed in package "Tutorial," hosted on a server with a null root context. The username and password are Guest and GuestPassword, respectively. The component implements the IDL interface Tutorial::CPPArithmetic, and the code narrows the proxy object to that interface.

// Build a CosNaming::Name object that contains the
// name of the tutorial component, Tutorial/CPPArithmetic

name[0].id = CORBA::string_dup( component_name );
name[0].kind = CORBA::string_dup( "" );

// Obtain a factory for component instances by
// resolving the component name
cout << "Creating component instance for "
  << component_name << "\n\n";
obj = nc->resolve(name);
SessionManager::Factory_var arithFactory =
  SessionManager::Factory::_narrow(obj);

if (CORBA::is_nil(arithFactory)) {
  cout << "ERROR: Null component factory. " << tutorial_help ;
  return -1;
}

// Use the factory to create an instance, passing the
// username and password for authorization
Tutorial::CPPArithmetic_var arith =
  Tutorial::CPPArithmetic::_narrow
    ( arithFactory->create("Guest", "GuestPassword"));

// Verify that we really have an instance.
if (CORBA::is_nil(arith)) {
  cout << "ERROR: Null component instance. " << tutorial_help ;
  return -1;
}