java.rmi.server Documentation Differences

This file contains all the changes in documentation in the package java.rmi.server 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 ExportException is a RemoteException thrown if an attempt to export a remote object fails. A remote object is exported via the constructors and exportObject methods of java.rmi.server.UnicastRemoteObject and java.rmi.activation.Activatable. @version 1.7 099 02/2102/9800 @author Ann Wollrath @since JDK1.1 @see java.rmi.server.UnicastRemoteObject @see java.rmi.activation.Activatable

LoaderHandler is an interface used internally by the RMI runtime in previous implementation versions. It should never be accessed by application code. @version 1.10 0713 02/1202/9800 @author Ann Wollrath @since JDK1.1 @deprecated no replacement

package of system LoaderHandler implementation.

LogStream provides a mechanism for logging errors that are of possible interest to those monitoring a system. @version 1.11 0915 02/2102/9800 @author Ann Wollrath (lots of code stolen from Ken Arnold) @since JDK1.1 @deprecated no replacement

Return the current default stream for new logs. @return default log stream @since JDK1.1 @deprecated no replacement

Return the current stream to which output from this log is sent. @return output stream for this log @since JDK1.1 @deprecated no replacement

Return the LogStream identified by the given name. If a log corresponding to "name" does not exist a log using the default stream is created. @param name name identifying the desired LogStream @return log associated with given name @since JDK1.1 @deprecated no replacement

Convert a string name of a logging level to its internal integer representation. @param s name of logging level (e.g. 'SILENT' 'BRIEF' 'VERBOSE') @return corresponding integer log level @since JDK1.1 @deprecated no replacement

Set the default stream for new logs. @param newDefault new default log stream @since JDK1.1 @deprecated no replacement

Set the stream to which output from this log is sent. @param out new output stream for this log @since JDK1.1 @deprecated no replacement

Return log name as string representation. @return log name @since JDK1.1 @deprecated no replacement

log level constant (brief logging).

log level constant (no logging).

log level constant (verbose logging).

An ObjID is used to identify remote objects uniquely in a VM over time. Each identifier contains an object number and an address space identifier that is unique with respect to a specific host. An object identifier is assigned to a remote object when it is exported. If the property java.rmi.server.randomIDs is true then the object number component (64 bits) of an ObjID created with the no argument constructor will contain a cryptographically strong random number. @version 1.16 0721 02/1217/9800 @author Ann Wollrath @since JDK1.1

Constructs an object id whose contents is read from the specified input stream. @param in input stream to read object ID from @return object ID instance read from stream @throws IOException if an I/O error occurred @since JDK1.1

Marshals object id to output stream. @param out output stream to write object ID to @throws IOException if an I/O error occurred @since JDK1.1

well-known id for the activator.

well-known id for the distributed garbage collector.

well-known id for the registry.

An Operation contains a description of a Java method. Operation objects were used in JDK1.1 version stubs and skeletons. The Operation class is not needed for JDK11.2 style stubs (stubs generated with rmic -v1.2); hence this class is deprecated. @version 1.813 0902/2102/9800 @since JDK1.1 @deprecated no replacement

Creates a new Operation object. @param op method name @deprecated no replacement @since JDK1.1

Returns the name of the method. @return method name @deprecated no replacement @since JDK1.1

RMIClassLoader provides static methods for loading classes from a network location (one or more URLs) and obtaining the location from which an existing class can be loaded. These methods are used by the RMI runtime when marshalling and unmarshalling classes of parameters and return values. @version 1.16 0722 02/1202/9800 @author Ann Wollrath @author Peter Jones @since JDK1.1

Returns the class annotation (representing the location for a class) that RMI will use to annotate the call stream when marshalling objects of the given class. @param cl the class to obtain the annotation for @return a string to be used to annotate the class when marshalled @since JDK11.2

ReturnReturns the security context of the given class loader. @param loader a class loader from which to get the security context @return the security context @since JDK1.1 @deprecated no replacement. As of JDK1the Java 2 platform v1.2 RMI no longer uses this method to obtain a classloaderclass loader's security context. @see java.lang.SecurityManager#getSecurityContext()

LoadLoads a class from the codebase URL path specified by the java.rmi.server.codebase property. @param name the name of the class to load @return the Class object representing the loaded class @exception MalformedURLException if the system property java.rmi.server.codebase contains an invalid URL @exception ClassNotFoundException if a definition for the class could not be found at the codebase location @since JDK1.1 @deprecated replaced by loadClass(String String) method @see #loadClass(String String)

LoadLoads a class from a codebase URL path. If the given codebase is null then the Class object returned is equivalent to the Class object returned by RMIClassLoader.loadClass(name). @param codebase the list of space-separated URLs to load the class from @param name the name of the class to load @return the Class object representing the loaded class @exception MalformedURLException if the codebase paramater contains an invalid non-null URL @exception ClassNotFoundException if a definition for the class could not be found at the specified location @since JDK11.2

LoadLoads a class from a codebase URL. If the given codebase is null then the Class object returned is equivalent to the Class object returned by RMIClassLoader.loadClass(name). @param codebase the URL to load the class from @param name the name of the class to load @return the Class object representing the loaded class @exception MalformedURLException if the codebase paramater contains an invalid non-null URL @exception ClassNotFoundException if a definition for the class could not be found at the specified URL @since JDK1.1

An RMIClientSocketFactory instance is used by the RMI runtime in order to obtain client sockets for RMI calls. A remote object can be associated with an RMIClientSocketFactory when it is created/exported via the constructors or exportObject methods of java.rmi.server.UnicastRemoteObject and java.rmi.activation.Activatable .

An RMIClientSocketFactory instance associated with a remote object will be downloaded to clients when the remote object's reference is transmitted in an RMI call. This RMIClientSocketFactory will be used to create connections to the remote object for remote method calls.

An RMIClientSocketFactory instance can also be associated with a remote object registry so that clients can use custom socket communication with a remote object registry. @version 1.3 077 02/1202/9800 @author Ann Wollrath @author Peter Jones @since JDK11.2 @see java.rmi.server.UnicastRemoteObject @see java.rmi.activation.Activatable @see java.rmi.registry.LocateRegistry

Create a client socket connected to the specified host and port. @param host the host name @param port the port number @return a socket connected to the specified host and port. @exception IOException if an I/O error occurs during socket creation @since JDK11.2

An RMIFailureHandler can be registered via the RMISocketFactory.setFailureHandler call. The failure method of the handler is invoked when the RMI runtime is unable to create a ServerSocket to listen for incoming calls. The failure method returns a boolean indicating whether the runtime should attempt to re-create the ServerSocket. @author Ann Wollrath @version @(#)RMIFailureHandler.java 1.6 988 00/0702/0802 @since JDK1.1

An RMIServerSocketFactory instance is used by the RMI runtime in order to obtain server sockets for RMI calls. A remote object can be associated with an RMIServerSocketFactory when it is created/exported via the constructors or exportObject methods of java.rmi.server.UnicastRemoteObject and java.rmi.activation.Activatable .

An RMIServerSocketFactory instance associated with a remote object is used to obtain the ServerSocket used to accept incoming calls from clients.

An RMIServerSocketFactory instance can also be associated with a remote object registry so that clients can use custom socket communication with a remote object registry. @version 1.3 077 02/1202/9800 @author Ann Wollrath @author Peter Jones @since JDK11.2 @see java.rmi.server.UnicastRemoteObject @see java.rmi.activation.Activatable @see java.rmi.registry.LocateRegistry

Create a server socket on the specified port (port 0 indicates an anonymous port). @param port the port number @return the server socket on the specified port @exception IOException if an I/O error occurs during server socket creation @since JDK11.2

An RMISocketFactory instance is used by the RMI runtime in order to obtain client and server sockets for RMI calls. An application may use the setSocketFactory method to request that the RMI runtime use its socket factory instance instead of the default implementation.

The default socket factory implementation used goes through a three-tiered approach to creating client sockets. First a direct socket connection to the remote VM is attempted. If that fails (due to a firewall) the runtime uses HTTP with the explicit port number of the server. If the firewall does not allow this type of communication then HTTP to a cgi-bin script on the server is used to POST the RMI call.

@version 1.14 0916 02/2402/9800 @author Ann Wollrath @author Peter Jones @since JDK1.1

RemoteCall is an abstraction used solely by the RMI runtime (in conjunction with stubs and skeletons of remote objects) to carry out a call to a remote object. The RemoteCall interface is deprecated in JDK1.the Java 2 platform since it is only used by deprecated methods of java.rmi.server.RemoteRef. @version 1.10 0915 02/2102/9800 @since JDK1.1 @author Ann Wollrath @author Roger Riggs @see java.rmi.server.RemoteRef @deprecated no replacement.

Get the InputStream that the stub/skeleton should get results/arguments from. @return input stream for reading arguments/results @exception java.io.IOException if an I/O error occurs. @since JDK1.1 @deprecated no replacement

Return the output stream the stub/skeleton should put arguments/results into. @return output stream for arguments/results @exception java.io.IOException if an I/O error occurs. @since JDK1.1 @deprecated no replacement

Returns an output stream (may put out header information relating to the success of the call). Should only succeed once per remote call. @param success If true indicates normal return else indicates exceptional return. @return output stream for writing call result @exception java.io.IOException if an I/O error occurs. @exception java.io.StreamCorruptedException If already been called. @since JDK1.1 @deprecated no replacement

The RemoteObject class implements the java.lang.Object behavior for remote objects. RemoteObject provides the remote semantics of Object by implementing methods for hashCode equals and toString. @version 1.17 0822 02/1002/9800 @author Ann Wollrath @since JDK1.1

Creates a remote object initialized with the specified remote reference. @param newref remote reference @since JDK1.1

Returns the remote reference for the remote object. @return remote reference for the remote object @since JDK11.2

Returns the stub for the remote object obj passed as a parameter. This operation is only valid after the object has been exported. @param obj the remote object whose stub is neede @return the stub for the remote object obj. @exception NoSuchObjectException if the stub for the remote object could not be found. @since JDK11.2

the objectsobject's remote reference.

RemoteRef represents the handle for a remote object. A RemoteStub uses a remote reference to carry out a remote method invocation to a remote object. @version 1.12 0718 02/0802/9800 @author Ann Wollrath @since JDK1.1 @see java.rmi.server.RemoteStub

Allows the remote reference to clean up (or reuse) the connection. Done should only be called if the invoke returns successfully (non-exceptionally) to the stub. @since JDK1.1 @deprecated JDK11.2 style stubs no longer use this method. Instead of using a sequence of method calls to the remote reference (newCall invoke and done) a stub uses a single method invoke(Remote Method Object[] int) on the remote reference to carry out parameter marshalling remote method executing and unmarshalling of the return value.

JDK11.2 stubs are generated using rmic -v1.2. By default rmic generates stubs compatible with JDK1.1 and JDK1.the Java 2 SDK. The compatible stubs can also be generated using rmic -vcompat. @param call object representing remote call @throws RemoteException if remote error occurs during call cleanup @see #invoke(Remote java.lang.reflect.Method Object[] long)

Invoke a method. This form of delegating method invocation to the reference allows the reference to take care of setting up the connection to the remote host marshaling some representation for the method and parameters then communicating the method invocation to the remote host. This method either returns the result of a method invocation on the remote object which resides on the remote host or throws a RemoteException if the call failed or an application-level exception if the remote invocation throws an exception. @param obj the object that contains the RemoteRef (e.g. the RemoteStub for the object. @param method the method to be invoked @param params the parameter list @param opnum a hash that may be used to represent the method @return result of remote method invocation @exception Exception if any exception occurs during remote method invocation @since JDK11.2

Executes the remote call. Invoke will raise any "user" exceptions which should pass through and not be caught by the stub. If any exception is raised during the remote invocation invoke should take care of cleaning up the connection before raising the "user" or remote exception. @since JDK1.1 @deprecated JDK11.2 style stubs no longer use this method. Instead of using a sequence of method calls to the remote reference (newCall invoke and done) a stub uses a single method invoke(Remote Method Object[] int) on the remote reference to carry out parameter marshalling remote method executing and unmarshalling of the return value.

JDK11.2 stubs are generated using rmic -v1.2. By default rmic generates stubs compatible with JDK1.1 and JDK1.the Java 2 SDK. The compatible stubs can also be generated using rmic -vcompat. @param call object representing remote call @throws Exception if any exception occurs during remote method @see #invoke(Remote java.lang.reflect.Method Object[] long)

Creates an appropriate call object for a new remote method invocation on this object. Passing operation array and index allows the stubs generator to assign the operation indexes and interpret them. The remote reference may need the operation to encode in the call. @since JDK1.1 @deprecated JDK11.2 style stubs no longer use this method. Instead of using a sequence of method calls on the stub's the remote reference (newCall invoke and done) a stub uses a single method invoke(Remote Method Object[] int) on the remote reference to carry out parameter marshalling remote method executing and unmarshalling of the return value.

JDK11.2 stubs are generated using rmic -v1.2. By default rmic generates stubs compatible with JDK1.1 and JDK1.the Java 2 SDK. The compatible stubs can also be generated using rmic -vcompat. @param obj remote stub through which to make call @param op array of stub operations @param opnum operation number @param hash stub/skeleton interface hash @return call object representing remote call @throws RemoteException if failed to initiate new remote call @see #invoke(Remote java.lang.reflect.Method Object[] long)

Returns a hashcode for a remote object. Two remote object stubs that refer to the same remote object will have the same hash code (in order to support remote objects as keys in hash tables). @return remote object hashcode @see java.util.Hashtable @since JDK1.1

Returns a String that represents the reference of this remote object. @return string representing remote object reference @since JDK1.1

indicate compatibility with JDK 1.1.x version of class.

The RemoteServer class is the common superclass to server implementations and provides the framework to support a wide range of remote reference semantics. Specifically the functions needed to create and export remote objects (i.e. to make them remotely available) are provided abstractly by RemoteServer and concretely by its subclass(es). @version 1.18 0722 02/0802/9800 @author Ann Wollrath @since JDK1.1

Return the hostname of the current client. When called from a thread actively handling a remote method invocation the hostname of the client is returned. @exception ServerNotActiveException If called outside of servicing a remote method invocation. @return client hostname @since JDK1.1

The RemoteStub class is the common superclass to client stubs and provides the framework to support a wide range of remote reference semantics. Stub objects are surrogates that support exactly the same set of remote interfaces defined by the actual implementation of the remote object. @version 1.15 0717 02/0802/9800 @author Ann Wollrath @since JDK1.1

A ServerCloneException is thrown if a remote exception occurs during the cloning of a UnicastRemoteObject. @version 1.10 0715 02/1202/9800 @author Ann Wollrath @since JDK1.1 @see java.rmi.server.UnicastRemoteObject#clone()

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 streamwriter pspw. @param pspw the print streamwriter @since JDK11.2

Nested exception for ServerCloneException. @serial @since JDK1.1

An ServerNotActiveException is an Exception thrown during a call to RemoteServer.getClientHost if the getClientHost method is called outside of servicing a remote method call. @version 1.8 0910 02/2102/9800 @author Roger Riggs @since JDK1.1 @see java.rmi.server.RemoteServer#getClientHost()

A ServerRef represents the server-side handle for a remote object implementation. @version 1.10 0913 02/2102/9800 @author Ann Wollrath @since JDK1.1

indicate compatibility with JDK 1.1.x version of class.

The Skeleton interface is used solely by the RMI implementation.

Every version 1.1 (and version 1.1 compatible skeletons generated in 1.2 using rmic -vcompat) skeleton class generated by the rmic stub compiler implements this interface. A skeleton for a remote object is a server-side entity that dispatches calls to the actual remote object implementation. @version 1.9 0915 02/2102/9800 @author Ann Wollrath @since JDK1.1 @deprecated no replacement. Skeletons are no longer required for remote method calls in JDK1the Java 2 platform v1.2 and greater.

Unmarshals arguments calls the actual remote object implementation and marshals the return value or any exception. @param obj remote implementation to dispatch call to @param theCall object representing remote call @param opnum operation number @param hash stub/skeleton interface hash @exception java.lang.Exception if a general exception occurs. @since JDK1.1 @deprecated no replacement

Returns the operations supported by the skeleton. @return operations supported by skeleton @since JDK1.1 @deprecated no replacement

This exception is thrown when a call is received that does not match the available skeleton. It indicates either that the remote method names or signatures in this interface have changed or that the stub class used to make the call and the skeleton receiving the call were not generated by the same version of the stub compiler (rmic). @version 1.7 0911 02/2102/9800 @author Roger Riggs @since JDK1.1 @deprecated no replacement. Skeletons are no longer required for remote method calls in JDK1the Java 2 platform v1.2 and greater.

A SkeletonNotFoundException is thrown if the Skeleton corresponding to the remote object being exported is not found. Skeletons are not required in JDK1.the Java 2 platform so this exception is never thrown if stubs are generated with rmic -v1.2. To generate stubs and skeletons compatible with JDK1.1 and JDK1.the Java 2 SDK use rmic -vcompat which is the default in JDK1.the Java 2 SDK. @version 1.7 0911 02/2102/9800 @since JDK1.1 @deprecated no replacement. Skeletons are no longer required for remote method calls in JDK1the Java 2 platform v1.2 and greater.

A SocketSecurityException is thrown during remote object export if the code exporting the remote object (either by construction or by explicit call to the exportObject method of UnicastRemoteObject or java.rmi.activation.Activatable) does not have permission to create a java.net.ServerSocket on the port number specified during remote object export. @version 1.7 099 02/2102/9800 @author Ann Wollrath @since JDK1.1 @see java.rmi.server.UnicastRemoteObject @see java.rmi.activation.Activatable

Abstraction for creating identifiers that are unique with respect to the the host on which it is generated. @version 1.10 0713 02/1202/9800 @author Ann Wollrath @since JDK1.1

Creates a "well-known" ID. There are 2^16 -1 such possible well-known ids. An id generated via this constructor will not clash with any id generated via the default UID constructor which will generates a genuinely unique identifier with respect to this host. @param num well known ID number @since JDK1.1

The UnicastRemoteObject class defines a non-replicated remote object whose references are valid only while the server process is alive. The UnicastRemoteObject class provides support for point-to-point active object references (invocations parameters and results) using TCP streams.

Objects that require remote behavior should extend RemoteObject typically via UnicastRemoteObject. If UnicastRemoteObject is not extended the implementation class must then assume the responsibility for the correct semantics of the hashCode equals and toString methods inherited from the Object class so that they behave appropriately for remote objects. @version 1.21 0726 02/0802/9800 @author Ann Wollrath @author Peter Jones @since JDK1.1 @see RemoteServer @see RemoteObject

Create and export a new UnicastRemoteObject object using an anonymous port. @throws RemoteException if failed to export object @since JDK1.1

Create and export a new UnicastRemoteObject object using the particular supplied port. @param port the port number on which the remote object receives calls (if port is zero an anonymous port is chosen) @throws RemoteException if failed to export object @since JDK11.2

Create and export a new UnicastRemoteObject object using the particular supplied port and socket factories. @param port the port number on which the remote object receives calls (if port is zero an anonymous port is chosen) @param csf the client-side socket factory for making calls to the remote object @param ssf the server-side socket factory for receiving remote calls @throws RemoteException if failed to export object @since JDK11.2

Export the remote object to make it available to receive incoming calls using an anonymous port. @param obj the remote object to be exported @return remote object stub @exception RemoteException if export fails @since JDK1.1

Export the remote object to make it available to receive incoming calls using the particular supplied port. @param obj the remote object to be exported @param port the port to export the object on @return remote object stub @exception RemoteException if export fails @since JDK11.2

Export the remote object to make it available to receive incoming calls using a transport specified by the given socket factory. @param obj the remote object to be exported @param port the port to export the object on @param csf the client-side socket factory for making calls to the remote object @param ssf the server-side socket factory for receiving remote calls @return remote object stub @exception RemoteException if export fails @since JDK11.2

Remove the remote object obj from the RMI runtime. If successful the object can no longer accept incoming RMI calls. If the force parameter is true the object is forcibly unexported even if there are pending calls to the remote object or the remote object still has calls in progress. If the force parameter is false the object is only unexported if there are no pending or in progress calls to the object. @param obj the remote object to be unexported @param force if true unexports the object even if there are pending or in-progress calls; if false only unexports the object if there are no pending or in-progress calls @return true if operation is successful false otherwise @exception NoSuchObjectException if the remote object is not currently exported @since JDK11.2

A remote object implementation should implement the Unreferenced interface to receive notification when there are no more clients that reference that remote object. @version 1.7 099 02/2102/9800 @author Ann Wollrath @author Roger Riggs @since JDK1.1