JavaTM RMI Release Notes
Changes in J2SE 5.0
- Dynamic Generation of Stub Classes
- This release adds support for the dynamic generation of stub classes at runtime, obviating the need to use the Java(tm) Remote Method Invocation (Java RMI) stub compiler,
rmic, to pregenerate stub classes for remote objects. Note that
rmicmust still be used to pregenerate stub classes for remote objects that need to support clients running on earlier versions.
When an application exports a remote object (using the constructors or static
exportObjectmethods1 of the classes
java.rmi.activation.Activatable) and a pregenerated stub class for the remote object's class cannot be loaded, the remote object's stub will be a
java.lang.reflect.Proxyinstance (whose class is dynamically generated) with a
java.rmi.server.RemoteObjectInvocationHandleras its invocation handler.
An existing application can be deployed to use dynamically generated stub classes unconditionally (that is, whether or not pregenerated stub classes exist) by setting the system property
"true". If this property is set to
"true", pregenerated stub classes are never used.
- If a remote object has pre-5.0 clients, that remote object should use a stub class pregenerated with
rmicor the client will get an
ClassNotFoundExceptiondeserializing the remote object's stub. Pre-5.0 clients will not be able to load an instance of a dynamically generated stub class, because such a class contains an instance of
RemoteObjectInvocationHandler, which was not available prior to this release.
- Prior to the J2SE 5.0 release, exporting a remote object would throw a
java.rmi.StubNotFoundExceptionif the pregenerated stub class for the remote object's class could not be loaded. With the added support for dynamically generated stub classes, exporting a remote object that has no pregenerated stub class will silently succeed instead. A user deploying a server application to support pre-5.0 clients must still make sure to pregenerate stub classes for the server's remote object classes, even though missing stub classes are no longer reported at export time. Such errors will instead be reported to a pre-5.0 client when it deserializes a dynamically generated stub class.
1 The static method
UnicastRemoteObject.exportObject(Remote)is declared to return
java.rmi.server.RemoteStuband therefore cannot be used to export a remote object to use a dynamically generated stub class for its stub. An instance of a dynamically generated stub class is a
java.lang.reflect.Proxyinstance which is not assignable to
- Standard SSL/TLS Socket Factory Classes
- This release adds standard Java RMI socket factory classes,
javax.rmi.ssl.SslRMIServerSocketFactory, which communicate over the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocols using the Java Secure Socket Extension (JSSE). These socket factory classes provide a simple way to use JSSE with Java RMI, enabling enforcement of integrity, confidentiality (through encryption), server authentication, and (optionally) client authentication for remote method invocations. For more information on how to use custom socket factories with Java RMI, see the tutorial "Using Custom Socket Factories with Java RMI". For more information on JSSE (including how to configure it), see the JSSE Reference Guide.
rmidor a Java RMI Server from
- A new feature, provided by the
System.inheritedChannelmethod, allows an application to obtain a channel (
java.nio.channels.ServerSocketChannel, for example) inherited from a process that launched the virtual machine (VM). Such an inherited channel can be used to either service a single incoming connection (in the case of a
SocketChannel) or accept multiple incoming connections (in the case of
ServerSocketChannel). Therefore, Java networking applications launched by
inetd(Solaris(tm) Operating System) or
xinetd(Linux) can now obtain the
With the addition of this feature, the Java RMI activation daemon
rmidhas been enhanced to support being launched from
rmidcan be started up only when it receives an incoming connection. For details on the enhancements to
rmidto support this feature, see the tools page for
rmid(for the Solaris Operating System). For details on how to configure
rmid, see the tutorial "Configuring
An application using Java RMI can also be designed to be launched from
xinetd. For an example on how to implement this technique, see the tutorial "Designing Services to be Launched from
- Serialization Enhancements
- See the Serialization Release Notes for more information on enhancements and improvements to Object Serialization in J2SE 5.0.
Enhancements and Changes in Previous Releases
rmicdefault stub protocol version option now
rmicis run without an option to specify the JRMP stub protocol version to be used by the generated classes, it now behaves as if the
-v1.2option were specified, instead of the
-vcompatoption as in previous releases.
This change means that by default,
rmicdoes not generate any skeleton classes and generates stub classes that only implement the 1.2 stub protocol version. If a remote implementation class needs to be built to support clients running on JDK 1.1, then the
-vcompatoption must now be specified explicitly. (Also, note that as described above, if a remote implementation class does not need to support clients running on any release prior to 5.0, then
rmicdoes not need to be run at all for that class.)
See the tools documentation for
rmic[Solaris and Linux] [Windows] for more information about these command line options.
rmicno longer compiles arbitrary source files in the class path
- In previous releases,
rmicwould sometimes, while processing its input class files, attempt to compile arbitrary
.javasource files that it encountered in the class path. In 5.0,
rmicdoes not attempt to compile any source files other than those for the stub, skeleton, or tie classes that it generates.
The expectation is that the remote implementation classes passed to
rmic, as well as all classes and interfaces that they depend on, have already been successfully compiled with
rmicis run. If an existing build procedure depends on the previous behavior of
rmicfor compiling some of its application source files, then that build procedure will need to be modified to ensure that all necessary classes are correctly compiled with
- Server-side Stack Traces Now Retained in Remote Exceptions (since 1.4)
- The Java RMI runtime implementation will now preserve the server-side stack trace information of an exception that is thrown from a remote call, in addition to filling in the client-side stack trace as it did in previous releases. Therefore, when such an exception becomes accessible to client code, its stack trace will now contain all of its original server-side trace data followed by the client-side trace.
This feature is made possible by the new "programmatic access to stack trace information" feature of java.lang.Throwable in J2SE 1.4, which included making a
Throwable's stack trace data part of its default serialized form. What the client-side Java RMI runtime implementation now does to cooperate with this feature is to append the client-side trace to the unmarshalled server-side trace, rather than simply overwriting with the client-side trace as it did in previous releases.
Certain server applications may wish to prevent any server-side stack trace data from accompanying an exception to be marshalled as the result of a remote call (as part of the exception's default serialized form in J2SE 1.4), perhaps for reasons of performance or confidentiality. In such cases, the implementation-specific system propertycan be set to "true" to cause the server-side Java RMI runtime implementation to clear the stack traces of all exceptions thrown from the current virtual machine as the result of remote method invocations.sun.rmi.server.suppressStackTraces
- Service Provider Interface for
- Certain static methods of
java.rmi.server.RMIClassLoadernow delegate their behavior to an instance of a new service provider interface,
java.rmi.server.RMIClassLoaderSpi. The service provider can be configured to augment the Java RMI dynamic class loading behavior for a given application. By default, the service provider implements the standard behavior of all of the static methods in
RMIClassLoader. See the class documentation of
RMIClassLoaderSpifor more details.
- Dynamic Server Host Name (since 1.4)
java.rmi.server.hostnameproperty can now be dynamically updated to indicate that future exports should use a new host name. Therefore, the new host name value will be contained in the stub for an object that is exported after the property is updated.
- HTTP Fallback Is More Configurable (since 1.4.1)
- The implementation-specific system property
sun.rmi.transport.proxy.eagerHttpFallbackhas been added to allow additional control over when the Java RMI default socket factory will fall back to HTTP tunneling. This property configures the default socket factory so that any SocketException thrown by an initial (direct) connection attempt will trigger HTTP tunneling; this more "eager" fallback strategy can be useful when dealing with firewalls which deny instead of ignore connection attempts to unauthorized ports.
java.rmi.Naming.listMethod No Longer Prepends a Scheme to Names Returned (since 1.4.1)
- In previous releases, the
Naming.listmethod prepended the scheme
rmi:to each name contained in the returned array of strings. The
Naming.listimplementation now matches the specification, returning an array of names that are URL-formatted, but without the scheme component.
getClassNamemethod, which returns the group's class name, can now return
null, indicating the system's default group implementation. Previously, the
getClassNamemethod would return the name of the internal implementation class if the default group implementation was chosen when the descriptor was constructed.
Due to this change, if an application running in a 1.3 virtual machine registers an new activatable object with the
rmidmust also be upgraded to run 1.3, since a pre-1.3
rmidwill not be able to activate the newly registered activatable object.
- The Java RMI Stub Compiler,
- By default,
rmic[Solaris and Linux] [Windows] now assumes that the destination directory for generated stubs is the package-named subdirectory of the current working directory. If the "
-d" option is not specified, the result is the same as though it were specified with the current working directory "." as an argument. The "
-d" may still be used to override the default destination directory.
Two new options, "
-idl" and "
-iiop" have been added to generate IDL and stubs for IIOP, respectively.
- The Java RMI Activation Daemon,
- By default,
rmid[Solaris and Linux] [Windows] now requires a security policy file.
- Serializing remote objects (since 1.2.2)
- Prior to 1.2.2, an attempt to pass an unexported remote object in a RMI call would result in a
java.rmi.StubNotFoundException. This exception was a result of the RMI runtime's failure to locate a stub object during an attempt to replace a remote object implementation with its corresponding stub. In 1.2.2 and later releases, an unexported remote object passed in an RMI call will no longer result in an exception, but rather the remote object will be serialized instead of its stub. If the remote object implementation is not serializable, an attempt to pass an unexported object in an RMI call will result in a
java.rmi.RemoteExceptionwith the nested exception
2004 Sun Microsystems, Inc. All Rights
Please send comments to: email@example.com