Chapter 13 Creating CORBA-Compatible Java Clients

Instantiating proxy instances

After you have compiled stub classes, you can implement code that uses the stubs to interact with Jaguar components.

Your program must obtain proxy objects for the Jaguar component and narrow them to the stub interface that you intend to use by following the steps below:

Step

What it does

Detailed explanation

1

Initialize the CORBA ORB classes.

"Configuring and initializing the ORB runtime"

2

Use an IOR string and the ORB.string_to_object method to obtain the Manager instance for the Jaguar server.

"Creating a Manager instance"

3

Use the Manager instance to create a Session.

"Creating Sessions"

4

Call the Session's lookup method to create proxy objects, then narrow them to an interface that the component supports. The lookup method uses the Jaguar name service to resolve the requested name to an installed component.

"Creating stub instances"

5

Call the stub methods to remotely invoke component methods.

"Executing component methods"

Java exceptions can occur at any step. "Handling exceptions" describes common exceptions and their cause.

You can also instantiate proxies using the CosNaming or JNDI naming APIs, however, the technique described in this section is recommended. See "Using client-side naming interfaces".

Configuring and initializing the ORB runtime

ORB properties define the class name of the ORB driver that will be used, and configure settings required by the driver. Properties can be set externally in HTML parameters for a Java applet or in command-line arguments for a Java application. You can also set them directly in your source code in both applets and applications.

The Jaguar ORB driver requires the following properties:

Example: ORB Initialization in an Applet ORB initialization for a Java applet is demonstrated in the example below. This code constructs a java.util.Properties object and sets the required properties. The applet reference and the Properties object are passed to the org.omg.CORBA.ORB.init method. 

import java.applet.*;
import org.omg.CORBA.*;
public class myApp extends Applet {

  public void init() {
    ...
    java.util.Properties props 
        = new java.utils.Properties();
    props.put("org.omg.CORBA.ORBClass",
       "com.sybase.CORBA.ORB");
    ORB orb = ORB.init(this, props);
    ...

Rather than property values, you can pass properties to the ORB as parameters in the HTML APPLET tag that loads the applet, as in the example below:

<APPLET 
codebase=....
<param name="org.omg.CORBA.ORBClass" 
  value="com.sybase.CORBA.ORB">
... 
</APPLET>

A property setting that is passed as an applet parameter supersedes any setting that is specified in the java.utils.Properties parameter to the ORB.init method. If you want to ensure that hard-coded property values are used, pass the Applet parameter as null.

Example: ORB Initialization in an Application ORB initialization for a Java application is demonstrated in the example below. This code constructs a java.util.Properties object and sets the required properties. The command-line parameters are passed to the org.omg.CORBA.ORB.init method. 

import java.util.*;
public class myApp extends Object {

  public static void main(String[] args) 
     throws Exception 
{
    ...
    Properties props = new Properties();
    props.put("org.omg.CORBA.ORBClass",
       "com.sybase.CORBA.ORB");
     ORB orb = ORB.init(args, props);
    ...

Rather than hard-coding the property values, you can pass them to the ORB as command-line parameters, as in the example below:

java yourclass -org.omg.CORBA.ORBClass com.sybase.CORBA.ORB

Properties that are specified as command-line parameters supersede values specified in the java.utils.Properties parameter to the ORB.init method. If you want to ensure that hard-coded property values are used, pass the String[ ] parameter to init as null.

Creating a Manager instance

The Jaguar authentication service implements the SessionManager::Manager interface is used for interacting with a Jaguar server. When using CORBA naming services, you can resolve this object by using the special name AuthenticationService. Without using naming services, you must supply a CORBA Interoperable Object Reference (IOR), which is a text string that describes how to connect to the server hosting the object.

Standard CORBA IOR strings are hex-encoded and not human-readable. Jaguar supports both standard format IORs and a URL form that is human-readable. For information on standard-format IORs, see "Instantiating components using a third-party ORB".

URL format IORs The URL string format offers the benefits of being human-readable. Also, for Java applets, you can create URL strings that connect to the applet's download host by default; this feature simplifies deployment since you do not need to change hard-coded IORs when you move your application to another Jaguar server. IOR strings in URL format must have the form:

protocol://host:iiop_port

where

An example URL-format IOR is iiop://machina:9000 , which specifies that the Jaguar server runs on the machine named "machina" and listens for IIOP requests on port 9000. In an applet, you can omit the host name to specify that the connection must go to the host from which the applet was downloaded. For example, iiop://:9000 specifies a connection to port 9000 on the applet's host.

Standard format IORs Use the standard IOR format if you must have portability to other standard Java ORB implementations. Your server generates IOR strings embedded within text files each time it starts. Several files are generated for each IIOP listener. There are files formatted as an HTML param tag; these can be used to compose HTML applet sections. There are also files that contain the IOR by itself. Additionally, there are different files generated for compatibility with different IIOP protocol versions.

For each listener, the Jaguar server prints a hex-encoded IOR string with standard encoding to the following files in the Jaguar HTML subdirectory:

where

<listener> is the name of the listener.

<iiop-version> is the version of IIOP and can be either 10 (which represents IIOP version 1.0) or 11 (which represents IIOP version 1.1). Use the file that matches the IIOP version that is supported by your client ORB.

For example, a Jaguar server will generate the following files for a listener named iiops2. All files are created in the html subdirectory:

Your applet can retrieve the IOR if you supply it in applet parameters. In this case, you can copy the contents of one of the param format files to the HTML file. Alternatively, you can add code that connects to Jaguar via HTTP and downloads one of the generated .ior files.

Note   If you change a server's host name or port number, you must edit or replace IOR values that contain the host name, including hex-format IORs copied from the server-generated .ior files. When using the Jaguar ORB, use the URL string format and omit the host name. When using another vendor's ORB, you can download the contents of a generated .ior file, or you can store Jaguar server IORs in the ORB vendor's name server.

Creating the Manager instance Once the applet or application has obtained the server's IOR string or an equivalent IIOP URL string, it calls the ORB.string_to_object method to convert the IOR string into a SessionManager::Manager instance, as shown in the following example:

import org.omg.CORBA.*;
import java.awt.*;
import SessionManager.*;

public class myApplet extends Applet {
  String ior;
  ORB orb;
  ... deleted ORB.init() code and code that 
      retrieves IOR from applet parameters ...
  Manager manager = ManagerHelper.narrow(
                   orb.string_to_object(ior));

Creating Sessions

The SessionManager.Session interface represents an authenticated session between the client application and a Jaguar server. The Manager.createSession method accepts a user name and password and returns a Session object, as shown in the example below:

import org.omg.CORBA.*;
import SessionManager.*;
import java.awt.*;

public class myApplet extends Applet {
  Manager manager;

  ... deleted code that created Manager instance
      ...
  try {
    Session session = manager.createSession(user, 
                                         password);
  }
  catch (org.omg.CORBA.COMM_FAILURE cf)
  {
     // The server is likely down or has run 
     // out of connections. You can retry the
     // connection if desired.
     ... report the error ...
  }
  catch (org.omg.CORBA.NO_PERMISSION np)
  {
    // Tell the user they are not authorized
    ...
  }
  catch (org.omg.CORBA.SystemException se)
  {
    // Catch-all clause for any CORBA system
    // exception that was not explicitly caught
    // above. Report the error but don't bother
    // retrying.
    ...
  }

Creating stub instances

A Java stub implements the Java version for one of the Jaguar component's IDL interfaces. Call the Session.lookup method to obtain a factory for stub instances. The signature of Session.lookup is:

SessionManager.Factory lookup(String name)

Session.lookup takes a string that specifies the name of the component to instantiate. A component's default name is the Jaguar package name and the component name, separated by a slash as in calculator/calc. However, a different name can be specified with the component's com.sybase.jaguar.component.naming property. For example, you can specify a logical name, such as USA/MyCompany/FinanceServer/Payroll. For more information on configuring the naming service, see "Jaguar Naming Services" in the Jaguar CTS System Administration Guide.

Session.lookup returns a factory for component proxies. Call the Factory.create method to obtain proxies for the component. This method returns a org.omg.CORBA.Object reference. You must call the narrow method in the IDL interface's generated helper class to convert this to an instance of the stub class for the component's IDL interface. If the component instance does not implement the requested interface, the narrow method returns a null object reference.

Session.lookup can throw these CORBA standard exceptions:

The code to call Session.lookup and Factory.create looks like this:

import org.omg.CORBA.*;
import SessionManager.*;
import java.awt.*;
import Calculator.*;  // Package for Java stubs
                      // for this example, matches
                      // IDL module name for the 
                      // component's interface.

public class myApplet extends Applet {

  Session session;

  ... deleted code that created Session instance
      ...

  //
  // In this example, the component is named calc
  // and is installed in the Jaguar package
  // calculator. calcHelper.narrow() verifies that
  // the returned object is of the appropriate
  // type, then returns a Calculator.Calc instance
  //
  try {
    Factory fact = 
      FactoryHelper.narrow(
        session.lookup("calculator/calc"));
    Calc c = 
      CalcHelper.narrow(factory.create());
  } 
  catch (org.omg.CORBA.OBJECT_NOT_EXIST one)
  {
    // Tell the user to contact the server
    // administrator
    ... report the error ...
  }
  catch (org.omg.CORBA.NO_PERMISSION np)
  {
    // Tell the user they are not authorized
    ... report the error ...
  }
  catch (org.omg.CORBA.SystemException se)
  {
    // Catch-all clause for any CORBA system
    // exception that was not explicitly caught
    // above. 
    ... report the error ...
  }




 



Copyright © 2000 Sybase, Inc. All rights reserved.