RMI Release Notes

JDK 1.2 Contents

Remote Method Invocation (RMI) has several new enhancements. Remote Object Activation introduces support for persistent references to remote objects and automatic object activation via these references. Custom RMI client and server socket factories allow a remote object to specify the custom socket type that RMI will use for remote calls to that object. RMI over a secure transport (such as SSL) can be supported using custom socket factories. Minor API Enhancements allow the following: unexporting a remote object, obtaining the stub for an object implementation, obtaining a local object implementation from a stub, and exporting an object on a specific port.

• Remote Interfaces
• A remote interface can now extend an interface that does not extend java.rmi.Remote as long as all of the methods throw a legal remote exception type (see Remote Exceptions, next).
• Remote Exceptions
• A remote interface method can alternatively use any of the superclasses of java.rmi.RemoteException, such as java.io.IOException or java.lang.Exception, instead of RemoteException in the throws clause of the method.

Spurious "RMI ... using multiplexed connections instead" messages when using Windows NT and NIS

If Solstice^TM Network Client^TM is installed on a Windows NT machine and NIS is selected as the primary name service, it may produce spurious UnknownHostException errors due to network timeouts. These errors cause the RMI subsystem to enable its multiplexed mode of operation, producing the following warning on the console (System.out):

*** RMI unable to listen on socket: using multiplexed connections instead ***

To work around this problem, start the Network Control Panel, select the Services tab, select the NIS service, press the Properties button, select NIS in the list of active name services at the bottom of the window and press the Down button until the NIS entry is at the bottom of the list. Press OK on all the dialogs. You will be prompted to reboot.

• java.rmi.server.RemoteServer
• The method unexportObject has been moved to the two subclasses of RemoteServer, java.rmi.server.UnicastRemoteObject and java.rmi.activation.Activatable.
• java.rmi.server.SocketType
• The class SocketType has been removed and replaced with a more flexible mechanism for using custom socket factories on a per-remote-object basis. We have introduced two new interfaces, java.rmi.server.RMIClientSocketFactory and java.rmi.server.RMIServerSocketFactory, that can be specified when a java.rmi.server.UnicastRemoteObject or java.rmi.activation.Activatable object is constructed/exported. The RMI runtime uses the specified RMIServerSocketFactory to create a ServerSocket to accept incoming calls for the remote object. The remote object's reference contains a reference to an RMIClientSocketFactory which is downloaded to clients, when transmitted in an RMI call, and is used to make connections to the remote object for a remote method call. The reason we replaced the SocketType abstraction with the custom client and server socket factories is to allow a client socket factory to be downloaded into applets so that no client-side socket factory installation is required. The constructors and exportObject methods of java.rmi.server.UnicastRemoteObject and java.rmi.activation.Activatable that previously took a SocketType as one of their arguments have been modified to take the custom socket factories as parameters instead.
• java.rmi.server.RMISocketFactory
• The RMISocketFactory class now implements java.rmi.server.RMIClientSocketFactory and java.rmi.server.RMIServerSocketFactory. The createSocket and createServerSocket methods that took a java.rmi.server.SocketType as a parameter have been removed.
• java.rmi.server.UnicastRemoteObject
• The UnicastRemoteObject class has several modified constructors and exportObject methods, and a new unexportObject method. The constructors and exportObject methods have been changed to used a java.rmi.server.RMIClientSocketFactory and java.rmi.server.RMIServerSocketFactory as arguments instead of a java.rmi.server.SocketType. The unexportObject method was moved from java.rmi.server.RemoteServer to UnicastRemoteObject.
• java.rmi.registry.LocateRegistry
• Two new methods, createRegistry and getRegistry, have been added to the LocateRegistry class. The createRegistry method allows you to create a remote object registry that uses custom client and server socket factories for communication with that registry. The getRegistry method returns a locally-created reference to a remote object registry that uses a specified RMIClientSocketFactory to obtain sockets to communicate with that remote registry.
• java.rmi.RMISecurityManager
• The RMISecurityManager has been updated to work with the new JDK1.2 security model. Most of the RMISecurityManager methods are no longer overridden since the default behavior of the methods of java.lang.SecurityManager, which it extends, is appropriate for the RMISecurityManager. Please note that if you do use the RMISecurityManager, you will need to use a policy file that lists the permissions that are granted to code from various codebases.
• java.rmi.server.RMIClassLoader
• The RMIClassLoader class has two new methods, getClassAnnotation and a loadClass method that takes a codebase path and a class name as arguments. The getClassAnnotation method returns a string containing the class's codebase path that RMI transmits with the class descriptor in remote method calls, which include an instance of that class in a parameter, return value, or exception. The new loadClass method was added to load a class from a codebase path, which is a string of URLs, each separated by a space.
• java.rmi.activation.Activatable
• The Activatable class has several new constructors and exportObject methods and a new unexportObject method. The new constructors and exportObject methods used a java.rmi.server.RMIClientSocketFactory and java.rmi.server.RMIServerSocketFactory as arguments and facilitate custom communication with activatable objects. The unexportObject method was moved from java.rmi.server.RemoteServer to Activatable. Also note that java.security.CodeSource is no longer used to represent the location of the activatable object's class. Instead, a java.lang.String is used to represent a codebase path from where the class bytecodes can be loaded. A codebase path is a string of URLs separated by a space. Due to this change, the constructors and exportObject methods now take a String instead of a CodeSource for the codebase argument.
• java.rmi.activation.ActivationDesc
• Since we now use a java.lang.String to represent the location (a codebase path) of the activatable object's class, the ActivationDesc constructors now take a String instead of a java.security.CodeSource as the codebase argument. The getCodeSource method has been renamed to getLocation for consistency.
• java.rmi.activation.ActivationGroupDesc
• Since we now use a java.lang.String to represent the location, a codebase path, of the activatable object's class, the ActivationGroupDesc constructor that previously took a java.security.CodeSource as the codebase argument, now takes a String instead. The getCodeSource method has been renamed to getLocation for consistency. ActivationGroupDesc also supports a new scheme for specifying the properties and environment in which a group executes. The new nested class java.rmi.activation.ActivationGroupDesc.CommandEnvironment allows you to specify the command and options that rmid will use to start up a particular activation group.
• java.rmi.server.ObjID
• We have introduced a new property java.rmi.server.randomIDs that, if true, ensures that an ObjID (contained in a remote object reference) contains a cryptographically secure random number. The property defaults to false. If the property is set to true, you will experience several seconds of delay when the first ObjID is generated while the secure random number generator determines its seed.
• java.rmi.server.useLocalHostname property
• RMI now uses an IP address for the local host if the java.rmi.server.hostname property is not specified and a fully-qualified domain name for the localhost cannot be otbained. In order to force RMI to default to the hostname, you need to set the java.rmi.server.useLocalHostname property to true. The useLocalHostname property defaults to false.

• java.rmi.activation.server.RemoteObject
• The method toImpl has been removed since the method cannot be made secure without allowing too many restrictions on its use.
• The accessor method getRef has been added. It returns the remote reference type, a java.rmi.server.RemoteRef for the remote object.
• java.rmi.server.RemoteServer
• The method unexportObject takes an additional parameter force and returns a boolean to indicate whether the operation was successful.
• java.rmi.server.UnicastRemoteObject
• Two forms of the exportObject method now return Remote instead of RemoteStub since the former allows more flexibility in future implementations of RMI.
• java.rmi.activation.ActivationDesc
• Two constructors have been added which take an additional parameter, restart, to indicate the restart mode for the object. The restart mode, if set, will cause the object to be restarted when the RMI activation daemon starts; otherwise, the object is simply activated on-demand.
• An additional method getRestartMode returns the restart mode for the object.
• java.rmi.activation.Activatable
• An additional constructor that takes a restart parameter.
• The register method now returns Remote instead of RemoteStub since the former allows more flexibility in future implementations of RMI.
• The inactive method now returns a boolean that indicates whether the object was deactivated successfully. An object can only be deactivated if it has no pending or executing calls.
• An additional exportObject method was added that is similar to the first but takes another parameter restart that indicates the restart mode of the object.
• java.rmi.activation.ActivationSystem
• An additional method shutdown has been added to provide a means for graceful shutdown of the activation system. Also, a new option, -stop has been added to rmid that invokes the shutdown method of the ActivationSystem running on the default or specified port.
• java.rmi.activation.ActivationGroup
• The method inactiveObject now returns a boolean that indicates whether the operation was successful.

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

Java Software