Previous     Contents     Index     DocHome     Next     
iPlanet Application Server Developer's Guide (Java)



Chapter 9   Developing and Deploying RMI/IIOP-Based Clients


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

This chapter contains the following sections:



Overview of RMI/IIOP Support

iPlanet Application Server supports access to EJBs via the RMI/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.

The following topics are covered in this overview:


Scenarios

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


Stand-Alone Java Main Program

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

Figure 9-1    Stand-alone Java main program




Server-to-Server

Java-enabled web servers, Java-based CORBA objects, and even other application servers can use RMI/IIOP to access EJBs housed in an iPlanet Application Server, as shown in Figure 9-2.

Figure 9-2    Server-to-server




Architectural Overview

RMI/IIOP 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 clients using RMI/IIOP and EJBs deployed to one or more Java Engines acting as EJB containers. For every EJB accessed by RMI/IIOP clients, the 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 9-3.

Figure 9-3    Architecture



Regardless of the Java 2 environment used on the client side, in this release of iPlanet Application Server, you are required to use the ORB that is bundled as part of the Application Server.


iPlanet Value-Added Features

iPlanet's implementation of RMI/IIOP goes beyond the RMI/IIOP specification by providing the following value-added features:


Naming Services

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


Built-in ORB

iPlanet provides a built-in ORB to support RMI/IIOP access to EJBs. You do not have to install and configure a third party ORB to use RMI/IIOP with iPlanet Application Server.


Basic Authentication and EJB Container Integration

Although the RMI/IIOP standards do not yet define a means of performing basic authentication between an RMI/IIOP 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 RMI/IIOP clients.

As an RMI/IIOP 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 RMI/IIOP infrastructure, this information is propagated over IIOP to the Application Server.


Server-Side Load Balancing

As new RMI/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 RMI/IIOP 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.


Scalability

Multiple RMI/IIOP processes can be configured for each application server instance. This feature enables system administrators to configure any number of JVMs dedicated to handling incoming RMI/IIOP requests. Client applications can rotor through a list of the available RMI/IIOP processes or use round-robin DNS to implement basic, client-side load balancing. Administrators can also modify the number of processing threads available for each RMI/IIOP 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: RMI/IIOP 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 RMI/IIOP clients can continue to access EJBs without interruption.


Minimal Ports Opened in Firewalls

The RMI/IIOP Bridge processes 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 RMI/IIOP clients and iPlanet Application Server instances on which Bridge processes are configured.


Limitations

RMI/IIOP in iPlanet Application Server has the following limitations:

  • It does not support C++ clients.

  • 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.



Developing RMI/IIOP Client Applications

Developing RMI/IIOP-based client applications to work with iPlanet Application Server is very similar to developing clients for 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:


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 RMI/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 RMI/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 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 RMI/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.


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 RMI/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 RMI/IIOP Bridge processes are listening. Assuming that you configure all of the RMI/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.



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 application-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-application-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>

  • 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 RMI/IIOP Bridge process configured, you must start the iPlanet Application Server Administrative tool to add an RMI/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 NT:

    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 RMI/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 RMI/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 RMI/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 9-4.

Figure 9-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.2.2) 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 are likely to 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 Java 2 1.2
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.2 distribution has been installed. For example:

export JAVA_HOME=/usr/java1.2

  1. Copy the Java extensions directory from an iPlanet Application Server Solaris installation to your Solaris client system.

    Copy the following directory:

    install_dir/ias/usr/java/jre/lib/ext

    to your Solaris client's JDK installation:

    $JAVA_HOME/jre/lib/ext

    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:

    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.


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

  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/rmiorb.jar

    install_dir/ias/usr/java/jre/lib/ext/iioprt.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/iioprt.jar:/opt/iplanet/orb/rmiorb.jar

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

    export JAVA_HOME PATH CLASSPATH LD_LIBRARY_PATH

  4. When you execute the client application, you must specify the ORB classes associated with the iPlanet ORB. If you do not specify the iPlanet ORB classes, the ORB classes bundled in Java 2 1.3 are used. Since the 1.3 ORB classes are incompatible with the iPlanet ORB, errors result when the 1.3 ORB classes are not overridden.

    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

  5. When you execute your client application, you may encounter the following error:

    ERROR! The shared library ioser12 could not be found.

    Although this error may occur when using Java 2 1.3 on the client side, RMI/IIOP access to EJBs has been demonstrated successfully using Solaris and RedHat Linux clients based on these setup instructions.

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 or Windows and Java 2 1.2
In this scenario, you have already installed a Java 2 1.2 environment on either Windows 98 or 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.2 distribution has been installed. For example:

set JAVA_HOME=JDK1.2.2

  1. Copy the Java extensions directory from an iPlanet Application Server Windows installation to your Windows 98 or Windows client system.

    Copy the directory:

    install_dir\ias\usr\java\jre\lib\ext

    to your client's JDK installation:

    %JAVA_HOME%\jre\lib\ext

    Ensure that the i386\ directory containing DLLs is copied as part of this step. The iPlanet ORB native serialization DLL 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:

    set 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.


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

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

    c:\iplanet\orb\

  2. Copy the following JAR files from the iPlanet Application Server installation to the ORB directory on your Windows system to an appropriate directory on the client system, for example, to c:\iplanet\orb\.

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

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

  3. From within your Windows client, copy the native serialization DLL from the JDK installation area to another directory. For example, copy:

    %JAVA_HOME%\jre\bin\ioser12.dll

    to:

    c:\iplanet\orb\

  4. Before running the client application, ensure that the PATH and CLASSPATH settings include the iPlanet ORB JAR files:

    set JAVA_HOME=c:\jdk1.3

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

    set CLASSPATH=c:\iplanet\orb\iioprt.jar;c:\iplanet\orb\rmiorb.jar;%CLASSPATH%

  5. When you execute the client application, you must specify the ORB classes associated with the iPlanet ORB. If you do not specify the iPlanet ORB classes, the ORB classes bundled in Java 2 1.3 are used. Since the 1.3 ORB classes are incompatible with the iPlanet ORB, errors result when the 1.3 ORB classes are not overridden.

    You can specify the iPlanet ORB classes as properties on the Java command line (the 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.


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 usr/java/bin/. For example, to test RMI/IIOP access locally, set the CLASSPATH variable as follows:

On Windows NT:

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 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 NT:

Set your PATH environment variable to include the appropriate Java 2 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 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 Client Applications."

In iPlanet Application Server Service Pack 2 and earlier, to load EJB classes, the RMI/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 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.



Running 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 RMI/IIOP Bridge is listening on the specified port.



Troubleshooting


When running an RMI/IIOP client, you may encounter error conditions on the client. To view the RMI/IIOP Bridge logs, see "Viewing RMI/IIOP Log Messages." Table 9-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 9-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 RMI/IIOP bridge fails because of one of the following reasons:

  • IIOP host and/or port number are incorrect.

  • RMI/IIOP Bridge process has not been started.

  • RMI/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 RMI/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 RMI/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 RMI/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.2.2. 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 RMI/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 RMI/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 RMI/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 RMI/IIOP Bridge process. Since the RMI/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 RMI/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.0" 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 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


Previous     Contents     Index     DocHome     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated June 14, 2001