Chapter 12 Creating CORBA Java Clients

Instantiating proxies with the CosNaming API

EAServer allows you to use the CosNaming API to instantiate proxies in your client applications. This technique is not recommended, because:

It requires use of deprecated SessionManager::Factory methods.
When run in standalone clients, the CosNaming classes are incompatible with 1.2 or later JDK classes. You can use the CosNaming API in server components running in a server that uses JDK 1.2 or a later JDK version.

You do not need to use the CosNaming API in clients to realize the benefits incurred by using logical component names. When you use the technique described in "Instantiating proxy instances", EAServer uses the CosNaming API to resolve component names in the implementation of the Session.lookup and Session.create methods.

The steps for resolving objects with CosNaming are as follows:

Step	What it does	Detailed explanation
1	Configure ORB properties, including the ORB runtime driver class and the EAServer naming server URL, then initialize the ORB runtime.	"Configuring and initializing the ORB runtime"
2	Instantiate the CORBA CosNaming naming service and obtain the initial naming context.	"Obtaining an initial naming context"
3	Resolve component names to proxy objects and narrow them to the stub interface.	"Instantiating proxy objects for EAServer components"

Initializing the ORB

Before you can call any other ORB methods, you must configure ORB properties and call the org.omg.CORBA.ORB.init method. "Configuring and initializing the ORB runtime" describes how to do this. In addtion, you must set the the com.sybase.CORBA.NameServiceURL property.

com.sybase.CORBA.NameServiceURL specifies the list of URLs with the host and port number for IIOP connectivity to the EAServer name servers for your application. Each URL takes the the form:

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

where

protocol is iiop or iiops . Use iiops if connecting to a secure IIOP port, and iiop otherwise.
hostname is the host machine name for the server that serves as the name server for your application. If omitted, the ORB uses a default host name. In Java applets, the default host name is the applet's download host. In Java applications, the default is localhost .
iiop-port is the IIOP port number for the server.
initial-context is the initial naming 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, the 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 servers, the cluster may use multiple name servers. In this case, specify the URLs 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/

If you do not set the com.sybase.CORBA.NameServiceURL, property, the default is assumed. Different defaults are used depending whether your client is a Java application or a Java applet. The applet default is:

iiop://download-host:9000/

which indicates that the EAServer ORB expects the name server to be available at port 9000 on the host from which the applet was downloaded, and that the initial naming context is the root context (/).

The default for applications is:

iiop://localhost:9000/

Obtaining an initial naming context

After initializing the ORB, call the ORB.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 EAServer component and service names to server-side objects.

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

import org.omg.CORBA.*;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;

public class myApplet extends Applet {

  ... deleted ORB initialization code ...
  NamingContext nc = null;
  org.omg.CORBA.Object objRef = null;
  try {
    objRef = orb.resolve_initial_references(
             "NameService");
    nc = NamingContextHelper.narrow(objRef);
  } catch (org.omg.CORBA.ORBPackage.InvalidName ine) {
    nc = null;
  }
  if (nc == null) {
    System.out.println("Error: Could not "
        + "instantiate CORBA naming context.");
    return;
  }

Introduction to CosNaming name resolution The initial NamingContext will have the name context that was specified in the com.sybase.CORBA.NameServiceURL ORB initialization property. Your client program invokes the NamingContext::resolve operation to obtain an instance of the EAServer authentication service as well as component instances.

EAServer's CosNaming implementation currently lacks support for the BindingIterator interface, which is used to browse the name hierarchy.

The NamingContext::resolve operation takes a CosNaming::Name parameter, which is a sequence of CosNaming::NameComponent structures. The Java definitions of these types and the NamingContext::resolve operation follow:

package org.omg.CosNaming;

class NameComponent {
  public String id;    // Represents a node in a name
  public String kind;  // Unused, can contain comment info

  // Construct a NameComponent instance with the
  // specified initial values for id and kind fields
  public NameComponent(String id, String kind);
}

interface NamingContext {
  ... other methods not shown ...
  public org.omg.CORBA.Object resolve
   (NameComponent[] n)
   throws 
   org.omg.CosNaming.NamingContextPackage.NotFound,
   org.omg.CosNaming.NamingContextPackage.CannotProceed,
   org.omg.CosNaming.NamingContextPackage.InvalidName;

In Java, a name is represented by an array of NameComponent instances, with the id field of each instance set to a node of the name. For example, the name

USA/Sybase/Jaguar/TestPackage/TestComponent

can be represented by the array theName which is created in this code fragment:

import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;

public class myApplet extends Applet {

  NamingContext nc;
  ... deleted code that retrieves initial NamingContext ...

  NameComponent theName[] = {
    new NameComponent("USA", ""), 
    new NameComponent("Sybase", ""),
    new NameComponent("Jaguar", ""),
    new NameComponent("TestPackage", ""),
    new NameComponent("TestComponent", "")
  } ;

To simplify your source code, the EAServer naming service allows you to specify multiple nodes of a name in one NameComponent instance, using a forward slash (/) to separate nodes. The name from the example above can be represented in a one-element array as shown below:

  NameComponent theName[] = {
    new NameComponent(
      "USA/Sybase/Jaguar/TestPackage/TestComponent", "")
  };

NamingContext::resolve resolves a name to an object; this method either returns an org.omg.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.

The code fragment below illustrates a typical call with exception handling:

import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;

public class myApplet extends Applet {

  try {
    NamingContext nc;
    ... deleted code that retrieves initial NamingContext ...

    NameComponent theName[] = {
      new NameComponent(
        "USA/Sybase/Jaguar/TestPackage/TestComponent", ""));

    org.omg.CORBA.Object obj = nc.resolve(theName);

    ... deleted code that narrows the object to a supported          interface ...

  } catch (NotFoundException nfe) {
    ... report the error ...
  } catch (InvalidName ine ) {
    ... report the error ...
  } catch (CannotProceed cpe) {
    ... report the error ...
  }

Instantiating proxy objects for EAServer components

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 specified an initial name context when initializing the ORB properties, then resolved names are assumed to be relative to the initial name context. For example, if your client program specifies an initial context of /USA/Sybase, and your server's root context is USA/Sybase/Engineering, then you can resolve component names as Engineering/package/component.
- package is the EAServer 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. It returns a factory object for the component. You can use the factory to create proxy objects.
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 generated helper class for the interface. The create method requires a username and password to authenticate the end user.

The example below instantiates a component MyComponent, installed in package MyPackage, hosted on a server with initial context USA/Sybase/Jaguar. The username and password are Guest and GuestPassword, respectively. The component implements the IDL interface MyPackage::MyInterface, and the code narrows the proxy object to that interface.

import org.omg.CORBA.*;
import org.omg.CosNaming.*;
import org.omg.CosNaming.CosNamingPackage.*;
import SessionManager.*;

public class myApplet extends Applet {

  NamingContext nc;

  ... deleted code that created initial naming context 
       ...

  // Create a NameComponent array for 
  // USA/Sybase/Jaguar/MyPackage/MyComponent
  // 
  NameComponent compName[] = {
    new NameComponent("USA", ""), 
    new NameComponent("Sybase", ""),
    new NameComponent("Jaguar", ""),
    new NameComponent("MyPackage", ""),
    new NameComponent("MyComponent", "")

  try {
    // Resolve the name to obtain the proxy object
    org.omg.CORBA.Object obj = nc.resolve(compName);

    // Narrow to a factory instance
    Factory compFactory = FactoryHelper.narrow(obj);

    // Get the proxy object and narrow it to MyInterface.
    obj = compFactory.create("Guest", "GuestPassword");
    MyPackage.MyInterface comp = 
        MyPackage.MyInterfaceHelper.narrow(obj);
  } 
  catch (NotFoundException nfe) {
     ... report the error ...
  }
  catch (CannotProceed cpe) {
     ... report the error ...
  }
  catch (InvalidName ine) {
     ... report the error ...
  }
}