Previous     Contents     Index     Next     
iPlanet Application Server Developer's Guide



Chapter 10   Developing and Deploying CORBA-Based Clients


This chapter explains how to access to EJBs via the IIOP (RMI or IDL over IIOP) protocol within an iPlanet Application Server environment.

This chapter contains the following sections:



Overview of CORBA Client Support

iPlanet Application Server supports access to EJBs via the IIOP protocol as specified in the Enterprise JavaBeans Specification, V1.1, and the Enterprise JavaBeans to CORBA Mapping specification. These clients use JNDI to locate EJBs and use Java RMI/IIOP to access business methods of remote EJBs, or they use C++ with IIOP to access business methods of remote EJBs.

The following topics are covered in this overview:


Scenarios

The most common scenarios in which CORBA clients are employed are when either a stand-alone program or another application server acts as a client to EJBs deployed to iPlanet Application Server.


Stand-Alone Program

In the simplest case, a stand-alone program running on a variety of operating systems uses IIOP to access business logic housed in back-end EJB components, as shown in Figure 10-1.

Figure 10-1    Stand-alone program




Server-to-Server

Web servers, CORBA objects, and even other application servers can use IIOP to access EJBs housed in an iPlanet Application Server, as shown in Figure 10-2.

Figure 10-2    Server-to-server




Architectural Overview

CORBA client support in iPlanet Application Server involves a specialized Java Engine process named the CORBA Executive Server (CXS). The CXS acts as a bridge between Java or C++ clients using IIOP and EJBs deployed to one or more Java Engines acting as EJB containers. For every EJB accessed by CORBA clients, the IIOP Bridge process handles the incoming IIOP-based requests and maps these requests to internal calls to EJBs housed within the EJB containers, as shown in Figure 10-3.

Figure 10-3    Architecture



In this release of iPlanet Application Server, you can use the ORB that is bundled as part of the Application Server, or you can use a third-party ORB (ORBIX 2000).


Note The bundled iPlanet ORB will not work with JDK 1.2 or earlier, or with earlier versions of iPlanet Application Server.



iPlanet Value-Added Features

iPlanet's implementation of CORBA clients goes beyond the specification by providing the following value-added features:


Naming Services

The CORBA clients use the standard CORBA COS Naming Service to resolve EJBHome objects. As EJBs are deployed to iPlanet Application Server, they are automatically and dynamically registered in the naming service.


C++ Client Support

C++ clients using IIOP are supported for Unix systems in this release of iPlanet Application Server. For more information, see "C++ IIOP Client Applications (Unix Only)".


Built-in ORB and Third Party ORB Support

iPlanet provides a built-in ORB to support IIOP access to EJBs. You can also install and configure a third party ORB (ORBIX 2000) to use IIOP with iPlanet Application Server. For more information, see "Choosing the ORB".


Basic Authentication and EJB Container Integration

Although the CORBA standards do not yet define a means of performing basic authentication between a CORBA client and an EJB server, iPlanet provides such support in the Application Server. This feature enables the EJB deployer to control access to EJBs using standard declarative and programmatic controls that apply to both web and CORBA clients.

As a CORBA client authenticates to the iPlanet Application Server, the principal information is automatically propagated to the EJB container for authorization based on the standard EJB security mechanisms. To trigger collection of the client's user name and password, iPlanet provides a client-side callback mechanism that enables an application to obtain a user name and password through application-specific means. Once the user name and password information is collected by the iPlanet CORBA infrastructure, this information is propagated over IIOP to the Application Server.


Client Side Authentication

If ORBIX 2000 is the ORB used for RMI/IIOP, portable interceptors implement security by providing hooks, or interception points, which define stages within the request and reply sequence. Services can use these interception points to query request and reply data, and to transfer service contexts between clients and servers.

There are two interceptors, one each on the client side and server side. The client interceptor intercepts the request before it is sent to the server, then checks whether the Principal class (which implements com.netscape.ejb.client.IUserPrincipal) is set. If it is set, the interceptor instantiates the class and calls the setPrincipal method. Inside the setPrincipal method, userId and password instance variables should be set; you can implement custom code inside this method for getting the user ID and password. The client interceptor uses the corresponding accessor methods to retrieve these values.

Subsequently, these values are stored in the PICurrent object (which is a table of slots). Separate slots are created in the PICurrent object for storing the user ID and password. Subsequently, the client interceptor creates the service contexts, one each for user ID and password, and adds them to the request before sending it. The user ID and password are stored in the PICurrent object in the first request. For subsequent requests, they are retrieved from the PICurrent object.

If the Principal class is not set, the request is sent unchanged, and no service context data is added.

On the server side, upon receipt of the request, the server interceptor is invoked. The server interceptor checks whether service context data is present in the request. If it is not present, the request is allowed to proceed further. If service context data is present, the server interceptor extracts the user ID and password and calls the login method of the security manager. This method authenticates the user. If authentication fails, an exception is sent back to the client. If it succeeds, the request is allowed to proceed further.


Note When authentication/authorization fails, java.rmi.AccessException is thrown to the client. java.rmi.AccessException is derived from java.rmi.RemoteException.


On both the server and client side, the interceptors must be registered using the ORBInitializer class for this functionality to take effect. The ORBInitilaizer class on client side also creates the PICurrent object.

Role mapping is done at the method or bean level for controlling the access. The EJB container retrieves the role mapping information from the security manager to authorize access to the method or bean. If the user is authorized, the method is executed. Otherwise an java.rmi.AccessException is thrown.


Load Balancing

As new IIOP requests arrive at an instance of iPlanet Application Server, the Application Server load balances these requests against one or more JVMs acting as EJB containers. Load balancing is implemented in a simple round-robin scheme. Upon startup, the application server obtains a list of the available EJB container processes, also known as Java Engines. As home lookup requests arrive from CORBA clients, the Application Server uses a list of engines to select the target engine on which an EJB home is hosted. Subsequent lookups for that EJB home, bean creations on that home, and business method invocations on the created beans go to the same target engine.


Client-Side Load Balancing
If the built-in iPlanet ORB is used, client applications can rotor through a list of the available CORBA processes or use round-robin DNS to implement basic, client-side load balancing.

If ORBIX 2000 is the ORB used, other client-side load balancing options are available. The naming service defines a repository of names that map to objects. A name maps to one object only. ORBIX 2000 extends the naming service model to allow a name to map to a group of objects. An object group is a collection of objects that can increase or decrease in size dynamically. Each object group has a selection algorithm. This algorithm is applied when a client resolves the name associated with the object group. Three algorithms are supported:

  • Round-robin selection

  • Random selection

  • Active load balancing selection

Object groups provide a way to replicate frequently requested objects and thereby distribute the request-processing load. The naming service directs client requests to the various replicated objects according to the object group's selection algorithm. The existence of an object group is transparent to the client, which resolves the object group name in the same way that it resolves any other name.


Scalability

Multiple CORBA processes can be configured for each application server instance. This feature enables system administrators to configure any number of JVMs dedicated to handling incoming IIOP requests. Administrators can modify the number of processing threads available for each CORBA and EJB container process to suit the expected loads of the system.


High Availability

The following features contribute to high availability:

  • Auto Restart of Java Engines: The application server monitors both the Bridge processes as well as the Java Engines supporting the EJB containers. If a process fails, administrative services automatically restart the failed process.

  • Stateful Session Bean Failover: CORBA clients can take advantage of the built-in EJB stateful session bean replication feature of iPlanet Application Server. If a Java Engine housing an EJB container fails, then subsequent requests to the stateful session bean continue to be processed once the Java Engine restarts.

  • EJB Handle and Object Reference Failover: If a Bridge process fails and is automatically restarted, the CORBA clients can continue to access EJBs without interruption.


Minimal Ports Opened in Firewalls

If the built-in iPlanet ORB is used, the Bridge process handles both name service and business method calls on a common, fixed IP port number. This approach helps to minimize the number of ports opened in firewalls positioned between CORBA clients and iPlanet Application Server instances on which Bridge processes are configured.


Limitations

CORBA client support in iPlanet Application Server has the following limitations:

  • It applies only to accessing EJBs.

  • General RMI objects cannot be accessed via RMI/IIOP.

  • Transaction propagation from Java RMI/IIOP clients is not supported.

  • When you are using JDK 1.3.x on the client side, only primitive data types can be exchanged.


Choosing the ORB

iPlanet provides a built-in ORB to support IIOP access to EJBs. You can also install and configure a third party ORB (ORBIX 2000) to use IIOP with iPlanet Application Server.

If your company uses ORBIX 2000 as its standard ORB, or if you wish to develop C++ clients that communicate with EJBs, you should configure iPlanet Application Server to use ORBIX 2000. ORBIX 2000 also offers additional authentication and load balancing options. For information about installing ORBIX 2000 and integrating it with iPlanet Application Server, see the Administrator's Guide.

For more information about configuring RMI/IIOP applications to use ORBIX 2000, see "Configuring RMI/IIOP Applications for ORBIX". For more information about configuring C++ IIOP applications to use ORBIX 2000, see "Configuring C++ IIOP Applications for ORBIX".



RMI/IIOP Client Applications


Using RMI/IIOP-based client applications with iPlanet Application Server is very similar to using clients with other J2EE-certified application servers. With minimal, if any, changes to the JNDI lookup section of your client, you can reuse your Java client to work with a variety of J2EE application servers.

The following topics are covered in this section:


Developing RMI/IIOP Client Applications

The following topics are covered in this section:


JNDI Lookup for the EJB Home Interface

One of the first steps in coding an RMI/IIOP client is to perform a lookup of an EJB's home interface. In preparation for performing a JNDI lookup of the home interface, you must first set several environment properties for the InitialContext. Then you provide a lookup name for the EJB.

The steps and an example are summarized in the following sections.


Specifying the Naming Factory Class
According to the RMI/IIOP specification, the client must specify com.sun.jndi.cosnaming.CNCtxFactory as the value of the java.naming.factory.initial entry in an instance of a Properties object. This object is then passed to the JNDI InitialContext constructor prior to looking up an EJB's home interface. For example:

...
Properties env = new Properties();
env.put("java.naming.factory.initial", "com.sun.jndi.cosnaming.CNCtxFactory");
env.put("java.naming.provider.url", "iiop://" + host + ":"+port);
Context initial = new InitialContext(env);
Object objref = initial.lookup("java:comp/env/ejb/MyConverter");
...


Specifying the Target IIOP Bridge
According to the RMI/IIOP specification, your client must set the java.naming.provider.url property to a value of the following form:

iiop://server:port

The server identifies the host on which an iPlanet Application Server instance resides. The port identifies a specific IIOP Bridge process running on the application server host.

Along with the java.naming.factory.initial property, you can specify the java.naming.provider.url property either on the command line or in the client application's code.

The following is an example of setting the IIOP URL on the Java command line (this command must be all on one line):

java -Djava.naming.provider.url="iiop://127.0.0.1 :9010" -Djava.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactory j2eeguide.cart.CartClient

In this case, the client application does not need to instantiate a Properties object:

...
public static void main(String[] args) {
   Context initial = new InitialContext();
   Object objref = initial.lookup("java:comp/env/ejb/MyConverter");
   ...
}

As an alternative, you can set the IIOP URL within the client application. In the following example, two command line arguments are passed into the main classes of the client.

...
public static void main(String[] args) {
   String host = args[0];
   String port = args[1];
   Properties env = new Properties();

   env.put("java.naming.factory.initial",
      "com.sun.jndi.cosnaming.CNCtxFactory");

   env.put("java.naming.provider.url", "iiop://" + host + ":"+port);

   Context initial = new InitialContext(env);
   Object objref = initial.lookup("java:comp/env/ejb/MyConverter");
...
}


Specifying the JNDI Name of an EJB
After creating a new JNDI InitialContext object, your client calls the lookup method on the InitialContext to locate the EJB's home interface. The name of the EJB is provided on the call to lookup. When using RMI/IIOP to access remote EJBs, the parameter is referred to as the "JNDI name" of the EJB. Depending on how your client application is packaged, the supported values of the JNDI name vary.


The JNDI Name Without an Application Client Container
When the client is not packaged as part of an Application Client Container (ACC), you must specify the absolute name of the EJB in the JNDI lookup. iPlanet supports the following approaches to performing the JNDI lookup outside of an ACC:

initial.lookup("ejb/ejb-name");

initial.lookup("ejb/module-name/ejb-name");

The ejb-name is the name of the EJB as it appears in the <ejb-name> element of the EJB's deployment descriptor. For example, here is a lookup using the value MyConverter:

initial.lookup("ejb/MyConverter");

This lookup requires that the EJB deployment descriptor specify MyConverter as the <ejb-name>, as follows:

<ejb-jar>
   <enterprise-beans>
      <session>
         <ejb-name>MyConverter</ejb-name>
         <home>j2eeguide.converter.ConverterHome</home>
         <remote>j2eeguide.converter.Converter</remote>
         ...
      </session>
   </enterprise-beans>
</ejb-jar>

Using only the ejb name in the JNDI lookup on the RMI/IIOP client works properly as long as only one EJB of this name is registered in the Application Server. If you have more than one EJB of this name registered, you must qualify the ejb name with the name of the EJB JAR module in which the EJB of interest exists. You can do this by including the module name in front of the ejb name in the JNDI lookup. The EJB JAR module name is the name of the EJB JAR file minus the .jar extension.

In the Converter sample application, since the EJB JAR module name is j2eeguide-converterEjb (based on the EJB JAR file name of j2eeguide-converterEjb.jar), a lookup based on the module name looks like this:

initial.lookup("ejb/j2eeguide-converterEjb/MyConverter");

The safe approach is to always use the module name qualifier when performing JNDI lookups from RMI/IIOP clients that do not use Application Client Container packaging. The only drawback of the module name approach is that the client becomes aware of additional aspects of the deployment structure of the server side environment beyond the absolute EJB name.

As of Service Pack 3, you can also use the prefix java:comp/env/ejb/ when performing lookups via absolute references. For example, the lookup in the Converter sample could be written as follows:

initial.lookup("java:comp/env/ejb/MyConverter");

Or, with a module name, it could be written as follows:

initial.lookup("java:comp/env/ejb/j2eeguide-converterEjb/MyConverter");

There is no mechanical difference between supplying this prefix and the first two approaches. You might find the java:comp/env/ejb/ confusing when used in conjunction with absolute EJB references because this notation is typically used when you are using indirect EJB references.


The JNDI Name When Using an Application Client Container
If you are using an Application Client Container (ACC) to house the client, the JNDI name can use the logical name of the EJB as specified in the <ejb-ref-name> element in the ACC deployment descriptor. This approach to specifying the JNDI name of an EJB, although dependent on packaging and running the client in the context of an ACC, is the same approach as used within a servlet or EJB housed within the Application Server.

As is the case for servlets and EJBs that perform lookups on EJBs, the format of the lookup must be as follows:

initial.lookup("java:comp/env/ejb/ejb-ref-name");

The ejb-ref-name is the value specified in the <ejb-ref-name> element of the ACC deployment descriptor.

In the following example, since SimpleConverter appears in the <ejb-ref-name> element of the ACC deployment descriptor, a value of SimpleConverter is used in the JNDI lookup:

initial.lookup("java:comp/env/ejb/SimpleConverter");

The application-client.xml file looks like this:

<application-client>
   <display-name>converter-acc</display-name>
   <description>
      Currency Converter Application Client Container Sample
   </description>
   <ejb-ref>
      <ejb-ref-name>SimpleConverter</ejb-ref-name>
      <ejb-ref-type>Session</ejb-ref-type>
      <home>j2eeguide.converter.ConverterHome</home>
      <remote>j2eeguide.converter.Converter</remote>
      <ejb-link>Test</ejb-link>
   </ejb-ref>
</application-client>

A benefit of using ACC packaging is that the JNDI names specified in the client application are indirectly mapped to the absolute JNDI names of the EJBs. However, this aspect is about the only real benefit of using ACC. See "Using Application Client Container (ACC)" for more details.


A JNDI Example
The following client program is taken from the Currency Converter application that is part of the J2EE Developer's Guide examples bundled in iPlanet Application Server. See "Sample RMI/IIOP Applications" for more information on the RMI/IIOP samples included with the application server.

package j2eeguide.converter;

import java.util.*;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.rmi.PortableRemoteObject;

import j2eeguide.converter.Converter;
import j2eeguide.converter.ConverterHome;

public class ConverterClient {

public static void main(String[] args) {
   try {

      if (args.length != 2) {
         System.out.println("Wrong number of arguments to client");
         System.exit(1);
      }
      String host = args[0];
      String port = args[1];
      Properties env = new Properties();
      env.put("java.naming.factory.initial",
         "com.sun.jndi.cosnaming.CNCtxFactory");
      env.put("java.naming.provider.url", "iiop://" + host
         + ":"+port);

      Context initial = new InitialContext(env);
      Object objref = initial.lookup("ejb/MyConverter");

// Alternatively, the module name could be used as a qualifier:.
// Object objref =
// initial.lookup("ejb/j2eeguide-converterEjb/MyConverter");

      ConverterHome home
         =(ConverterHome)PortableRemoteObject.narrow(objref,
         ConverterHome.class);

      Converter currencyConverter = home.create();

      double amount = currencyConverter.dollarToYen(100.00);

      System.out.println(String.valueOf(amount));

      amount = currencyConverter.yenToEuro(100.00);

      System.out.println(String.valueOf(amount));

   }

   catch (Exception ex) {
      System.err.println("Caught an unexpected exception!");
      ex.printStackTrace();
   }
}
}


Client Authentication

To take advantage of the optional authentication mechanism for RMI/IIOP clients, you must provide a security principal class that implements the com.netscape.ejb.client.IUserPrincipal interface. This class is instantiated once by the client side iPlanet RMI/IIOP infrastructure as the JNDI lookup method is called. The client side RMI/IIOP infrastructure calls the setPrincipal method of this interface before the JNDI lookup triggers a call to the remote name services.

The security principal class must be named in the client's properties and the class must be present in the client's CLASSPATH to enable the RMI/IIOP infrastructure to load the class during execution of the client.

For example, in the Converter sample application, you could add a third property specifying the security principal class to be instantiated as the JNDI lookup is performed:

...
Properties env = new Properties();
env.put("java.naming.factory.initial",
   "com.sun.jndi.cosnaming.CNCtxFactory");
env.put("java.naming.provider.url", "iiop://" + host + ":"+port);
env.put("com.netscape.ejb.client.PrincipalClass",
   "j2eeguide.converter.RmiPrincipal");

Context initial = new InitialContext(env);
Object objref = initial.lookup("ejb/MyConverter");
...

The RmiPrincipal class is the class that you develop that implements the com.netscape.ejb.client.IUserPrincipal interface.


Sample Principal Class
The IUserPrincipal interface can be implemented in several ways. The simplest is to pop up a dialog in the setPrincipal callback to capture a user/password pair and store them in the username and password private string fields. Then, whenever an EJB invocation occurs from the client, the getUserId and getPassword methods are used to set the security context propagated by the client.

The IIOP Bridge attempts to authenticate the user and password with the iPlanet Application Server security manager. If an authentication exception occurs in Bridge the client side ORB is notified and the setPrincipal method is called to obtain the correct user/password information. The client side RMI/IIOP infrastructure retries the request automatically three times, after which an authentication exception is generated on the client side.

...
import com.netscape.ejb.client.IUserPrincipal;

public class Principal implements IUserPrincipal {

   private String username;
   private String password;

   public void setPrincipal() {
      // Pop up GUI to take user name and password
   }

   public String getUserId() {
      return username;
   }

   public String getPassword() {
      return password;
   }
}

Another valid implementation of IUserPrincipal supports multiple user identities in the same client JVM. This is done by using ThreadLocal variables to store the user name and password. In this case, the methods in the IUserPrincipal implementation must to be ThreadLocal aware.


Client-Side Load Balancing and Failover

Although iPlanet Application Server provides server-side load balancing and failover for RMI/IIOP access, you may consider implementing client side approaches to further enhance the performance and availability of your application.


iPlanet ORB Configuration
If you are using the built-in iPlanet ORB, you can configure client-side load balancing in these ways:

  • Manual Selection from the List of Known Bridges

    You can create a wrapper class to round-robin through a set of known bridge host name and port combinations on behalf of the client business application. If a communication exception occurs for one of the host name and port combinations, the wrapper class attempts to use the next host name and port combination in the list.

    For example, the following exception is thrown by the underlying client classes when the remote IIOP Bridge cannot be contacted:

    javax.naming.CommunicationException: Cannot connect to ORB. Root exception is org.omg.CORBA.COMM_FAILURE:

    Your client wrapper code can catch this exception and select the next available host_name:port pairing to re-attempt access to the EJB.

  • Round Robin DNS

    To implement a simple load balancing scheme without making source code changes to your client, you can leverage the round-robin feature of DNS. In this approach, you define a single virtual host name representing multiple physical IP addresses on which IIOP Bridge processes are listening. Assuming that you configure all of the IIOP Bridge process to listen on a common IIOP port number, the client application can use a single host_name:IIOP_port during the JNDI lookup. The DNS server resolves the host name to a different IP address each time the client is executed.

    After developing the client application, you must package your application in preparation for deployment.


ORBIX Configuration
If ORBIX 2000 is the ORB used, other client-side load balancing options are available. The naming service defines a repository of names that map to objects. A name maps to one object only. ORBIX 2000 extends the naming service model to allow a name to map to a group of objects. An object group is a collection of objects that can increase or decrease in size dynamically. Each object group has a selection algorithm. This algorithm is applied when a client resolves the name associated with the object group. Three algorithms are supported:

  • Round-robin selection

  • Random selection

  • Active load balancing selection

Object groups provide a way to replicate frequently requested objects and thereby distribute the request-processing load. The naming service directs client requests to the various replicated objects according to the object group's selection algorithm. The existence of an object group is transparent to the client, which resolves the object group name in the same way that it resolves any other name.

For Unix, you can set the flag ORBIX_LOADBALANCING=true or false in the iasenv.ksh file, which sets the Java argument as follows:

-DORBIXLoadBalancing=$ORBIX_LOADBALANCING

For Windows, you can set the Java argument in the registry as follows:

HKEY_LOCAL_MACHINE\SOFTWARE\iPlanet\Application Server\6.5\Java\JavaArgs=-DORBIXLoadBalancing=true


Packaging RMI/IIOP Client Applications

You can package RMI/IIOP Client Applications in these ways:


Using the Assembly Tool GUI

The iPlanet Application Server Deployment Tool automatically generates a JAR file containing EJB-specific home and remote interface and stub classes when you indicate that an EJB is accessible via IIOP. As an alternative to copying individual class files to the client, this JAR file can be deployed as part of the client application.

The Deployment Tool does not support packaging of applications to be deployed as part of an Application Client Container.


Automating Reassembly Using Ant

If you have an interest in a command line means of packaging RMI/IIOP client applications, it is recommended that you review the Ant-based build.xml files supplied as part of the sample applications. The build.xml files for RMI/IIOP-based samples contain an install_client target that can be easily enhanced to assemble a self-contained client JAR file in much the same manner as the Deployment Tool creates a JAR file of client-oriented classes.


Using Application Client Container (ACC)

Although iPlanet does not recommend deployment of client applications in Application Client Containers, this deployment and runtime method is supported as part of the J2EE specification. This approach is not recommended because, in the current state of the ACC specification, using ACC introduces additional complexity with minimal benefit. Furthermore, due to the limited definition of ACC within the J2EE v1.2, support for ACC varies widely across J2EE application servers.

If you choose to experiment with ACC on iPlanet Application Server, take the following deployment steps into consideration:

  • The iasacc.jar JAR file supplied as part of iPlanet Application Server must be in the client's CLASSPATH. This file can be copied from the following location to the client environment:

    install_dir/ias/classes/java/iasacc.jar

    Including this file eliminates the need to include the iasclient.jar file in the client's environment.

  • A J2EE v1.2-compliant EAR file needs to be created. This EAR file must contain:

    • The RMI/IIOP client application classes, home and remote interfaces and stubs.

    • A J2EE v1.2 XML descriptor file named app-client.xml. For example:

      <?xml version="1.0" encoding="UTF-8"?>

      <!DOCTYPE application-client PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application Client 1.2//EN' 'http://java.sun.com/j2ee/dtds/application-client_1_2.dtd'>

      <application-client>
         <display-name>converter-acc</display-name>
         <description>
         Currency Converter Application Client Container Sample
         </description>
         <ejb-ref>
            <ejb-ref-name>SimpleConverter</ejb-ref-name>
            <ejb-ref-type>Session</ejb-ref-type>
            <home>j2eeguide.converter.ConverterHome</home>
            <remote>j2eeguide.converter.Converter</remote>
            <ejb-link>Test</ejb-link>
         </ejb-ref>
      </application-client>

    • An iPlanet Application Server specific XML descriptor file (typically named ias-app-client.xml). This descriptor maps EJB references to absolute EJB names.

      <?xml version="1.0" encoding="UTF-8"?>

      <!DOCTYPE ias-java-client-jar PUBLIC '-//Sun Microsystems, Inc.//DTD iAS Enterprise JavaBeans 1.0//EN' 'http://developer.iplanet.com/appserver/dtds/IASjava_client_jar_1_0.dtd'>

      <ias-java-client-jar>
         <ejb-ref>
            <ejb-ref-name>SimpleConverter</ejb-ref-name>
            <jndi-name>ejb/MyConverter</jndi-name>
         </ejb-ref>
      </ias-java-client-jar>

    • A J2EE v1.2 XML descriptor file named application.xml.

    For more information about the structure of an RMI/IIOP client EAR file, see Chapter 11 "Packaging for Deployment."


    Note EJB JAR names identified by the first portion of their filenames (without the .jar extensions) must be unique when deploying to the Application Server. Use a Java package-like naming scheme for EAR filenames and EJB names as found in the <ejb-name> portion of the ejb-jar.xml files; this ensures that name collisions do not occur. The benefits of this naming practice apply not only to the iPlanet Application Server, but to other J2EE application servers as well.


To invoke the client through the Application Client Container, use the following command:

java com.netscape.ejb.client.AppContainer client_ear_file -iasXml ias_xml_file


Configuring RMI/IIOP Support

To enable RMI/IIOP access to EJBs deployed to iPlanet Application Server, you must configure both the Application Server and client environments, as described in these sections:

The following configuration steps are required only once; they do not need to be repeated as you deploy EJBs and client applications.


Server Configuration

If your installation of iPlanet Application Server does not already have the IIOP Bridge process configured, you must start the iPlanet Application Server Administrative tool to add an IIOP Bridge process to the application server environment.

  1. Start the iPlanet Application Server Administration Tool

    On UNIX:

    install_dir/ias/bin/ksvradmin

    On Windows:

    Start->Programs->iPlanet Application Server->iAS Administration Tool

  2. Connect to your application server instance and double click on the server name icon to see a list of the processes defined for this instance of the Application Server. You should see at least one kjs and possibly a single kxs process (the kxs process is not required for RMI/IIOP access to EJBs). If you see a cxs process, you already have an IIOP Bridge process defined in your application server instance. In this case, double click the cxs process entry, note the IIOP port number, and continue to the next section. If you don't see a Bridge process, continue to the next step to define one.

  3. Select any of the existing process entries and then select File->New->Process.

  4. Select cxs from the pull-down list of process types and enter a port number (for example, port 10822) that does not conflict with the other port numbers already in use by the kjs and kxs processes. Take the default IIOP port number (9010) as long as it does not conflict with other port assignments in your system environment. Click on OK to instantiate the process.

  5. After several seconds, you see the IIOP Bridge process running in the Application Server environment. This process, along with all of the other application server processes listed in the Administrative Tool, is automatically started as the application server is restarted.

  6. On UNIX, you can also check for the existence of the IIOP bridge process from the command line. For example (each command is all on one line):

    ps -ef | grep iiop

    root 1153 1 0 17:00:15 ? 0:00 /bin/sh /usr/iPlanet/ias6/ias/bin/kjs -cset CCS0 -eng 3 -iiop -DORBinsPort=9010

    This output shows an iPlanet Java Engine process started with the -iiop option. This option informs this instance of the Java Engine to start itself as an IIOP Bridge process rather than a J2EE web and EJB container process.

    Instantiating a cxs process completes the server side configuration for RMI/IIOP support.


Client Configuration

To enable a Java application client to access EJBs housed in iPlanet, you must ensure that a suitable Java 2 environment, the iPlanet ORB, and several JAR files are available on the client system, as in Figure 10-4.

Figure 10-4    Client configuration



The steps are explained in the following sections:


Configuring a Java 2 Environment and iPlanet ORB
A Java 2 environment and the iPlanet ORB must be present on the client to support communication to remote EJBs via RMI/IIOP. Either the Java 2environment bundled as part of the iPlanet Application Server or one of the tested variants described in the section "Using an Existing JDK" must be used on the client. Other Java 2 environments are likely to work properly, but these environments are not supported by iPlanet.


Using the Bundled JDK
Because it is the platform on which iPlanet performs the bulk of its RMI/IIOP testing, the recommended Java 2 platform for client side RMI/IIOP-based applications is the Java 2 environment that is bundled as part of the application server. To use this JVM on the client side, you can simply copy the Java 2 environment from an iPlanet installation to your client environment and set the PATH appropriately to pick up the appropriate java executable file. Since the bundled Java 2 environment includes the iPlanet ORB, you do not need to modify the Java 2 environment after you copy it to the client side.

The bundled Java 2 platform is in the following location on your Application Server installation:

install_dir/ias/usr/java/

To copy the server's JVM environment to your client, follow these steps:

  1. Navigate to install_dir/ias/usr/.

  2. Copy the entire java/ directory to your client environment. You can zip or tar the java/ directory, transfer the archive to the client system, and expand it into a directory of your choice.

  3. Set your client's PATH to include client_side_JVM_directory/java/bin.

  4. Execute java -fullversion to ensure that the appropriate JDK (1.3.1) is being used. On UNIX, execute which java to check your work.

Now that you've installed the bundled JDK along with the iPlanet ORB, you need to install several supporting JAR files in your client environment. Proceed to "Installing RMI/IIOP Client Support Classes" to install these JAR files.


Using an Existing JDK
Basic testing of several distributions of the Java 2 environment have demonstrated that, with minor setup steps, you can leverage an existing Java 2 environment in support of RMI/IIOP clients accessing EJBs housed in iPlanet Application Server. In these cases, you must copy the iPlanet ORB files from an iPlanet Application Server environment to the pre-existing JVM on the client system.

The following combinations of operating systems and Java 2 platforms have been tested with iPlanet Application Server:

Other combinations of operating systems and Java 2 platforms may work properly with RMI/IIOP and iPlanet Application Server, but no testing has been performed on other combinations. Regardless of the combination chosen, you should ensure that you test your configuration thoroughly prior to making a determination that it is suitable for production use.


Solaris and JDK 1.3.1
In this scenario, you have already installed a Java 2 1.2 environment on a Solaris system and you plan to use this JVM as the platform for your RMI/IIOP client.

In the following instructions, JAVA_HOME is used as the directory in which the JDK 1.3.1 distribution has been installed. For example:

export JAVA_HOME=/usr/java1.3

  1. Copy the j2eeorb.jar from an iPlanet Application Server Solaris installation to your Solaris client system.

    Copy the j2eeorb.jar file:

    install_dir/ias/usr/java/jre/lib/ext/j2eeorb.jar

    to your Solaris client's JDK installation:

    $JAVA_HOME/jre/lib/ext

    (To be removed)Ensure that the sparc/ directory containing shared object files is copied as part of this step. The iPlanet ORB, native serialization files and other support files are copied to your client in this step.

  2. Copy the orb.properties file from your iPlanet installation:

    install_dir/ias/usr/java/jre/lib/orb.properties

    to your client's JDK installation:

    $JAVA_HOME/jre/lib/

  3. Set the PATH to make sure the DLLs can be accessed by the client application:

    (to be removed)export PATH=$JAVA_HOME/bin:$JAVA_HOME/jre/lib/ext/i386:$PATH

Now that you've configured the existing JDK to use the iPlanet ORB, you need to install several supporting JAR files in your client environment. Proceed to "Installing RMI/IIOP Client Support Classes" to install these JAR files.


Linux and Java 1.3.1
In this scenario, you have already installed a JDK 1.3.1 environment on a Linux system and you plan to use this JVM as the platform for your RMI/IIOP client. The following approach was tested with RedHat 6.2.


Note Due to incompatabilities between the native serialization libraries in JDK 1.2 and JDK 1.3, if you use JDK 1.3 on the client side, only values of primitive data types can be exchanged between the client and server.


  1. Create a directory on the client to hold the iPlanet ORB. For example:

    mkdir -p /opt/iplanet/orb

  2. Copy the following JAR files from the iPlanet Application Server installation to your Linux system to an appropriate directory on the client system, for example, to /opt/iplanet/orb/.

    install_dir/ias/usr/java/jre/lib/ext/j2eeorb.jar

  3. Set the environment. For example:

    JAVA_HOME=/opt/jdk1.3

    PATH=:$JAVA_HOME/bin:$JAVA_HOME/jre/lib/i386:$PATH

    CLASSPATH=/opt/iplanet/orb/j2eeorb.jar

    LD_LIBRARY_PATH=$JAVA_HOME/jre/lib:$JAVA_HOME/jre/lib/i386

    export JAVA_HOME PATH CLASSPATH LD_LIBRARY_PATH

  4. You can specify the iPlanet ORB classes as properties on the command line (this command must be all on one line):

    java -Dorg.omg.CORBA.ORBClass=com.netscape.ejb.client.ClientORB -Dorg.omg.CORBA.ORBSingletonClass=com.sun.corba.ee.internal.corba.ORBSingleton j2eeguide.converter.ConverterClient ias_host 9010

Now that you've configured the existing JDK to use the iPlanet ORB, you need to install several supporting JAR files in your client environment. Proceed to "Installing RMI/IIOP Client Support Classes" to install these JAR files.


Windows 98, NT, or 2000 and Java 1.3.1
In this scenario, you have already installed a Java 1.3.1 environment on Windows, and you plan to use this JVM as the platform for your RMI/IIOP client.

In the following instructions, JAVA_HOME is used as the directory in which the JDK 1.3.1 distribution has been installed. For example:

set JAVA_HOME=c:\JDK1.3.1

  1. Copy the j2eeorb.jar from an iPlanet Application Server Windows installation to your Windows client system.

    Copy the j2eeorb.jar file::

    install_dir\ias\usr\java\jre\lib\ext\j2eeorb.jar

    to your client's JDK installation:

    %JAVA_HOME%\jre\lib\ext

  2. Copy the orb.properties file from your iPlanet installation:

    install_dir\ias\usr\java\jre\lib\orb.properties

    to your client's JDK installation:

    %JAVA_HOME%\jre\lib\

  3. Copy native serialization DLLs from your iPlanet installation:

    install_dir\ias\usr\java\jre\bin\ioser12.dll

    to your client's JDK installation:

    %JAVA_HOME%\jre\bin\

  4. Set the PATH to make sure the DLLs can be accessed by the client application:

    set PATH=%JAVA_HOME%\bin;%PATH%

Now that you've configured the existing JDK to use the iPlanet ORB, you need to install several supporting JAR files in your client environment. Proceed to "Installing RMI/IIOP Client Support Classes" to install these JAR files.


Installing RMI/IIOP Client Support Classes
Regardless of the Java 2 platform used on the client side, the client's CLASSPATH must include the file iasclient.jar, an iPlanet-specific JAR file containing several security-related classes supporting iPlanet's client authentication feature (if you are using ACC, iasclient.jar is replaced by iasacc.jar ). The standard javax.jar file must also be included in your client CLASSPATH. This file contains standard Java interfaces for naming services and other Java extensions.

These JAR files can be copied from an iPlanet installation to your client environment and added to the client's CLASSPATH. On UNIX, you can find these files in the following location of an iPlanet Application Server installation:

install_dir/ias/classes/java/iasclient.jar

install_dir/ias/classes/java/javax.jar

On Windows, you can find these files in the following location of an iPlanet Application Server installation:

install_dir/ias/classes/java/iasclient.jar

install_dir/ias/lib/java/javax.jar

Once you've copied these supporting files to the client environment, you must configure the client's CLASSPATH to include the JAR files.


RMI/IIOP Client Access to EJBs on Same System
If you are experimenting with RMI/IIOP client access using a client that is on the same machine as the application server, you can take a shortcut to setting up the PATH and CLASSPATH variables. Simply reference the existing, pre-installed copies of the javax.jar, iasclient.jar, and the JVM in install_dir/usr/java/bin/. For example, to test RMI/IIOP access locally, set the CLASSPATH variable as follows:

On Windows:

set CLASSPATH=d:\iplanet\ias6\ias\lib\java\javax.jar;d:\iplanet\ias6\ia s\classes\java\iasclient.jar;%CLASSPATH%

(The Windows System PATH environment variable already contains install_dir/usr/java/bin/ of the bundled JDK, so there is no need to set this again on Windows.)

You could set the Windows System CLASSPATH to avoid having to manually set the variable.

On UNIX:

export CLASSPATH=/usr/iplanet/ias6/ias/classes/java/javax.jar:/usr/iplanet /ias6/ias/classes/java/iasclient.jar:$CLASSPATH

On UNIX, you must also modify the PATH to include the bundled JDK directory:

export PATH=/usr/iplanet/ias6/ias/usr/java/bin:$PATH


RMI/IIOP Client Access to EJBs from a Remote System
If you are using a remote client system, follow these steps to establish the appropriate PATH and CLASSPATH settings.

On UNIX:

Set your PATH environment variable to include the appropriate Java 2 bin/ directory:

export PATH=Java2_install_dir/usr/java/bin:$PATH

Set your CLASSPATH to include the standard Java Extension classes and the iPlanet RMI/IIOP client support JAR:

export CLASSPATH=/opt/rmi-client/iasclient.jar:/opt/rmi-client/javax.jar:$ CLASSPATH

Double check the CLASSPATH to ensure that it is set correctly (your CLASSPATH may vary from the one shown below):

echo $CLASSPATH

/opt/rmi-client/iasclient.jar:/opt/rmi-client/javax.jar:

On Windows:

Set your PATH environment variable to include the appropriate JDK bin/ directory:

set PATH=Java2_install_dir\usr\java\bin;%PATH%

Set your CLASSPATH to include the standard Java Extension classes (javax.jar) and the iPlanet client support JAR (iasclient.jar):

set CLASSPATH=d:\rmi-client\javax.jar;d:\rmi-client\iasclient.jar;%CLAS SPATH%


Deploying RMI/IIOP Client Applications

As you develop client applications, you will need to deploy a number of files from your development environment to the client system. This section addresses the underlying steps required to deploy an RMI/IIOP-capable client application in the following sections:


Client Deployment

In addition to ensuring that client application classes are available on the client system, you must ensure that EJB-specific home and remote interfaces and their corresponding stubs are deployed to the client system. For example, in the Converter sample application, the following classes must be copied to the client system:

Home and Remote Interface Classes:

ConverterHome.class

Converter.class

EJB-Specific iPlanet Client Stubs:

_Converter_Stub.class

_ConverterHome_Stub.class


Deployment Tools

The Deployment Tool creates a JAR file containing only the home and remote interfaces and the RMI/IIOP stub classes. The tool does not currently package the rest of your client application classes and resources.

You can easily automate assembly of your client application via the Java-based Ant build facility. Refer to the RMI/IIOP sample applications for examples of using Ant to both package and deploy client applications.


Server CLASSPATH Setting (SP2 and Prior)

This section applies to iPlanet Application Server 6.0 Service Pack 2 (SP2) and earlier. Service Packs 3 and later do not require the following configuration step. If you are using SP3 or beyond, skip to the next section, "Running RMI/IIOP Client Applications."

In iPlanet Application Server Service Pack 2 and earlier, to load EJB classes, the IIOP Bridge process must be able to access the EJB stubs and home and remote interfaces via the application server's CLASSPATH. Before the first execution of an RMI/IIOP-based Java application client in SP2 or earlier, you must first modify the CLASSPATH of the application server.

With the advent of iPlanet Application Server 6.0 SP2, registration of EJB-based applications results in the EJB JAR file being expanded to the application server's deployment directory. By default, when a J2EE application such as j2eeguide-converter.ear is deployed to the application server, the embedded EJB JAR file, j2eeguideEjb.jar in this example, is expanded to:

install_dir/ias/APPS/j2eeguide-converter/j2eeguide-converterEjb/

When a stand-alone EJB JAR module (or WAR module) is deployed to iPlanet Application Server, the default expansion location for the stand-alone module is:

install_dir/ias/APPS/modules/j2eeguide-converterEjb/

Prior to running the RMI/IIOP client, you must add the appropriate module directory to the CLASSPATH of the application server.


Configuring RMI/IIOP Applications for ORBIX

After you have installed ORBIX 2000 and integrated it with iPlanet Application Server as described in the Administrator's Guide, you can choose which ORB (built-in or ORBIX) to use for each RMI/IIOP client application. This section describes how to configure an RMI/IIOP client to use ORBIX.

For information about ORBIX and client-side load balancing, see "Client-Side Load Balancing and Failover."


References


Configuration Steps

The steps are the same for Unix and Windows except for the format of the file paths. The examples show Unix file paths.

  1. Install ORBIX 2000 version 1.2.1. Copy the license file to /etc/opt/iona/ and install the license. Refer to the Administrator's Guide and the ORBIX documentation.

  2. Copy the ORBIX domain configuration file from the server ORBIX installation (where the naming service is running) to another directory, for example:

    /etc/opt/iona/domains

    This file contains the necessary configuration information to contact the server ORBIX installation. The client program uses this file to connect to the naming service.

    This is not required if the client and server are run on the same machine. In this case, the localhost configuration (the default) is used.

  3. If you are planning to install one of the pre-packaged sample applications, regenerate the stubs and skeletons using the ejbc utility. For details about ejbc, see

  4. Install the client application.

  5. Copy the stubs (*Stub*.class) pertaining to the application to the client directory. For example (all on one line):

    cp ias_inst_dir/ias/APPS/j2eeguide-converter/j2eeguide-converterEjb/j2eeguide/converter/ _Converter_Stub.class client_inst_dir/j2eeguide/converter

    and (all on one line):

    cp ias_inst_dir/ias/APPS/j2eeguide-converter/j2eeguide-converterEjb/j2eeguide/converter/ _ConverterHome_Stub.class client_inst_dir/j2eeguide/converter

  6. Set the classpath. For example (all on one line):

    export CLASSPATH=orbix_inst_dir/orbix_art/1.2/classes/orbix2000.jar:orbix_inst_dir/orbix_art/1.2 /classes/omg.jar:orbix_license_file_path/licenses.txt:server_orbix_config_file_path: ias_inst_dir/classes/java/javax.jar:ias_inst_dir/ias/classes/java/iasclient.jar

    If an iPlanet Application Server installation is not present on the client machine, copy the javax.jar file from any iPlanet Application Server installation (version 6.5) to the client machine and include it in the classpath.

  7. Set the ORBdomain_name property to the domain name in the server ORBIX configuration file (see the ORBIX documentation for details about this file). This can be done in two ways:

    • Set the ORBdomain_name property at the Java command line when you run the client.

      In this case, the org.omg.CORBA.ORBClass property in the jdk_inst_dir/jre/lib/orb.properties file must be set to com.iplanet.ias.iona.clientorb.IONAorb. In addition, the iasclient.jar file must be included in the classpath as shown in Step 6.

    • In the client program, pass the ORBdomain_name property (as an array of strings) to the first parameter in the ORB.init call. This initializes the ORB. The initialized ORB can be passed to the JNDI calls, or subsequent CORBA initialization calls can be called on it.

      In this case, the org.omg.CORBA.ORBClass property in the jdk_inst_dir/jre/lib/orb.properties file must be set to com.iona.corba.art.artimpl.ORBImpl.

    Refer to the JNDI description in the JDK documentation for information about passing an initialized ORB to JNDI calls.

    Usage of the IONAorb class is optional. The IONAorb is derived from com.iona.corba.art.artimpl.ORBImpl (the ORBIX ORB class), and the set_parameters method is overloaded. In the set_parameters method, the ORBname and ORBdomain_name properties are read and passed to the ORB.init call.

  8. Modify the following property in the orb.properties file, which is available in the jdk_ inst_dir/jre/lib:

    org.omg.CORBA.ORBSingletonClass=com.iona.corba.art.artimpl.ORBSingleton

  9. Run the client.


    Note The built-in ORB uses the IIOP URL (which includes the host name and port number) to connect to the iPlanet Application Server. The ORBIX ORB does not use this URL for connecting to CXS.

    If the built-in ORB is used, the naming service is in-process to CXS. If the ORBIX ORB is used, it is out-of-process.

    ORBIX Java client applications trying to pass User-Defined serializable objects embedded inside java containers (such as java.util.vector) receive MARSHALLING exceptions.



Enabling Security

To enable security, perform the following steps before invoking the client.

  1. Make sure no value is set for the following property. There should be only blank space after the equal sign.

    org.omg.PortableInterceptor.ORBInitializerClass.com.iplanet.ias.iona. orbinitializers.IONAClientORBInitializerImpl=

  2. Set the ORBname property to orbname in the scope in which the client_interceptor name has been registered. This can be done in two ways:

    • Set the ORBname property at the Java command line.

      In this case, the org.omg.CORBA.ORBClass property must be set to com.iplanet.ias.iona.clientorb.IONAorb.

    • In the client program, pass the ORBname property (as an array of strings) to the first parameter in the ORB.init call. This initializes the ORB. The initialized ORB can be passed to the JNDI calls, or subsequent CORBA initialization calls can be called on it.

      In this case, the org.omg.CORBA.ORBClass property must be set to com.iona.corba.art.artimpl.ORBImpl.

    Refer to the JNDI description in the JDK documentation for information about passing an initialized ORB to JNDI calls.

    Usage of the IONAorb class is optional. The IONAorb is derived from com.iona.corba.art.artimpl.ORBImpl (the ORBIX ORB class), and the set_parameters method is overloaded. In the set_parameters method, the ORBname property is read and passed to the ORB.init call.

  3. Add the client interceptor name, iASClientInterceptor, to the client_binding_list in the ORBIX configuration file at the appropriate scope. If it is not added at the global scope, set the property ORBname to the value orbname. Refer to the ORBIX documentation for further details. For example:

    binding:client_binding_list = ["OTS+POA_Coloc", "POA_Coloc", "OTS+TLS_Coloc+POA_Coloc", "TLS_Coloc+POA_Coloc", "iASClientInterceptor+GIOP+IIOP", "OTS+GIOP+IIOP", "GIOP+IIOP", "OTS+GIOP+IIOP_TLS", "GIOP+IIOP_TLS"];


    Note The "iASClientInterceptor+GIOP+IIOP" entry must be listed before the "OTS+GIOP+IIOP" entry.


  4. Add portable_interceptor to the orb_plugins list at the appropriate scope.

    For example, before the addition:

    orb_plugins=["iiop_profile","giop" ,"iiop", "ots"]

    and after the addition:

    orb_plugins=["iiop_profile","giop" ,"iiop", "ots", "portable_interceptor"]

    Interceptor names and portable_interceptor have to be added at the same scope.

  5. For enabling security, the com.netscape.ejb.client.IUserPrincipal interface must be implemented, and the class file name must be specified in the property com.netscape.ejb.client.PrincipalClass.


    Note If the org.omg.CORBA.ORBClass property is set to com.iona.corba.art.artimpl.ORBImpl, the com.netscape.ejb.client.PrincipalClass property has to be set in the system properties. Passing it programmatically does not work.



Running RMI/IIOP Client Applications

If your client is a Java main program, then as long as the client environment is set appropriately and you are using a compatible JVM, you merely need to execute the main class. Depending on whether you are passing the IIOP URL components (host and port number) on the command line or obtaining this information from a properties file, the exact manner in which you execute the main program will vary. For example, the ConverterClient sample is executed in the following manner:

java j2eeguide.converter.ConverterClient host_name port

The host_name is the name of the host on which an IIOP Bridge is listening on the specified port.


Troubleshooting RMI/IIOP Client Applications

When running an RMI/IIOP client, you may encounter error conditions on the client. To view the IIOP Bridge logs, see "Viewing RMI/IIOP Log Messages." Table 10-1 lists common symptoms and fixes for common RMI/IIOP configuration problems.

If you are running the RMI/IIOP client application under load and are experiencing issues, see "Recognizing Performance Issues" to understand how to troubleshoot load-related issues.


Table 10-1    Troubleshooting

Symptom

Probable Cause

Corrective Action

The client throws the following exception during JNDI lookup:

org.omg.CORBA.INITIALIZE: can't instantiate default ORB implementation  

The client CLASSPATH does not include the iasclient.jar file.

The client PATH does not pickup appropriate java command. Either the JVM bundled with the application server or a suitable pre-existing JVM must be used.  

Ensure that the client configuration steps were followed; see "Client Configuration."  

The client experiences a CORBA communication failure exception:

javax.naming.CommunicationException: Cannot connect to ORB. Root exception is org.omg.CORBA.COMM_FAILURE:  

Connection to the IIOP Bridge fails because of one of the following reasons:

  • IIOP host and/or port number are incorrect.

  • IIOP Bridge process has not been started.

  • IIOP Bridge process was started, but has not finished initializing.

  • Client machine cannot access the network.

  • Firewall rules do not allow access to the Application Server system.

 

Ensure that the IIOP Bridge process is configured and started; see "Server Configuration."

Ensure that the client machine has network access and that intermediate firewalls are not blocking access.  

a) The client appears to hang and then experiences an out of memory exception:

Exception in thread "main" java.lang.OutOfMemoryError.

b) The IIOP Bridge throws one of the following exceptions repeatedly:

Name Not Found:

[01/May/2001 08:20:14:4] info: GDS-007: finished a registry load [01/May/2001 08:20:14:6] info: PROT-006: new connection established SendRemoteReq status=0x0 javax.naming.NameNotFoundException: EjbContext: exception on getHome(), com.nets cape.server.eb.UncheckedException: unchecked exception thrown by impl com.kivasoft.eb.boot.EBBootstrapImpl@1fca24a; nested exception is:

Class not Found:

[24/Jan/2001 12:25:52:9] error: EBFP-unserialize: error during unserialization of method, exception = java.lang.ClassNotFoundException: j2eeguide.confirmer.ejb_stub_ConfirmerHome java.lang.ClassNotFoundException: j2eeguide.confirmer.ejb_stub_ConfirmerHome at java.lang.Throwable.fillInStackTrace(Native Method)

Class Cast Exceptions  

The JNDI name as specified in the client application is not correct.

OR

(Pre SP3) The expanded EJB JAR directory has not been added to the server CLASSPATH or the server has not been restarted since the EJB JAR directory was added to the CLASSPATH.  

Correct the JNDI name used by the client.

OR

Set application server's CLASSPATH  

The client application encounters a naming communication exception:

javax.naming.CommunicationException  

The Directory Server associated with the Application Server is not running.  

Start the Directory Server.  


Performance Tuning RMI/IIOP

For deployment environments in which you expect the RMI/IIOP path to support more than a handful of concurrent users, you should experiment with the tuning guidelines described in this section. The default configuration of the JVM and the underlying OS do not yield optimal performance and capacity when you are using RMI/IIOP.

This section covers the following topics:


Recognizing Performance Issues

Before exercising your RMI/IIOP client application under load, ensure that you've verified that basic mechanical tests are completed successfully.

As you begin exercising the client application under load, you may experience the following exceptions on the RMI/IIOP client:

org.omg.CORBA.COMM_FAILURE

java.lang.OutOfMemoryError

java.rmi.UnmarshalException

If you've verified that the basic mechanics of your application are working properly and you experience any one of these exceptions while load testing your application, see the next section to learn how to tune the RMI/IIOP environment.


Basic Tuning Approaches

You should experiment with the following tuning recommendations in order to find the best balance for your specific environment.


Solaris File Descriptor Setting
On Solaris, setting the maximum number of open files property using ulimit has the biggest impact on your efforts to support the maximum number of RMI/IIOP clients. The default value for this property is 64 or 1024 depending on whether you are running Solaris 2.6 or Solaris 8. To increase the hard limit, add the following command to /etc/system and reboot it once:

set rlim_fd_max = 8192

You can verify this hard limit by using the following command:

ulimit -a -H

Once the above hard limit is set, you can increase the value of this property explicitly (up to this limit) using the following command:

ulimit -n 8192

You can verify this limit by using the following command:

ulimit -a

For example, with the default ulimit of 64, a simple test driver can support only 25 concurrent clients, but with ulimit set to 8192, the same test driver can support 120 concurrent clients. The test driver spawned multiple threads, each of which performed a JNDI lookup and repeatedly called the same business method with a think (delay) time of 500ms between business method calls, exchanging data of about 100KB.

These settings apply to both RMI/IIOP clients (on Solaris) and to the IIOP Bridge installed on a Solaris system. Refer to Solaris documentation for more information on setting the file descriptor limits.


Java Heap Settings
Apart from tuning file descriptor capacities, you may want to experiment with different heap settings for both the client and Bridge JVMs. Refer to the JDK 1.3.1 documentation for information about modifying the default heap size.


Enhancing Scalability

Beyond tuning the capacity of a single Bridge process and client systems, you can improve the scalability of the RMI/IIOP environment by using multiple IIOP Bridge processes. You may find that configuring multiple Bridge processes on the same application server instance improves the scalability of your application deployment. In some cases, you may want to use a number of application server instances each configured with one or more Bridge processes.

In configurations where more than one Bridge process is active, you can partition the client load by either statically mapping sets of clients to different Bridges or by implementing your own logic on the client side to load balance against the known Bridge processes.


Firewall Configuration for RMI/IIOP

If the RMI/IIOP client is communicating through a firewall to the iPlanet Application Server, you must enable access from the client system to the IIOP port used by the IIOP Bridge processes. Since the client's port numbers are assigned dynamically, you must open up a range of source ports and a single destination port to allow RMI/IIOP traffic to flow from a client system through a firewall to an instance of the Application Server.

A snoop-based trace of the IIOP traffic between two systems during a single execution of the Converter sample application follows. The host swatch is the RMI/IIOP client, while the host mamba is the destination or Application Server system. The port number assigned to the IIOP Bridge process is 9010. Note that the two dynamically assigned ports (33046 and 33048) are consumed on the RMI/IIOP client, while only port 9010 is used to communicate with the Bridge process.

swatch -> mamba.red.iplanet.com TCP D=9010 S=33046 Syn Seq=140303570 Len=0 Win=24820
Options=<nop,nop,sackOK,mss 1460>
mamba.red.iplanet.com -> swatch TCP D=33046 S=9010 Syn Ack=140303571 Seq=1229729413 Len=0 Win=8760
Options=<mss 1460>
swatch -> mamba.red.iplanet.com TCP D=9010 S=33046 Ack=1229729414 Seq=140303571 Len=0 Win=24820
swatch -> mamba.red.iplanet.com TCP D=9010 S=33046 Ack=1229729414 Seq=140303571 Len=236 Win=24820
mamba.red.iplanet.com -> swatch TCP D=33046 S=9010 Ack=140303807 Seq=1229729414 Len=168 Win=8524
swatch -> mamba.red.iplanet.com TCP D=9010 S=33046 Ack=1229729582 Seq=140303807 Len=0 Win=24820
swatch -> mamba.red.iplanet.com TCP D=9010 S=33048 Syn Seq=140990388 Len=0 Win=24820
Options=<nop,nop,sackOK,mss 1460>
mamba.red.iplanet.com -> swatch TCP D=33048 S=9010 Syn Ack=140990389 Seq=1229731472 Len=0 Win=8760
Options=<mss 1460>
swatch -> mamba.red.iplanet.com TCP D=9010 S=33048 Ack=1229731473 Seq=140990389 Len=0 Win=24820
swatch -> mamba.red.iplanet.com TCP D=9010 S=33048 Ack=1229731473 Seq=140990389 Len=285 Win=24820
mamba.red.iplanet.com -> swatch TCP D=33048 S=9010 Ack=140990674 Seq=1229731473 Len=184 Win=8475
swatch -> mamba.red.iplanet.com TCP D=9010 S=33048 Ack=1229731657 Seq=140990674 Len=0 Win=24820
swatch -> mamba.red.iplanet.com TCP D=9010 S=33048 Ack=1229731657 Seq=140990674 Len=132 Win=24820
mamba.red.iplanet.com -> swatch TCP D=33048 S=9010 Ack=140990806 Seq=1229731657 Len=25 Win=8343
swatch -> mamba.red.iplanet.com TCP D=9010 S=33048 Ack=1229731682 Seq=140990806 Len=0 Win=24820
swatch -> mamba.red.iplanet.com TCP D=9010 S=33048 Ack=1229731682 Seq=140990806 Len=124 Win=24820
mamba.red.iplanet.com -> swatch TCP D=33048 S=9010 Ack=140990930 Seq=1229731682 Len=0 Win=8219
mamba.red.iplanet.com -> swatch TCP D=33048 S=9010 Ack=140990930 Seq=1229731682 Len=336 Win=8219
swatch -> mamba.red.iplanet.com TCP D=9010 S=33048 Ack=1229732018 Seq=140990930 Len=120 Win=24820
mamba.red.iplanet.com -> swatch TCP D=33048 S=9010 Ack=140991050 Seq=1229732018 Len=0 Win=8099
mamba.red.iplanet.com -> swatch TCP D=33048 S=9010 Ack=140991050 Seq=1229732018 Len=32 Win=8099
swatch -> mamba.red.iplanet.com TCP D=9010 S=33048 Ack=1229732050 Seq=140991050 Len=120 Win=24820
mamba.red.iplanet.com -> swatch TCP D=33048 S=9010 Ack=140991170 Seq=1229732050 Len=0 Win=7979
mamba.red.iplanet.com -> swatch TCP D=33048 S=9010 Ack=140991170 Seq=1229732050 Len=32 Win=7979
swatch -> mamba.red.iplanet.com TCP D=9010 S=33046 Fin Ack=1229729582 Seq=140303807 Len=0 Win=24820
mamba.red.iplanet.com -> swatch TCP D=33046 S=9010 Ack=140303808 Seq=1229729582 Len=0 Win=8524
mamba.red.iplanet.com -> swatch TCP D=33046 S=9010 Fin Ack=140303808 Seq=1229729582 Len=0 Win=8524
swatch -> mamba.red.iplanet.com TCP D=9010 S=33048 Fin Ack=1229732082 Seq=140991170 Len=0 Win=24820
swatch -> mamba.red.iplanet.com TCP D=9010 S=33046 Ack=1229729583 Seq=140303808 Len=0 Win=24820
mamba.red.iplanet.com -> swatch TCP D=33048 S=9010 Ack=140991171 Seq=1229732082 Len=0 Win=7979
mamba.red.iplanet.com -> swatch TCP D=33048 S=9010 Fin Ack=140991171 Seq=1229732082 Len=0 Win=7979
swatch -> mamba.red.iplanet.com TCP D=9010 S=33048 Ack=1229732083 Seq=140991171 Len=0 Win=24820


Viewing RMI/IIOP Log Messages

Log messages generated by the RMI/IIOP path can be monitored by reviewing the log file generated by the IIOP Bridge process. Since the IIOP Bridge process is a form of a Java Engine (kjs), you monitor these logs in the same manner as you would monitor the Java Engines supporting the web and EJB containers. To view the appropriate log file, you must identify the Java Engine that is playing the role of the IIOP Bridge.


Monitoring Logs on Windows

By default, on a Windows installation of iPlanet Application Server, the Java Engine log files are not automatically displayed during startup of the Application Server. Most developers find it convenient to enable automatic display of console log information by performing the following steps:

  1. Select Start->Settings->Control Panel.

  2. Double click on Services.

  3. Find the "iPlanet Application Server 6.5" entry and select it.

  4. Click on Startup.

  5. Click on "Allow Service to Interact with Desktop" and click on OK.

  6. Click on Stop to stop the Application Server.

  7. Click on Start to start the Application Server.

As the application server starts, a number of MS DOS output windows appear on the desktop. A single output window is present for each physical process in the application server. As the engines start, look for the Java Engines and, in particular, the engine that specifies the port number defined in the CXS (Bridge) process.

To enable vertical scroll bars in these output windows, follow these steps:

  1. Select the MS DOS icon at the upper left of the output window.

  2. Select Properties.

  3. Select Layout.

  4. Set the Screen Buffer Size Height to 200 or as desired.

  5. Answer Yes when asked to apply these changes to all invocations of this window.


Monitoring Logs on UNIX

On UNIX, most developers use the tail -f command to monitor the application server log files of the process of interest. To monitor the Java Engine logs in this manner, follow these steps:

  1. Navigate to the logs directory:

    cd install_dir/ias/logs

  2. Execute the tail command on one of the Java Engine (kjs) and the Executive Service (kxs) processes:

    tail -f kjs_2*

    You must select the appropriate Java Engine log file to monitor. Java Engines are numbered according to how they are defined in the Administration Tool. Although the CXS (Bridge) process is typically the highest numbered Java Engine log file, double check the port number information within the log file to confirm which log files is generated by the CXS process.

  3. Press Control-C to kill the tail command.


Sample RMI/IIOP Applications

A list of RMI/IIOP-oriented samples is available under the following location of your web server's document root or under the installation directory of the Application Server:

http://webserver_host/ias-samples/ -> RMI/IIOP

install_dir/ias/ias-samples/index.html -> RMI/IIOP


Converter Sample Application

The Currency Converter sample application from Sun's J2EE Developer's Guide has been bundled with iPlanet Application Server. This sample has been augmented with detailed setup instructions for deploying the application to iPlanet Application Server. It is recommended that you follow the detailed setup instructions for this sample and exercise the Converter sample prior to deploying other RMI/IIOP-based applications. Currency Converter setup documentation and source code are available at the following locations:

install_dir/ias/ias-samples/j2eeguide/docs/converter.html

install_dir/ias/ias-samples/j2eeguide/converter/src/


Other RMI/IIOP Sample Applications

Many of the J2EE Developer's Guide samples bundled with iPlanet Application Server include RMI/IIOP client programs. These are relatively simple samples that demonstrate various facets of the EJB specification. You can find these samples at:

install_dir/ias/ias-samples/j2eeguide/docs/index.html



C++ IIOP Client Applications (Unix Only)


Using C++ IIOP-based client applications with iPlanet Application Server is very similar to using these clients with other J2EE-certified application servers. With minimal, if any, changes to the lookup section of your client, you can reuse your client to work with a variety of J2EE application servers.

The following topics are covered in this section:


Configuring C++ IIOP Applications for ORBIX

Before you can use a C++ IIOP client with iPlanet Application Server, you must install ORBIX 2000 and integrate it with iPlanet Application Server as described in the Administrator's Guide. This section lists software requirements for ORBIX use and additional documentation.


Requirements

The software requirements are as follows:

  • Solaris 2.6 +

  • ORBIX 2000 C++ development kit Version 1.2+

  • Sun Workshop 6.2 (C++ 5.2)

  • iPlanet Application Server version 6.5

  • A Java to IDL compiler (rmic of J2SE 1.3 and below has some problems; use either rmic of J2SE 1.4 Beta or any other Java to IDL compiler)

  • Implementation of the pass-by-value user-defined and Java native complex types in C++. To ensure that the data types that are passed by value between the EJB and the C++ client are correctly converted between the different languages, you must provide C++ implementations of these types; this applies to both the native Java types and the user-defined types.


References


Preparing for C++ Client Development

Perform these steps before starting C++ client development:

  1. Make sure all the required software is installed; see "Requirements".

  2. Make sure the stubs and skeletons in the EAR file have been generated with the -iiop option of ejbc. If they have not been, edit the build.xml file to add -iiop to the ejbc options and regenerate the EAR file.

  3. Deploy the EJBs. You can use the J2EE guide samples (for example, the currency converter and the confirmer ) bundled with iPlanet Application Server.


    Note According to the OMG IDL to Java Language Mapping, the use of Java package names differing only in case is not supported. Using class or interface names within the same package that differ only in case is not supported either. Both of these are treated as errors. Therefore, deployed beans must not have package names and class names differing only in case. Since the J2EE guide samples have this characteristic, you must modify them before deploying them. For an example of this, see "Redeploying the Converter Sample for Use with a C++ Client."



Data Type Assumptions and Limitations

Only double, int, long, short, float, char, boolean, and byte data type value passing between the client and server have been tested. It is assumed that all other standard CORBA datatypes for which there is IDL to Java/C++ language mapping work. Passing a java.lang.BigDecimal throws a NO_IMPLEMENT exception.

For other data types (such as HashTable or other custom Java classes) that must be passed by value, you must provide a native C++ implementation or provide a wrapper over an existing C++ implementation of those classes (such as STL) that conforms to the IDL generated for the Java classes.


Generating the IDL Files

You can generate the IDL files in two ways:


Using J2SE 1.4 rmic 2

To use rmic from J2SE 1.4, follow these steps:

  1. Create a new directory for C++ client development. For example:

    mkdir cppclient
    cd cppclient

  2. Execute rmic, for example (all on one line):

    rmic -classpath ias_inst_dir/ias/APPS/j2eeguide-myconverter/j2eeguide-myconverterEjb: ias_inst_dir/ias/classes/java/javax.jar -idl j2eeguide.myconfirmer.Confirmer

    and (all on one line):

    rmic -classpath ias_inst_dir/ias/APPS/j2eeguide-myconverter/j2eeguide-myconverterEjb: ias_inst_dir/ias/classes/java/javax.jar -idl j2eeguide.myconfirmer.ConfirmerHome

  3. Move the IDL files, for example:

    mv j2eeguide/myconverter/Converter.idl .
    mv j2eeguide/myconverter/ConverterHome.idl .

  4. Combine the above two generated IDLs into a single one for convenience. For example:

    1. cat ConverterHome.idl >> Converter.idl

    2. Edit Converter.idl and delete all the lines except those declaring the j2eeguide and myconverter modules, the Converter and ConverterHome interfaces, and the corresponding #pragma declarations.

    3. Add the following lines to the beginning of the IDL file:

         #include <omg/orb.idl>
         #include "ejb.idl"
         #include "_std_java.idl"

    Here is the final IDL file output, for comparison:

    #include <omg/orb.idl>
    #include "ejb.idl"
    #include "_std_java.idl"
    module j2eeguide {
       module myconverter {
          interface Converter : ::javax::ejb::EJBObject {
             double dollarToYen(in double arg0) ;
             double yenToEuro(in double arg0) ;
          };
          #pragma ID Converter
          "RMI:j2eeguide.myconverter.Converter:0000000000000000"
          interface ConverterHome : ::javax::ejb::EJBHome {
             Converter create() raises(::javax::ejb::CreateEx);
          };
          #pragma ID ConverterHome
       "RMI:j2eeguide.myconverter.ConverterHome:0000000000000000"
       };
    };

  5. Copy the supplied _std_java.idl and ejb.idl files to the cppclient directory.


Using the OpenORB JavaToIDL Compiler

Using the openorb JavaToIdl tool, copy the supplied openorb JAR files (openorb_rmi-1.0.1.jar and openorb_tools-1.0.1.jar) to the current directory. For example (all on one line):

java -cp openorb_rmi-1.0.1.jar:openorb_tools-1.0.1.jar:ias_inst_dir/ias/APPS/ j2eeguide-myconverter/j2eeguide-myconverterEjb: ias_inst_dir/ias/classes/java/javax.jar org.openorb.rmi.compiler.JavaToIdl j2eeguide.myconverter.Converter

and (all on one line):

java -cp openorb_rmi-1.0.1.jar:openorb_tools-1.0.1.jar:ias_inst_dir/ias/APPS/ j2eeguide-myconverter/j2eeguide-myconverterEjb: ias_inst_dir/ias/classes/java/javax.jar org.openorb.rmi.compiler.JavaToIdl j2eeguide.myconverter.ConverterHome


Generating CPP Files from IDL Files

To generate .cpp files from the .idl files, follow these steps:

  1. Source the ORBIX environment setup script by executing the following command:

    . orbix_inst_dir/bin/domain_env

    For example:

    . /opt/iona/bin/localhost_env

  2. Execute the following command (all on one line):

    orbix_inst_dir/bin/idlgen cpp_poa_genie.tcl -ns -all -complete Confirmer.idl -I. -I orbix_inst_dir/orbix_art/1.2/idl

  3. Edit the makefile and change the value IT_PRODUCT_DIR to the value applicable to your installation.

  4. Include -I. in CXXFLAGS.

  5. Export the PATH to include the workshop6 bin directory at the beginning of the path.

  6. Execute the following command. You will get errors, which you will correct in later steps.

    make -e

  7. Change CORBA to ::CORBA in the ejb.hh file, but only in the namespace javax::rmi::CORBA.

  8. Change EJBMetaData to javax::ejb::EJBMetaData.

  9. Remove or comment out lines containing EJBMetaDataImpl in the makefile and in client.cxx to prevent compilation errors.

  10. Edit client.cxx in the following ways:

    1. Comment out lines registering EJBMetaData, for example:

         javax_ejb_EJBMetaDataFactory::_register_with_orb(orb);

    2. Delete these lines:

         tmp_ref = default_context->resolve_str("IT_GenieDemo");
         CosNaming::NamingContext_var demo_context =
            CosNaming::NamingContext::_narrow(tmp_ref);
         assert(!CORBA::is_nil(demo_context));

    3. Delete the generated code with the lookups for Converter, EJBObject, and EJBHome, identified by the following comments:

      //Exercise interface j2eeguide::myconverter::Converter
      //Exercise interface javax::ejb::EJBObject
      //Exercise interface javax::ejb::EJBHome

    4. Change the following lines:

      name = default_context->to_name("j2eeguide_myconfirmer_Confirmer");
      tmp_ref = demo_context->resolve(name);

      to:

      name = default_context->to_name("ejb/MyMyConfirmer");
      tmp_ref = default_context->resolve(name);

    5. Comment out the generated code to call functions (beginning with call_j2eeguide_ ) and insert code to call create and the business methods. For example:

         j2eeguide::myconverter::Converter_var converter =
            ConverterHome4->create();
         CORBA::Double yen = 4000;
         CORBA::Double euro = converter->yenToEuro(yen);

  11. Edit ejbC.cxx and change CORBA to ::CORBA wherever relevent. For example, change it in the regular expression syntax:

    s/^CORBA/::CORBA/g

    s/ CORBA/ ::CORBA/g

    s/namespace ::CORBA/namespace CORBA/g

    s/\!CORBA/\!::CORBA/g

    s/(CORBA/(::CORBA/g

    s/ EJBMetaData/::javax::ejb::EJBMetaData/g

    s/IT_CONST_CAST(::CORBA/IT_CONST_CAST(CORBA/g

  12. Edit ConverterC.cxx file and change the operation name to a name in the following pattern. The double underscores are literal.

    function-name__return-type(pkg1_pkg2_class)__argument-type

    The types should be the Java types. For example, if the Java type is int, the IDL type is long, but the type represented in the operation should be int. You can refer to the parameters of the _request method in the generated Java stubs (for example _Converter_Stub.java, which is generated if the -gs option is provided for ejbc in build.xml) to get the exact operation name. For example:

    s/"create"/"create__j2eeguide_myconverter_Converter__void"/g
    s/"yenToEuro"/"yenToEuro__double__double"/g
    s/"dollorToYen"/"dollorToYen__double__double"/g

  13. Execute the make:

    make -e client

  14. Execute the client:

    ./client


Enabling Security for C++ IIOP Applications

To enable security, you must link the client application with:

  • The libgxorbixclientinterceptor.so library that comes with the iPlanet Application Server version 6.5.

  • The it_portable_interceptor library that comes with ORBIX.

The steps are as follows:

  1. Insert the following into the line for CLIENT_LIBS in client's makefile:

    -lit_portable_interceptor -lgxorbixclientinterceptor

  2. Insert the path to the location of libgxorbixclientinterceptor.so in the LDLIBS setting in the makefile. For example:

    -L/space/interceptor \

  3. Insert the path to the location of libgxorbixclientinterceptor.so in LD_LIBRARY_PATH . For example:

    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/space/interceptor

  4. Rebuild the client:

    make -e client

  5. Set the environment variables IAS_RC_USERID and IAS_RC_PASSWORD either from the shell or programmatically through putenv function, with the user IDand password corresponding to an LDAP user. If set to null or if not set, authentication won't happen, and the user won't be able to access beans that are role-mapped. For example:

    export IAS_RC_USERID=j2ee
    export IAS_RC_PASSWORD=j2ee

  6. Enable client interceptors and server interceptors as given in admin guide of Orbix integration.

  7. Execute the client:

    ./client


Lookup for the EJB Home Interface

One of the first steps in coding an IIOP client is to perform a lookup of an EJB's home interface. In preparation for performing a lookup of the home interface, you must set several environment properties. Then you provide a lookup name for the EJB. The following example shows these steps:

//initialise the orb
global_orb = CORBA::ORB_init(argc, argv);

// Get the naming context for genie demonstrations.
tmp_ref = global_orb->resolve_initial_references("NameService");
CosNaming::NamingContext_var default_context =
   CosNaming::NamingContext::_narrow(tmp_ref);
assert(!CORBA::is_nil(default_context));

//lookup the home
name = new CosNaming::Name(2);
name->length(2);
name[0].id = CORBA::string_dup("ejb");
name[0].kind = CORBA::string_dup("");
name[1].id = CORBA::string_dup("MyMyConfirmer");
name[1].kind = CORBA::string_dup("");
tmp_ref = default_context->resolve(name);

j2eeguide::myconfirmer::ConfirmerHome_var ConfirmerHome=j2eeguide::myconfirmer::ConfirmerHome::_narrow(tmp_ref);

//call create
j2eeguide::myconfirmer::Confirmer_var Confirmer=ConfirmerHome->create();

//call business method
Confirmer->sendNotice(chars);


Client-Side Load Balancing and Failover

Although iPlanet Application Server provides server-side load balancing and failover for IIOP access, you may consider implementing client side approaches to further enhance the performance and availability of your application.

The naming service defines a repository of names that map to objects. A name maps to one object only. ORBIX 2000 extends the naming service model to allow a name to map to a group of objects. An object group is a collection of objects that can increase or decrease in size dynamically. Each object group has a selection algorithm. This algorithm is applied when a client resolves the name associated with the object group. Three algorithms are supported:

  • Round-robin selection

  • Random selection

  • Active load balancing selection

Object groups provide a way to replicate frequently requested objects and thereby distribute the request-processing load. The naming service directs client requests to the various replicated objects according to the object group's selection algorithm. The existence of an object group is transparent to the client, which resolves the object group name in the same way that it resolves any other name.

You can set the flag ORBIX_LOADBALANCING=true or false in the iasenv.ksh file, which sets the Java argument as follows:

-DORBIXLoadBalancing=$ORBIX_LOADBALANCING


Configuring the IIOP Bridge

If your installation of iPlanet Application Server does not already have the IIOP Bridge process configured, you must start the iPlanet Application Server Administrative tool to add an IIOP Bridge process to the application server environment.

  1. Start the iPlanet Application Server Administration Tool:

    install_dir/ias/bin/ksvradmin

  2. Connect to your application server instance and double click on the server name icon to see a list of the processes defined for this instance of the Application Server. You should see at least one kjs and possibly a single kxs process (the kxs process is not required for IIOP access to EJBs). If you see a cxs process, you already have an IIOP Bridge process defined in your application server instance. In this case, double click the cxs process entry, note the IIOP port number, and continue to the next section. If you don't see a Bridge process, continue to the next step to define one.

  3. Select any of the existing process entries and then select File->New->Process.

  4. Select cxs from the pull-down list of process types and enter a port number (for example, port 10822) that does not conflict with the other port numbers already in use by the kjs and kxs processes. Take the default IIOP port number (9010) as long as it does not conflict with other port assignments in your system environment. Click on OK to instantiate the process.

  5. After several seconds, you see the IIOP Bridge process running in the Application Server environment. This process, along with all of the other application server processes listed in the Administrative Tool, is automatically started as the application server is restarted.

  6. You can also check for the existence of the IIOP bridge process from the command line. For example (each command is all on one line):

    ps -ef | grep iiop

    root 1153 1 0 17:00:15 ? 0:00 /bin/sh /usr/iPlanet/ias6/ias/bin/kjs -cset CCS0 -eng 3 -iiop -DORBinsPort=9010

    This output shows an iPlanet Java Engine process started with the -iiop option. This option informs this instance of the Java Engine to start itself as an IIOP Bridge process rather than a J2EE web and EJB container process.

    Instantiating a cxs process completes the server side configuration for IIOP support.


Deploying C++ IIOP Client Applications

As you develop client applications, you will need to deploy a number of files from your development environment to the client system. This section addresses the underlying steps required to deploy an IIOP-capable client application in the following sections:


Client Deployment

You must ensure that EJB-specific home and remote interfaces and their corresponding stubs are deployed to the client system. For example, in the Converter sample application, the following classes must be copied to the client system:

Home and Remote Interface Classes:

ConverterHome.class

Converter.class

EJB-Specific iPlanet Client Stubs:

_Converter_Stub.class

_ConverterHome_Stub.class


Server CLASSPATH Setting (SP2 and Prior)

This section applies to iPlanet Application Server 6.0 Service Pack 2 (SP2) and earlier. Service Packs 3 and later do not require the following configuration step. If you are using SP3 or beyond, skip to the next section.

In iPlanet Application Server Service Pack 2 and earlier, to load EJB classes, the IIOP Bridge process must be able to access the EJB stubs and home and remote interfaces via the application server's CLASSPATH. Before the first execution of IIOP-based Java application client in SP2 or earlier, you must first modify the CLASSPATH of the application server.

With the advent of iPlanet Application Server 6.0 SP2, registration of EJB-based applications results in the EJB JAR file being expanded to the application server's deployment directory. By default, when a J2EE application such as j2eeguide-converter.ear is deployed to the application server, the embedded EJB JAR file, j2eeguideEjb.jar in this example, is expanded to:

install_dir/ias/APPS/j2eeguide-converter/j2eeguide-converterEjb/

When a stand-alone EJB JAR module (or WAR module) is deployed to iPlanet Application Server, the default expansion location for the stand-alone module is:

install_dir/ias/APPS/modules/j2eeguide-converterEjb/

Prior to running the C++ IIOP client, you must add the appropriate module directory to the CLASSPATH of the application server.


Performance Tuning IIOP

For deployment environments in which you expect the IIOP path to support more than a handful of concurrent users, you should experiment with the tuning guidelines described in this section. The default configuration of the JVM and the underlying OS do not yield optimal performance and capacity when you are using IIOP.

This section covers the following topics:


Basic Tuning Approaches

You should experiment with the following tuning recommendations in order to find the best balance for your specific environment.


Solaris File Descriptor Setting
On Solaris, setting the maximum number of open files property using ulimit has the biggest impact on your efforts to support the maximum number of IIOP clients. The default value for this property is 64 or 1024 depending on whether you are running Solaris 2.6 or Solaris 8. To increase the hard limit, add the following command to /etc/system and reboot it once:

set rlim_fd_max = 8192

You can verify this hard limit by using the following command:

ulimit -a -H

Once the above hard limit is set, you can increase the value of this property explicitly (up to this limit) using the following command:

ulimit -n 8192

You can verify this limit by using the following command:

ulimit -a

For example, with the default ulimit of 64, a simple test driver can support only 25 concurrent clients, but with ulimit set to 8192, the same test driver can support 120 concurrent clients. The test driver spawned multiple threads, each of which performed a JNDI lookup and repeatedly called the same business method with a think (delay) time of 500ms between business method calls, exchanging data of about 100KB.

These settings apply to both IIOP clients (on Solaris) and to the IIOP Bridge installed on a Solaris system. Refer to Solaris documentation for more information on setting the file descriptor limits.


Enhancing Scalability

Beyond tuning the capacity of a single Bridge process and client systems, you can improve the scalability of the IIOP environment by using multiple IIOP Bridge processes. You may find that configuring multiple Bridge processes on the same application server instance improves the scalability of your application deployment. In some cases, you may want to use a number of application server instances each configured with one or more Bridge processes.

In configurations where more than one Bridge process is active, you can partition the client load by either statically mapping sets of clients to different Bridges or by implementing your own logic on the client side to load balance against the known Bridge processes.


Viewing IIOP Log Messages

Log messages generated by the IIOP path can be monitored by reviewing the log file generated by the IIOP Bridge process. Since the IIOP Bridge process is a form of a Java Engine (kjs), you monitor these logs in the same manner as you would monitor the Java Engines supporting the web and EJB containers. To view the appropriate log file, you must identify the Java Engine that is playing the role of the IIOP Bridge.

Most developers use the tail -f command to monitor the application server log files of the process of interest. To monitor the Java Engine logs in this manner, follow these steps:

  1. Navigate to the logs directory:

    cd install_dir/ias/logs

  2. Execute the tail command on one of the Java Engine (kjs) and the Executive Service (kxs) processes:

    tail -f kjs_2*

    You must select the appropriate Java Engine log file to monitor. Java Engines are numbered according to how they are defined in the Administration Tool. Although the CXS (Bridge) process is typically the highest numbered Java Engine log file, double check the port number information within the log file to confirm which log files is generated by the CXS process.

  3. Press Control-C to kill the tail command.


Sample C++ IIOP Applications

The Currency Converter sample application from Sun's J2EE Developer's Guide has been bundled with iPlanet Application Server. This sample has been augmented with detailed setup instructions for deploying the application to iPlanet Application Server. It is recommended that you follow the detailed setup instructions for this sample and exercise the Converter sample prior to deploying other IIOP-based applications. Currency Converter setup documentation and source code are available at the following locations:

install_dir/ias/ias-samples/j2eeguide/docs/converter.html

install_dir/ias/ias-samples/j2eeguide/converter/src/


Redeploying the Converter Sample for Use with a C++ Client

Because deployed beans must not have package names and class names differing only in case, you must follow these steps to redeploy the converter example for use with a C++ IIOP client. You can use similar steps to redeploy other examples.

  1. cd ias_inst_dir/ias/ias-samples/j2eeguide

  2. cp -R converter myconverter

  3. cd myconverter/src

  4. Change package and other names in the build.xml, ejb-jar.xml, web.xml, application.xml, and schema/*.xml files as in the following table:


    Table 10-2    Changes to XML files for the Converter sample

    What to Change

    Before

    After

    package name  

    converter  

    myconverter  

    appname, display-name, and context-root  

    j2eeguide-converter  

    j2eeguide-myconverter  

    ejb-name and ejb-link  

    MyConverter  

    MyMyConverter  

  5. Execute this command:

    ias_inst_dir/ias/bin/kguidgen

  6. Copy the above generated guid, and replace the guid value in the <guid> section of the ias-ejb-jar.xml file.

  7. Execute this command again:

    ias_inst_dir/ias/bin/kguidgen

  8. Copy the above generated guid and replace the guid value in the <guid> section of the ias-web.xml file.

  9. mv j2eeguide/converter j2eeguide/myconverter

  10. cd j2eeguide/myconverter

  11. Change all the Java files to reflect the change in package names (for example, change converter to myconverter) and in ConverterClient.java, change the lookup name from MyConverter to MyMyConverter.

  12. cd ../..

  13. ias_inst_dir/ias/bin/build

  14. cd ../assemble/ear

  15. ias_inst_dir/ias/bin/iasdeploy deployapp j2eeguide-myconveter.ear

  16. For iPlanet Application Server version 6.0 SP2 and prior versions, perform these additional steps:

    1. Edit the ias_inst_dir/ias/bin/kjs script and add the new directory ias_inst_dir/ias/APPS/j2eeguide-myconverter/j2eeguide-myconverterEjb to the classpath.

    2. Restart the iPlanet Application Server.


Previous     Contents     Index     Next     
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated March 06, 2002