Chapter 12 Creating CORBA Java Clients

Instantiating proxy instances

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

Your program must obtain proxy objects for the EAServer 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 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 EAServer 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 API, however, the technique described in this section is recommended. See "Instantiating proxies with the CosNaming API".

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. Table 12-2 describes the EAServer ORB properties.

Table 12-2: EAServer Java ORB properties
Property	Specifies
`org.omg.CORBA.ORBClass`	The class that implements interface org.omg.ORB. Specify `com.sybase.CORBA.ORB` to indicate the EAServer ORB driver class. There is no default for this property.
`com.sybase.CORBA.forceSSL`	If set to true when using a a reverse proxy server, forces use of SSL for the connection to the reverse proxy. Set this property to true if the connection to the reverse proxy must use SSL (HTTPS) tunnelling, but the connection from the proxy to the server does not use SSL tunnelling. See the EAServer Security Administration and Programming Guide for more information on connecting to EAServer through proxy servers.
`com.sybase.CORBA.GCInterval`	Specifies how often the ORB forces deallocation (Java garbage collection) of unused class references. Though this property is set on an individual ORB instance, it affects all ORB instances. The default is 30 seconds. The default is appropriate unless you have set an idle connection timeout of less than 30 seconds. In that case, you should specify a lower value for the garbage collection interval, since connections are only closed while performing garbage collection. In other words, the effective idle connection timeout ranges from the idle connection timeout setting to the smallest integral multiple of the garbage collection interval.
`com.sybase.CORBA.http`	Specify whether the ORB should use HTTP tunnelling without trying to use plain IIOP first. The default is false. With the default setting, the ORB tries to open a connection using plain IIOP, and switches to HTTP tunnelling if the plain IIOP connection is refused. The default is appropriate when some users connect through firewalls that require tunnelling and others do not; the same application can serve both types. If you know tunnelling is required, set this property to true. This setting eliminates a slight bit of overhead that is incurred by trying plain IIOP connections before tunnelling is used.
`com.sybase.CORBA. HttpExtraHeader`	An optional setting to specify what extra information is appended to the header of each HTTP packet when connecting through a Web proxy. See the EAServer Security Administration and Programming Guide for more information.
`com.sybase.CORBA.http. jaguar35Compatible`	When set to true, specifies that HTTP tunnelling must be compatible with servers running EAServer version 3.5 or older installations. The default is false. Compatibility with version 3.5 or older servers The default tunnelling model is incompatible with servers older than version 3.6. If you do not set the `com.sybase.CORBA.http.jaguar35Compatible` property to true, clients using the EAServer 3.6 or later Java client ORB cannot connect to older-version servers using HTTP tunnelling. Note that HTTP tunnelling may happen automatically when clients connect to the server through firewalls.
`com.sybase.CORBA. HttpUsePost`	When using HTTP tunnelling, specifies the HTTP request type used. A value of true indicates that POST requests are to be used. A value of false (the default) specifies that GET requests are to be used. Some Web browsers cannot handle the long URLs generated when using HTTP tunnelling with GET requests. Setting this property to true can work around the issue.
`com.sybase.CORBA. IdleConnectionTimeout`	Specifies the time, in seconds, that a connection is allowed to sit idle. When the timeout expires, the ORB closes the connection. The default is 0, which specifies that connections can never timeout. The connection timeout does not affect the life of proxy instance references; the ORB may close and reopen connections transparently between proxy method calls. Specifying a finite timeout for your client applications can improve server performance. If many instances of the client run simultaneously, a finite client connection timeout limits the number of server connections that are devoted to idle clients. A finite timeout also allows rebalancing of server load in an application that uses a cluster of servers. If you specify an idle connection timeout, make sure the garbage collection interval (`com.sybase.CORBA.GCInterval` ) is set to an equal or lesser value.
`com.sybase.CORBA.isApplet`	Specifies whether the client is a Java applet. The default is `false` unless the ORB is initialized by calling the Orb.init method that takes a java.applet.Applet instance as a parameter. If you call another version of init from a Java applet, you must set this property to `true` in order to connect to EAServer using SSL.
`com.sybase.CORBA.local`	For server-side component use only. Specifies whether the ORB reference can be used to issue intercomponent calls in user-spawned threads. The default is `true` , which means that intercomponent calls are made in memory and must be issued from a thread spawned by EAServer. Set this property to `false` if your component makes intercomponent calls from user-spawned threads. com.sybase.CORBA.local property is deprecated This property is not needed when calling components from threads spawned by the the Thread Manager. The Thread Manager is the recommended way to spawn threads in Java components. See Chapter 30, "Using the Thread Manager" for more information.
`com.sybase.CORBA.ProxyHost`	Specifies the machine name or the IP address of a reverse-proxy server. See the EAServer Security Administration and Programming Guide for more information.
`com.sybase.CORBA.ProxyPort`	Specifies the port number of a reverse-proxy server. See the EAServer Security Administration and Programming Guide for more information.
`com.sybase.CORBA.RetryCount`	Specify the number of times to retry when the initial attempt to connect to the server fails. The default is 5.
`com.sybase.CORBA.RetryDelay`	Specify the delay, in milliseconds, between retry attempts when the initial attempt to connect to the server fails. The default is 2000.
`com.sybase.CORBA. socketReuseLimit`	Specify the number of times that a network connection may be reused to call methods from one server. The default is 0, which indicates no limit. The default is ideal for short-lived clients. The default may not be appropriate for a long-running client program that calls many methods from servers in a cluster. If sockets are reused indefinitely, the client may build an affinity for servers that it has already connected to rather than randomly distributing its server-side processing load among all the servers in the cluster. In these cases, the property should be tuned to best balance client performance against cluster load distribution. In Sybase testing, settings between 10 and 30 proved to be a good starting point. If the reuse limit is too low, client performance degrades.
`com.sybase.CORBA. WebProxyHost`	The host name or IP address of an HTTP proxy server that supports generic Web tunnelling, sometimes called connect-based tunnelling. See the EAServer Security Administration and Programming Guide for more information. There is no default for this property, and you must specify both the host name and port number properties.
`com.sybase.CORBA. WebProxyPort`	When generic Web tunnelling is enabled (`com.sybase.CORBA.WebProxyHost` is true), this property specifies the port number at which the HTTP proxy server accepts connections. See the EAServer Security Administration and Programming Guide for more information. There is no default for this property, and you must specify both the host name and port properties.
`com.sybase.CORBA. useJSSE`	Use the Java Secure Sockets Extension (JSSE) classes for secure HTTP tunnelled (HTTPS protocol) connections. JSSE provides an alternative to the built-in SSL implementations when secure connections are needed from an applet running in a Web browser. Additional configuration may be required to use this option. See the EAServer Security Administration and Programming Guide for more information.

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 EAServer authentication service implements the SessionManager::Manager interface. 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. EAServer 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 server. IOR strings in URL format must have the form:

protocol://host:iiop_port

where

protocol is iiops if connecting to a secure port and iiop otherwise.
host is the EAServer host address or machine name. 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.
iiop_port is the port number for IIOP requests. Your server may accept IIOP connections at several different ports, each of which uses a diffferent security profile. For example, the default server configuration provides listeners at these ports:
- 9000 accepts unsecure IIOP connections.
- 9001 accepts IIOPS connections with encryption and server-side authentication.
- 9002 accepts IIOPS connections with encryption and mutual (client and server) authentication. Mutual authentication requires that your end users have valid digital certificates, and that those certificates are issued by a certificate authority that is trusted by the server.
The EAServer Security Administration and Programming Guide describes how to configure listeners and security profiles.

An example URL-format IOR is iiop://machina:9000 , which specifies that the 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 server prints a hex-encoded IOR string with standard encoding to the following files in the EAServer html subdirectory:

<listener><iiop-version>.ior - Contains the IOR string by itself, followed by a newline.
<listener>_<iiop-version>_param.ior - Contains the IOR as part of an HTML param definition that can be inserted into an applet section.

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 server will generate the following files for a listener named iiops2. All files are created in the html subdirectory:

iiops2_10.ior
iiops2_11.ior
iiops2_10_param.ior
iiops2_11_param.ior

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 EAServer via HTTP and downloads one of the generated .ior files.

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 EAServer 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 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 EAServer. 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 EAServer 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 EAServer 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 "Naming Services" in the EAServer 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:

NO_PERMISSION The user is not authorized to instantiate the requested component.
OBJECT_NOT_EXIST The server component cannot be instantiated. Verify that:
- The specified component is installed in the specified Jaguar Manager package.
- The specified Jaguar Manager package is installed in the server.
- The Java class, Windows DLL, or UNIX shared library that implements the component is available.
- If you are instantiating a Java component, the component's skeleton class is available.

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 EAServer 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 ...
  }