RMI Release Notes - JDK 5 Documentation v1.2.2, Java 2 SDK 英文文档

RMI Release Notes

Contents of the
Java^TM 2 SDK,
Standard Edition,
v 1.2

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.

Changes to Remote Interface Definition

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.

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 because the RMI runtime, in its attempt to replace the remote object implementation with its corresponding stub object, could not locate the stub. While normal correct operation is unaffected, 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.
This functionality was added to support the marshalling of stub objects unknown to the RMI runtime, such as RMI/IIOP stubs.

Known Problems

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

^TM

UnknownHostException

System.out

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

API Changes Since Java ^TM 2 SDK, v1.2 Beta3

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 Java ^TM 2 SDK, v1.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.

API Changes Since Java 2 SDK, v1.2 Beta2

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.

Java Software