#

# RMI-IIOP

# Hello Sample

Copyright © 1999 Sun Microsystems, Inc.
Copyright © 1999,2003 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:

- `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 writable build directory of `$DEMO_HOME` (for example `$HOME/rmi-iiop/demo`).
- 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/bin:$JAVA_HOME/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.4.1/docs/guide/security/PolicyFiles.html
- http://java.sun.com/products/jdk/1.4.1/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.

          cp $JAVA_HOME/demo/rmi-iiop/hello/*.java .

2. Compile all java files.

       javac *.java

3. Change directory to `$DEMO_HOME`.

       cd ..

4. Compile the stubs with `rmic`.

- For JRMP:

    rmic hello.RemoteHelloServer

- For IIOP:

    rmic -iiop hello.RemoteHelloServer

5. Copy the following files to `$SERVER_ROOT` (the HTTP server root):

- `iiop.html`
- `jrmp.html`

6. Copy the following files to `$SERVER_ROOT/java/hello`:

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

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, so it is easiest to start it in its own window.
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.

- For JRMP:

    rmiregistry

- For IIOP:

    tnameserv

3. From `$DEMO_HOME` run the server, passing parameters to the system with the `-D` option.
There are several 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

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

- 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

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

- For JRMP:

    appletviewer http://aslan.narnia.com/jrmp.html

- For IIOP:

    appletviewer http://aslan.narnia.com/iiop.html

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