RMI and Object Serialization
Prebeta Release Notes
These release notes contain the following sections:
- This RMI Prebeta release has no expiration date.
- This RMI Prebeta release is compatible with:
- JDK 1.0.2 on Solaris
- JDK 1.0.2 on Win95/NT
- A special HotJava release for RMI on Win95/NT and Solaris
- This RMI Prebeta release requires local installation of the
rmi package appropriate for Solaris or Win95/NT.
The Prebeta release of RMI runs in a special version of HotJava. If you use this
RMI specific version of HotJava, see the README for important details.
RMI based applets can also be run in the JDK1.0.2 appletviewer.
Since
RMI and Object Serialization are part of the JDK core, full support in
all Java enabled browsers will be available when each Java licensee
incorporates the JDK1.1 release. In the interim, support for Netscape
will be available with a soon to be released plug in.
The RMI Prebeta release ships with two entirely new examples. The first is
a distributed version of Hello World, which has an accompanying Getting
Started doc 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.
This section lists most of the changes made to the API. For complete
API details, see the Remote Method Invocation Specification.
- Applets built with this RMI Prebeta release can be run in the appletviewer
and in a specially built version of HotJava that can be downloaded.
- RMI calls from clients behind firewalls are now supported. See
RMI Through Firewalls via a CGI Program below for details.
Also see
the RMI Specification for architectural details.
- Callbacks from the Applet host to remote objects exported by
applets are now supported if allowed by network security policies.
- Name changes:
- UnicastRemoteServer -> UnicastRemoteObject
- java.rmi.server.ClientClassDisable -> java.rmi.server.useCodebaseOnly
- java.rmi.server.StubClassBase -> java.rmi.server.codebase
- java.rmi.server.StubSecurityManager -> java.rmi.RMISecurityManager
- java.rmi.server.StubClassLoader -> java.rmi.server.RMIClassLoader
- Exception names have been changed and new exceptions have been added.
See Appendix A of the RMI Specification for a complete listing.
- A number of classes and interfaces that were not previously public have
been made public. These are in the package java.rmi.server and the
package java.rmi.dgc.
- The RemoteException class now extends java.io.IOException instead of
java.lang.Exception.
- Changes to the class java.rmi.server.RemoteServer
- The method getClientPort is no longer part of the API.
- The method setLog logs RMI calls to the specified output stream
- The method getLog returns the stream for the RMI call log so that
application specific information can be written to the call log
in a synchronized manner.
- The java.rmi.server.RMIClassLoader class has two new methods:
loadClass(URL, String) and loadClass(String).
- The method java.rmi.server.UnicastRemoteObject.clone returns a clone
of the remote object that is distinct from the original.
- No longer part of API:
- The RegistryImpl class. Registries are now created via the new method
java.rmi.registry.LocateRegistry.createRegistry or the rmiregistry
command.
- The classes java.rmi.server.MarshalOutputStream and
java.rmi.server.MarshalInputStream.
- Objects must explicitly declare that they can be sent outside their
VM by implementing either the interface java.io.Serializable or the
interface java.io.Externalizable. Most of the Java classes in the
java.lang and java.util packages are serializable, as are the Java
primitive types.
Objects implementing the interface java.io.Externalizable must implement
the new writeExternal method to save the entire state of the object and
the readExternal method to restore the entire state of the object.
The Prebeta Object serialization treats the following JDK1.0.2
classes (and their subclasses) as Serializable though they do not
implement the Serializable interface:
java.lang.Character, Boolean, String, Throwable, Number,
StringBuffer,
java.util.Hashtable, Random, Vector, Date, BitSet,
java.io.File,
java.net.InetAddress,
java.awt.BorderLayout, Color, Dimension, Event, Font,
Polygon, CardLayout, FontMetrics, Image,
Window, FlowLayout, GridLayout, Point,
Rectangle, MenuComponent, Insets, CheckboxGroup,
MediaTracker, GridBagLayout, GridBagConstraints,
Cursor
- The readObjectCleanup method is no longer part of the API.
- The new class java.io.ObjectStreamClass provides information about classes
that are saved in a Serialization stream.
- java.lang.FingerPrintClass and java.io.SHAOutputStream are no longer
part of the API.
- 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
streams and from which it can read. For example:
static final long serialVersionUID = 3487495895819393L;
To retrieve this value, use the getSerialVersionUID method of the
ObjectStreamClass class or the serialver program that is part of
the RMI distribution.
- Changes to the OutputObjectStream class:
- Extends OutputStream instead of DataOutputStream. (The methods of
DataOutput are still available because the OutputObjectStream class
implements the DataOutput interface.)
- All methods for writing primitive types have been specified.
- The defaultWriteObject method implements the default serialization
mechanism for the current class. This method may be called only from
a class's writeObject method.
- The enableReplaceObject method is used by trusted subclasses of
ObjectOutputStream to enable the substitution of one object for
another during serialization.
- The reset method resets the stream state to be the same as if it
had just been constructed. This is useful when the contents of an
object or objects must be sent again.
- The methods close, flush, and drain.
- The writeStreamHeader method writes the magic number and version
to the stream.
- Changes to the InputObjectStream class:
- Extends InputStream instead of DataInputStream. (The methods of
DataInput are still available because InputObjectStream implements
the DataInput interface.)
- All methods for reading primitive types have been specified.
- The defaultReadObject method is used to read the fields of an object
from the stream. It uses the class descriptor in the stream to read
the fields by name and type from the stream. This method may be called
only from a class's readObject method.
- The enableResolveObject method is used by trusted subclasses of
ObjectInputStream to enable the monitoring or substitution of one
object for another during deserialization.
- The methods available and close.
- The readStreamHeader method reads and verifies the magic number
and version of the stream.
- Changes to the java.io.ObjectOutput interface:
- The method getNestedStream is no longer part of the API.
- The write(int b), write(byte b[]), and write((byte b[], int off, int len)
methods have been added.
- The methods flush and close have been added.
- Changes to the java.io.ObjectInput interface:
- The method getNestedStream is no longer part of the API.
- The read(int b), read(byte b[]), and read((byte b[], int off, int len)
methods have been added.
- The methods skip, available, and close method have been added.
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:
Copy the file "$RMIHOME/lib/solaris/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
and the RMI classes on the host machine, as noted in the script
comments.
On Windows 95/NT:
Copy the file "$RMIHOME/lib/win32/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, and the system CLASSPATH
variable must include "%RMIHOME%/lib/classes.zip".
- java.rmi.server.Unreferenced is now implemented.
- At Alpha2, applets that exported remote objects had to be allowed
by the SecurityManager to use ServerSockets to listen for and accept
incoming socket connections. This is no longer necessary.
- Interface classes can now be loaded dynamically from codebase. This is
made possible by a work around for the bug in how the JDK 1.0.2 VM
resolves interfaces.
- The equals method now correctly compares a remote object equal to itself
if it is sent from a server S to a client C as the return
value of a remote method, and then C sends that same object back to S.
- rmic now correctly generates code in the case where one remote implementation
extends another remote implementation. The remote methods from the extended
class now appear in the stub as they should.
- rmic now correctly finds all of the remote interfaces that are inherited
and properly generates the stub methods for those
remote interfaces.
- rmic now correctly allows static initializers in remote interfaces.
- The RMI release replaces a few existing JDK files in order for
prebeta RMI to be as compatible as possible with JDK1.1 RMI. Here is a
list of those files:
java.io.File (for serialization compatibility)
java.net.InetAddress (bug fix)
java.util.Hashtable (for serialization compatibility)
java.util.Date.java (for serialization compatibility)
sun.net.www.protocol.file.Handler (bug fix)
- A fix is provided to the JDK 1.0.2 java.net.InetAddress class so that
it supports hostnames that are raw IP addresses.