Java

RMI-IIOP

Hello Sample

Copyright © 1999 Sun Microsystems, Inc. 
Copyright © 1999 International Business Machines Corporation. All Rights Reserved.


The RMI-IIOP Hello Sample

This is the classic "Hello World!" application adapted to RMI-IIOP. While similar to the Hello World sample presented in the "RMI-IIOP Programmer's Guide" this sample illustrates developing an RMI program that can be built and run for either the JRMP or IIOP protocols with the "flip of a switch". The "switch" we refer to is an -iiop switch used with the rmic compiler. You also need to pass a different system/applet environment setting to the java command using the -D option, but the code itself need not be changed. This sample illustrates both application and applet client.

The Files

The sample code is found in the $JAVA_HOME/demo/rmi-iiop/hello directory. There you will find the following files: To provide a complete explanation in the steps that follow, we make the following assumptions:

Setting Up the Environment

Set your CLASSPATH environment variable so that the current directory (".") is at the beginning. Set your PATH environment variable to include $JAVA_HOME/sdk/sh:$JAVA_HOME/sdk/jre/sh, where JAVA_HOME is the directory where the Java SDK is installed.

Note: Don't forget to set up a security policy file. See the following section for instructions.

A Note About Security Policy Files

The JDK 1.2 security model is more sophisticated than the JDK 1.1 model. JDK 1.2 contains enhancements for finer-grained security and requires code to be granted specific permissions to be allowed to perform certain operations. In JDK 1.1 code in the class path is trusted and can perform any operation; downloaded code is governed by the rules of the installed security manager. If you run this example in JDK 1.2, you need to specify a policy file when you run your server and client. In this example, for simplicity, we will use a policy file that gives global permission to anyone from anywhere. Do not use this policy file in a production environment. For more information on how to properly open up permissions using a java.security.policy file, please refer to the following documents:
    http://java.sun.com/products/jdk/1.2/docs/guide/security/PolicyFiles.html
    http://java.sun.com/products/jdk/1.2/docs/guide/security/permissions.html
Create a policy file called $DEMO_HOME/policy containing the following code:
   grant {
      permission java.security.AllPermission;
   };
The RMI section in the Java Tutorial contains a discussion of policy files.

Building the Hello Sample

After configuring your environment, as explained above, change directory to $DEMO_HOME/hello.
  1. Copy the demo files to your demo build directory:
    1. cp $JAVA_HOME/demo/rmi-iiop/hello/*.java .
  2. Compile all java files.
  3.      javac *.java
  4. Change directory to $DEMO_HOME.
  5.      cd ..
  6. Compile the stubs with rmic.
  7. Copy iiop.html and jrmp.html to $SERVER_ROOT (the HTTP server root).  Copy the following files to $SERVER_ROOT/java/hello:
  8. Remember that $SERVER_ROOT/java is your codebase, and that hello is the package name.

Running the Hello Sample

The following assumes that the server is run on a host named aslan.narnia.com, that an http server is running, and that the code base is a "java" directory under the server's root and that the class files are in a "hello" directory under "java".
  1. Start an HTTP server.
  2. Run the name server that will be used to resolve the name RemoteHelloServer to an RMI server. The name server you run depends on whether you will be using JRMP or IIOP. The name server must be started in a separate process.

  3. Note: Run your naming service from an environment (shell) where your CLASSPATH does not include the samples directory. See the RMI documentation for an explanation.
  4. From $DEMO_HOME run the server, passing parameters to the system with the -D option. There are a couple of details to pay attention to here. First, these commands are all one line, even though the formatting in this document may make them appear to have carriage returns. Second, there must be no space between the -D and the property text that follows it. Finally, the codebase property must end with a "/".
  5. From $DEMO_HOME run the application. Pass the host address of the server to the application as a command line parameter. Pay attention to the same details described in the last step.
  6. Run the applet. This is easiest to do using the appletviewer. To use a browser such as Internet Explorer or Netscape Navigator you will need to modify jrmp.html or iiop.html to enable the browser to use the Java plug-in. Details of the Java plug-in can be found on the following website:
      http://java.sun.com/products/plugin

Errors

There are several steps involved and it is easy to make a mistake. You may build for one protocol and run for another, run the wrong name server for the protocol, or forget to copy class files, for example. Here are a couple of errors (exceptions) you may encounter and what they mean.
 
 
Exception  Probable Cause 
java.lang.ClassCastException The stub class file cannot be found in the client class path 
java.lang.NoClassDefFound The interface class file cannot be found in the client class path 
java.rmi.ConnectException Either the server has not been started or you are running a client for the wrong protocol 

The Hello IDL Sample

Next, you might want to look at the Hello IDL sample. Hello IDL shows how an RMI-IIOP program interoperates with a conventional IDL program.