RMI Release Notes for J2SETM 1.4.2

Documentation Contents

Changes to RMI for J2SE^TM 1.4.2 included minor bug fixes.

HTTP Fallback Is More Configurable

The implementation-specific system property sun.rmi.transport.proxy.eagerHttpFallback has been added to allow additional control over when RMI's 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.list Method No Longer Prepends a Scheme to Names Returned

In previous releases, the Naming.list method prepended the scheme rmi: to each name contained in the returned array of strings. The Naming.list implementation now matches the specification, returning an array of names that are URL-formatted, but without the scheme component.

java.rmi.server.RemoteServer.setLog Method Now Requires a Permission

The RemoteServer.setLog method now specifies that it throws a SecurityException if the caller does not have permission to set the global call log. The method requires that the calling context has the permission java.util.logging.LoggingPermission("control") to set the log.

java.rmi.server.RMISocketFactory.setFailureHandler Method Now Requires a Permission

The RMISocketFactory.setFailureHandler method now specifies that it throws a SecurityException if the caller does not have permission to set the global java.rmi.server.RMIFailureHandler. The method requires that the calling context has the permission java.lang.RuntimePermission("setFactory") to set the failure handler.

Server-side Stack Traces Now Retained in Remote Exceptions

The 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 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 RMI 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 property

sun.rmi.server.suppressStackTraces

can be set to "true" to cause the server-side RMI runtime implementation to clear the stack traces of all exceptions thrown from the current virtual machine as the result of remote method invocations.

Service Provider Interface for RMIClassLoader

Certain static methods of java.rmi.server.RMIClassLoader now delegate their behavior to an instance of a new service provider interface, java.rmi.server.RMIClassLoaderSpi. The service provider can be configured to augment RMI's 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 RMIClassLoader and RMIClassLoaderSpi for more details.

Dynamic Server Host Name

The java.rmi.server.hostname property 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.

Serializing Primitive Class Objects

In previous releases, a ClassNotFoundException would be thrown if an attempt was made to pass a primitive Class object in an RMI call. Now, an object that contains Class objects for primitive types can be passed as a remote method parameter or return value, and can be stored in a java.rmi.MarshalledObject instance.

Enhanced RMI Implementation Logging

Sun's implementation of RMI in J2SE 1.4 now uses the new Logging APIs to provide implemention-specific logging output. See the RMI Implementation Logging page for more information.

Serialization Enhancements

See the Serialization Release Notes for more information on enhancements and improvements to Object Serialization in J2SE 1.4.

java.rmi.activation.ActivationGroupDesc (since 1.3)

The getClassName method, which returns the group's class name, can now return null, indicating the system's default group implementation. Previously, the getClassName method 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 JVM registers an new activatable object with the ActivationSystem, rmid must also be upgraded to run 1.3, since a pre-1.3 rmid will not be able to activate the newly registered activatable object.

Constructors of activatable objects (since 1.3)

An activatable object's "activation" constructor, which takes an ActivationID and a MarshalledObjectas arguments and which is called by the ActivationInstantiator each time the object is activated, can now be private or protected. Previously, the implementation only allowed public activation constructors.

java.rmi.server.RMIClassLoader (since 1.3)

java.rmi.server.RMIClassLoader has a new method, getClassLoader. This method returns the class loader that RMI uses to load classes from a specified codebase URL path. This API can be used in an implementation that requires complete RMI marshalling/unmarshalling behavior. See java.rmi.server.RMIClassLoader for details.

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.RemoteException with the nested exception java.io.NotSerializableException.

The RMI Stub Compiler, rmic

• By default, rmic 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 RMI Activation Daemon, rmid

By default, rmid now requires a security policy file.

*As used on this web site, the terms "Java virtual machine" or "JVM" mean a virtual machine for the Java platform.

Copyright © 2003 Sun Microsystems, Inc. All Rights Reserved.  Please send comments to: rmi-comments@java.sun.com