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.7 099 02/2102/9800 @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.7 099 02/2102/9800 @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.8 0910 02/2102/9800 @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.7 099 02/2102/9800 @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.7 099 02/2102/9800 @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.24 0728 02/0802/9800 @author Ann Wollrath @author Peter Jones @since JDK11.2

Creates a new MarshalledObject that contains the serialized representation of the current state of the supplied object. The object is serialized with the semantics used for marshaling parameters for RMI calls. @param obj the object to be serialized (must be serializable) @exception IOException if an IOException occurs; an IOException may occur if obj is not serializable. @since JDK11.2

Compares this MarshalledObject to another object. Returns true if and only if the argument refers to a MarshalledObject that contains exactly the same serialized representation of an object as this one does. The comparison ignores any class codebase annotation meaning that two objects are equivalent if they have the same serialized representation except for the codebase of each class in the serialized representation. @param obj the object to compare with this MarshalledObject @return true if the argument contains an equaivalent serialized object; false otherwise @since JDK11.2

Returns a new copy of the contained marshalledobject. The internal representation is deserialized with the semantics used for unmarshaling paramters for RMI calls. @return a copy of the contained object @exception IOException if an IOException occurs while deserializing the object from its internal representation. @exception ClassNotFoundException if a ClassNotFoundException occurs while deserializing the object from its internal representation. could not be found @since JDK11.2

The Naming class provides methods for storing and obtaining references to remote objects in the remote object registry. The Naming class's methods take as one of their arguments a name that is a URL formatted java.lang.String of the form:

 //host:port/name 

where host is the host (remote or local) where the registry is located port is the port number on which the registry accepts calls and where name is a simple string uninterpreted by the registry. Both host and port are optional. If host is omitted the host defaults to the local host. If port is omitted then the port defaults to 1099 the "well-known" port that RMI's registry rmiregistry uses.

Binding a name for a remote object is associating or registering a name for a remote object that can be used at a later time to look up that remote object. A remote object can be associated with a name using the Naming class's bind or rebind methods.

Once a remote object is registered (bound) with the RMI registry on the local host callers on a remote (or local) host can lookup the remote object by name obtain its reference and then invoke remote methods on the object. A registry may be shared by all servers running on a host or an individual server process may create and use its own registry if desired (see java.rmi.registry.LocateRegistry.createRegistry method for details). @version 1.10 0713 09/1205/9899 @author Ann Wollrath @author Roger Riggs @since JDK1.1 @see java.rmi.registry.Registry @see java.rmi.registry.LocateRegistry @see java.rmi.registry.LocateRegistry#createRegistry(int)

Returns a reference a stub for the remote object associated with the specified name. @param name a URL-formatted name for the remote object @return a reference for a remote object @exception NotBoundException if name is not currently bound @exception RemoteException if registry could not be contacted @exception AccessException if this operation is not permitted (@exception MalformedURLException if originating from athe name is non-localnot host foran appropriately example)formatted URL @since JDK1.1

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.7 099 02/2102/9800 @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.7 099 02/2102/9800 @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.8 0911 02/2102/9800 @author Roger Riggs @since JDK1.1 @deprecated no replacement. RMISecurityManager no longer throws this subclass of java.lang.SecurityException.

Construct an RMISecurityException with a detail message. @param sname the detail message @since JDK1.1 @deprecated no replacement

Construct an RMISecurityException with a detail message. @param sname the detail message @param arg ignored @since JDK1.1 @deprecated no replacement

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.25 0427 02/2202/9900 @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.710 0902/2102/9800 @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. @version 1.12 0717 02/1202/9800 @author Ann Wollrath @since JDK1.1

Prints the composite message to System.err. @since JDK11.2

Prints the composite message and the embedded stack trace to the specified stream ps. @param ps the print stream @since JDK11.2

Prints the composite message and the embedded stack trace to the specified print writer pw. @param pw the print writer @since JDK11.2

A ServerError is thrown as a result of a remote method call if the execution of the remote method on the server machine throws a java.lang.Error. The ServerError contains a nested exception which is the java.lang.Error that occurred during remote method execution. @version 1.7 099 02/2102/9800 @author Ann Wollrath @since JDK1.1

A ServerException is thrown as a result of a remote method call if the execution of the remote method on the server machine throws a RemoteException. @version 1.7 099 02/2102/9800 @author Ann Wollrath @since JDK1.1

A ServerRuntimeException is thrown as a result of a remote method call if the execution of the remote method on the server machine throws a java.lang.RuntimeException. A ServerRuntimeException is not thrown from servers executing in JDK1the Java 2 SDK v1.2 or later versions. @version 1.8 0912 02/2102/9800 @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.9 0412 02/2202/9900 @author Roger Riggs @since JDK1.1 @see java.rmi.server.UnicastRemoteObject @see java.rmi.activation.Activatable

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

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.7 099 02/2102/9800 @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.8 0910 02/2102/9800 @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.7 099 02/2102/9800 @author Ann Wollrath @since JDK1.1