RMI-IIOP

Hello Sample

IBM Developer Kit for Windows(R) Java(TM) 2 Technology Edition, Version 1.2.2

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:

RemoteHello.java - the remote interface
RemoteHelloServer.java - the remote server
RemoteHelloApplet.java - a client applet
RemoteHelloApplication.java - a client application
jrmp.html - HTML for applet with JRMP settings
iiop.html - HTML for applet with IIOP settings

To provide a complete explanation in the steps that follow, we make the following assumptions:

A server named aslan.narnia.com.
A running HTTP server with root %SERVER_ROOT%. Class files resulting from a sample build go into a codebase of %SERVER_ROOT%\java. Classes in this directory will be loaded remotely; files to be copied into this directory will be listed in the instructions below.

Setting Up the Environment

Set your CLASSPATH environment variable so that the current directory (".") is at the beginning. Check that your PATH environment variable includes %JAVA_HOME%\sdk\bin;%JAVA_HOME%\sdk\jre\bin, 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 %JAVA_HOME%\demo\rmi-iiop\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 %JAVA_HOME%\demo\rmi-iiop\hello.

Compile all java files.

     javac *.java

Change directory to %JAVA_HOME%\demo\rmi-iiop.

     cd ..

Compile the stubs with rmic.

For JRMP:

       rmic hello.RemoteHelloServer

For IIOP:

       rmic -iiop hello.RemoteHelloServer

Copy iiop.html and jrmp.html to %SERVER_ROOT% (the HTTP server root). Copy the following files to %SERVER_ROOT%\java\hello:

RemoteHello.class
RemoteHelloApplet.class
RemoteHelloServer_Stub.class (for JRMP)
_RemoteHello_Stub.class (for IIOP)

%SERVER_ROOT%\java

codebase

hello

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

Start an HTTP server.
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.

Note:

not

samples

RMI

For JRMP:

      rmiregistry

rmi-iiop

For IIOP:

       tnameserv

From %JAVA_HOME%\demo\rmi-iiop 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 "/".

For JRMP:

       java -Djava.rmi.server.codebase=http://aslan.narnia.com/java/
            -Djava.security.policy=policy
            -Djava.naming.factory.initial=com.sun.jndi.rmi.registry.RegistryContextFactory
            hello.RemoteHelloServer

For IIOP:

       java -Djava.rmi.server.codebase=http://aslan.narnia.com/java/
            -Djava.security.policy=policy
            -Djava.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactory
            hello.RemoteHelloServer

From %JAVA_HOME%\demo\rmi-iiop 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.

For JRMP:

       java -Djava.rmi.server.codebase=http://aslan.narnia.com/java/
            -Djava.security.policy=policy
            -Djava.naming.factory.initial=com.sun.jndi.rmi.registry.RegistryContextFactory
            hello.RemoteHelloApplication aslan.narnia.com

For IIOP:

       java -Djava.rmi.server.codebase=http://aslan.narnia.com/java/
            -Djava.security.policy=policy
            -Djava.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactory
            hello.RemoteHelloApplication aslan.narnia.com

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:
- For JRMP:
- For IIOP:

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.