java.rmi Documentation Differences

This file contains all the changes in documentation in the package java.rmi as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

An AccessException is thrown by certain methods of the java.rmi.Naming class (specifically bind rebind and unbind) and methods of the java.rmi.activation.ActivationSystem interface to indicate that the caller does not have permission to perform the action requested by the method call. If the method was invoked from a non-local host then an AccessException is thrown. @version 1.9 0210 12/0203/0001 @author Ann Wollrath @author Roger Riggs @since JDK1.1 @see java.rmi.Naming @see java.rmi.activation.ActivationSystem

An AlreadyBoundException is thrown if an attempt is made to bind an object in the registry to a name that already has an associated binding. @version 1.9 0210 12/0203/0001 @since JDK1.1 @author Ann Wollrath @author Roger Riggs @see java.rmi.Naming#bind(String java.rmi.Remote) @see java.rmi.registry.Registry#bind(String java.rmi.Remote)

A ConnectException is thrown if a connection is refused to the remote host for a remote method call. @version 1.10 0211 12/0203/0001 @author Ann Wollrath @since JDK1.1

A ConnectIOException is thrown if an IOException occurs while making a connection to the remote host for a remote method call. @version 1.9 0210 12/0203/0001 @author Ann Wollrath @since JDK1.1

A MarshalException is thrown if a java.io.IOException occurs while marshalling the remote call header arguments or return value for a remote method call. A MarshalException is also thrown if the receiver does not support the protocol version of the sender.

If a MarshalException occurs during a remote method call the call may or may not have reached the server. If the call did reach the server parameters may have been deserialized. A call may not be retransmitted after a MarshalException and reliably preserve "at most once" call semantics. @version 1.9 0210 12/0203/0001 @author Ann Wollrath @since JDK1.1

A MarshalledObject contains a byte stream with the serialized representation of an object given to its constructor. The get method returns a new copy of the original object as deserialized from the contained byte stream. The contained object is serialized and deserialized with the same serialization semantics used for marshaling and unmarshaling parameters and return values of RMI calls: When the serialized form is created:

• classes are annotated with a codebase URL from where the class can be loaded (if available) and
• any remote object in the MarshalledObject is represented by a serialized instance of its stub.

When copy of the object is retrieved (via the get method) if the class is not available locally it will be loaded from the appropriate location (specified the URL annotated with the class descriptor when the class was serialized.

MarshalledObject facilitates passing objects in RMI calls that are not automatically deserialized immediately by the remote peer. @version 1.28 0230 12/0203/0001 @author Ann Wollrath @author Peter Jones @since 1.2

A NoSuchObjectException is thrown if an attempt is made to invoke a method on an object that no longer exists in the remote virtual machine. If a NoSuchObjectException occurs attempting to invoke a method on a remote object the call may be retransmitted and still preserve RMI's "at most once" call semantics. A NoSuchObjectException is also thrown by the method java.rmi.server.RemoteObject.toStub and by the unexportObject methods of java.rmi.server.UnicastRemoteObject and java.rmi.activation.Activatable and @version 1.9 0210 12/0203/0001 @author Ann Wollrath @since JDK1.1 @see java.rmi.server.RemoteObject#toStub(Remote) @see java.rmi.server.UnicastRemoteObject#unexportObject(Remote boolean) @see java.rmi.activation.Activatable#unexportObject(Remote boolean)

A NotBoundException is thrown if an attempt is made to lookup or unbind in the registry a name that has no associated binding. @version 1.9 0210 12/0203/0001 @since JDK1.1 @author Ann Wollrath @author Roger Riggs @see java.rmi.Naming#lookup(String) @see java.rmi.Naming#unbind(String) @see java.rmi.registry.Registry#lookup(String) @see java.rmi.registry.Registry#unbind(String)

An RMISecurityException signals that a security exception has occurred during the execution of one of java.rmi.RMISecurityManager's methods. @version 1.11 0213 12/0203/0001 @author Roger Riggs @since JDK1.1 @deprecated noUse java.lang.SecurityException replacementinstead. Application code should never directly reference this class and RMISecurityManager no longer throws this subclass of java.lang.SecurityException.

RMISecurityManager provides an example security manager for use by RMI applications that use downloaded code. RMI's class loader will not download any classes from remote locations if no security manager has been set. RMISecurityManager does not apply to applets which run under the protection of their browser's security manager.

To use the RMISecurityManager in your application add the following statement to your code (it needs to be executed before RMI can download code from remote hosts so it most likely needs to appear in the main of your application):

 System.setSecurityManager(new RMISecurityManager()); 

@version 1.27 0228 12/0203/0001 @author Roger Riggs @author Peter Jones @since JDK1.1

The Remote interface serves to identify interfaces whose methods may be invoked from a non-local virtual machine. Any object that is a remote object must directly or indirectly implement this interface. Only those methods specified in a "remote interface" an interface that extends java.rmi.Remote are available remotely.

Implementation classes can implement any number of remote interfaces and can extend other remote implementation classes. RMI provides some convenience classes that remote object implementations can extend which facilitate remote object creation. These classes are java.rmi.server.UnicastRemoteObject and java.rmi.activation.Activatable.

For complete details on RMI see the RMI Specification which describes the RMI API and system. @version 1.1012 0212/0203/0001 @since JDK1.1 @author Ann Wollrath @see java.rmi.server.UnicastRemoteObject @see java.rmi.activation.Activatable

A RemoteException is the common superclass for a number of communication-related exceptions that may occur during the execution of a remote method call. Each method of a remote interface an interface that extends java.rmi.Remote must list RemoteException in its throws clause.

As of release 1.4 this exception has been retrofitted to conform to the general purpose exception-chaining mechanism. The "wrapped remote exception" that may be provided at construction time and accessed via the public #detail field is now known as the cause and may be accessed via the Throwable#getCause() method as well as the aforementioned "legacy field." @version 1.17 0221 12/0203/0001 @author Ann Wollrath @since JDK1.1

Constructs a RemoteException with no specified detail message. @since JDK1.1

Constructs a RemoteException with the specified detail message. @param s the detail message @since JDK1.1

Constructs a RemoteException with the specified detail message and nested exception. @param s the detail message @param ex the nested exception @since JDK1.1

Returns the detail message including the message from the nested exception if there is one. @sincereturn JDK1.1the detail message including nested exception message if any

Nested Exception to hold wrapped remote exception. @serial

This @sincefield predates the general-purpose exception chaining facility. The Throwable#getCause() JDK1method is now the preferred means of obtaining this information.1 @serial

A ServerError is thrown as a result of a remote method call if theinvocation when an executionError of the remoteis thrown while methodprocessing the invocation on the server machine throws aeither while unmarshalling java.lang.Error.the Thearguments ServerErrorexecuting contains a nested exception which isthe remote method itself or marshalling the java.langreturn value. A ServerError instance contains the original Error that occurred during remoteas method executionits cause. @version 1.911 0212/0203/0001 @author Ann Wollrath @since JDK1.1

A ServerException is thrown as a result of a remote method call ifinvocation when a RemoteException is thrown while processing the executioninvocation ofon the server either while unmarshalling the arguments executing the remote method onitself or marshalling the serverreturn machinevalue. throwsA aServerException instance contains the original RemoteException that occurred as its cause. @version 1.9 0212 12/0203/0001 @author Ann Wollrath @since JDK1.1

AFrom a server executing on JDK 1.1 a ServerRuntimeException is thrown as a result of a remote method callinvocation when a RuntimeException is thrown ifwhile processing the executioninvocation ofon the server either while unmarshalling the arguments executing the remote method onitself or marshalling the serverreturn machinevalue. throwsA aServerRuntimeException instance contains the original java.lang.RuntimeException that occurred as its cause.

A ServerRuntimeException is not thrown from servers executing inon the Java 2 SDKplatform v1.2 or later versions. @version 1.12 0215 12/0203/0001 @author Ann Wollrath @since JDK1.1 @deprecated no replacement

A StubNotFoundException is thrown if a valid stub class could not be found for a remote object when it is exported. A StubNotFoundException may also be thrown when an activatable object is registered via the java.rmi.activation.Activatable.register method. @version 1.12 0213 12/0203/0001 @author Roger Riggs @since JDK1.1 @see java.rmi.server.UnicastRemoteObject @see java.rmi.activation.Activatable

An UnexpectedException is thrown if the client of a remote method call receives as a result of the call a checked exception that is not among the checked exception types declared in the throws clause of the method in the remote interface. @version 1.9 0210 12/0203/0001 @author Roger Riggs @since JDK1.1

An UnknownHostException is thrown if a java.net.UnknownHostException occurs while creating a connection to the remote host for a remote method call. @version 1.10 0211 12/0203/0001 @since JDK1.1

An UnmarshalException can be thrown while unmarshalling the parameters or results of a remote method call if any of the following conditions occur:

• if an exception occurs while unmarshalling the call header
• if the protocol for the return value is invalid
• if a java.io.IOException occurs unmarshalling parameters (on the server side) or the return value (on the client side).
• if a java.lang.ClassNotFoundException occurs during unmarshalling parameters or return values
• if no skeleton can be loaded on the server-side; note that skeletons are required in the 1.1 stub protocol but not in the 1.2 stub protocol.
• if the method hash is invalid (i.e. missing method).
• if there is a failure to create a remote reference object for a remote object's stub when it is unmarshalled.

@version 1.9 0210 12/0203/0001 @author Ann Wollrath @since JDK1.1