JDK Contents

# RMI and Object Serialization

# JDK 1.1 Release Notes

These release notes contain the following sections:

- RMI General Notes
- Serialization General Notes
- RMI through Firewalls via a CGI Program (required under limited conditions)
- Known Limitations and Bugs

## RMI General Notes

1. Two examples illustrate the use of the RMI APIs. The first is a distributed version of Hello World, which has an accompanying Getting Started tutorial that explains the basics of using RMI. The second example is a stock monitoring applet that receives notification when the values of the portfolio change and that demonstrates callbacks from an object exported by the applet.

2. Applets developed with the JDK 1.1 release of RMI can be run in the appletviewer and HotJava 1.0. Full support in all Java enabled browsers will be available when each Java licensee incorporates the JDK 1.1 release. In the interim, RMI on JDK 1.0.2 has a Netscape plug-in that allows RMI based applets to be run in Nescape 3.01.

## Serialization General Notes

1. Objects must explicitly declare that they can be written to an ObjectOutputStream by implementing either the interface `java.io.Serializable` or the interface `java.io.Externalizable`. Many of the core classes implement the `Serializable` interface.

2. Objects implementing the interface `java.io.Externalizable` must implement the `writeExternal` method to save the entire state of the object and the `readExternal` method to restore the entire state of the object.

3. To support versioning of classes, each version of a class except the first must specify the `SerialVersionUID` variable. This variable indicates the original class version for which the current class is capable of writing or reading streams. For example:

             static final long serialVersionUID = 3487495895819393L;

   To obtain this value, use the method `ObjectStreamClass.getSerialVersionUID` or the `serialver` tool.

## RMI through Firewalls via a CGI Program (required under limited conditions)

For a server to support RMI calls from clients behind firewalls that do not foward HTTP requests to arbitrary ports, a CGI program needs to be installed on the server host's default HTTP server (listening on port 80). (Without installion of the CGI program, the server will still support RMI calls from clients behind typical firewalls.)

The CGI program "java-rmi.cgi" is responsible for forwarding HTTP-packaged RMI calls sent to the default HTTP server to be forwarded to an RMI server listening on a port specified in the URL. Specifically, when a POST request is sent with the URL path "/cgi-bin/java-rmi.cgi?forward=", the body of the request will be sent (as another POST request) to the server listening on the specified port (must be >= 1024). The HTTP response from this forwarded request will be the response to the original request.

On Solaris:

In the JDK release, copy the file bin/java-rmi.cgi to the directory to which your HTTP server maps the URL path "/cgi-bin". You will need to edit this script to fill in the proper path for the Java interpreter on the host machine, as noted in the script comments.

On Windows 95/NT:

In the JDK release, copy the file bin/java-rmi.cgi to the directory to which your HTTP server maps the URL path "/cgi-bin". For this program to execute correctly, the system PATH environment variable must include the directory for the Java interpreter.

## Known Limitations and Bugs

- JDK 1.1 and the RMI Prebeta release are not compatible, if you use the `java.rmi.server.UnicastRemoteObject.exportObject` method in your applet or application. This is due to a change in the method signature, which in JDK 1.1 now returns a `RemoteStub` instead of `void`.

- On some network configurations the Registry operations of bind, rebind and unbind will throw an `AccessException` in cases where it should not. The Registry implementation restricts these operations to clients on the same host as the Registry. If the hostname or IP address does not match the exception is thrown. In some DHCP and PPP network configurations the assigned IP address and hostname do not match the name assigned to the node. A workaround is to statically and explicitly assign the IP address for the node.

  On Solaris, another alternative is to change the node name have the IP address assigned by PPP, or to set the nodename to "localhost" which is bound to the IP address 127.0.0.1.

- Applications (servers) that export remote objects may not exit even if all remote objects have been garbage collected (remotely and locally) and there are no other non-daemon threads in the process other than an RMI thread which keeps the process alive. The current workaround is for a server process to call `System.exit()` to exit the application.

- `rmic` does not currently flag an error if a remote interface implemented by a remote class is not public.

- The implementation of the `java.rmi.registry.Registry` interface does not handle stub classes evolving over time. If a remote object implementation adds support for an additional interface after its previous stub was loaded into the registry, object serialization will flag a class mismatch when binding the new stub in the registry. As a workaround, a registry must be stopped and restarted if changes are made to the remote interfaces implemented by remote object implementation classes.

Copyright © 1996 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA 94043-1100 USA. All rights reserved.