The java.rmi.server Package (Java Enterprise in a Nutshell)

The java.rmi.server package contains the classes that develop server implementations of remote objects. Figure 17-1 shows the class hierarchy for this package.

The RemoteServer class in this package acts as the base class for all RMI server objects. A single subclass of RemoteServer, UnicastRemoteObject, is provided in this package. It implements a nonpersistent, point-to-point object communication scheme. Other subclasses of RemoteServer could be written to implement multicast object communication, replicated objects, etc.

This package also contains several Exception subclasses relevant to the server implementation of a remote object.

Figure 17-1. The java.rmi.server package

ExportException

Java 1.1

java.rmi.server

serializable checked PJ1.1(opt)

This RemoteException is thrown if an attempt is made to export a remote object on a port already in use.

public class ExportException extends RemoteException {
//	Public Constructors
	public ExportException (String s);
	public ExportException (String s, Exception ex);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->ExportException

Subclasses: SocketSecurityException

LoaderHandler

Java 1.1; Deprecated in Java 1.2

java.rmi.server

PJ1.1(opt)

This defines the interface to the internal handler used by the RMIClassLoader to load classes over the network.

public abstract interface LoaderHandler {
//	Public Constants
	public static final String packagePrefix ;	="sun.rmi.server"
//	Deprecated Public Methods
#	public abstract Object getSecurityContext (ClassLoader loader);
#	public abstract Class loadClass (String name) throws java.net.MalformedURLException, ClassNotFoundException;
#	public abstract Class loadClass (java.net.URL codebase, String name) throws java.net.MalformedURLException, ClassNotFoundException;
}

LogStream

Java 1.1; Deprecated in Java 1.2

java.rmi.server

PJ1.1(opt)

This class provides the server with an output stream to an error log. A LogStream cannot be created directly by an application. Instead, a handle on a LogStream is obtained by calling the static log() method with the name of the desired log. If the named log doesn't exist, the default log is returned. The default PrintStream creates new LogStream objects can be retrieved through the getDefaultStream() method and set using the setDefaultStream() method.

public class LogStream extends PrintStream {
//	No Constructor
//	Public Constants
	public static final int BRIEF ;	=10
	public static final int SILENT ;	=0
	public static final int VERBOSE ;	=20
//	Deprecated Public Methods
#	public static PrintStream getDefaultStream ();	synchronized
#	public java.io.OutputStream getOutputStream ();	synchronized
#	public static LogStream log (String name);
#	public static int parseLevel (String s);
#	public static void setDefaultStream (PrintStream newDefault);	synchronized
#	public void setOutputStream (java.io.OutputStream out);	synchronized
#	public String toString ();	Overrides:Object
#	public void write (int b);	Overrides:PrintStream
#	public void write (byte[ ] b, int off, int len);	Overrides:PrintStream
}

Hierarchy: Object-->java.io.OutputStream-->FilterOutputStream-->PrintStream-->LogStream

Returned By: LogStream.log()

ObjID

Java 1.1

java.rmi.server

serializable PJ1.1(opt)

An ObjID is used on an object server to uniquely identify exported remote objects. It is used in an RMI server during distributed garbage collection.

The equals() method is overridden from Object to return true only if the objects identified by the two ObjID values are equal. The ObjID class also has read() and write() methods that marshal and unmarshal an ObjID from I/O streams.

public final class ObjID implements Serializable {
//	Public Constructors
	public ObjID ();
	public ObjID (int num);
//	Public Constants
1.2	public static final int ACTIVATOR_ID ;	=1
	public static final int DGC_ID ;	=2
	public static final int REGISTRY_ID ;	=0
//	Public Class Methods
	public static ObjID read (ObjectInput in) throws IOException;
//	Public Instance Methods
	public void write (ObjectOutput out) throws IOException;
//	Public methods overriding Object
	public boolean equals (Object obj);
	public int hashCode ();
	public String toString ();
}

Hierarchy: Object-->ObjID(Serializable)

Passed To: java.rmi.dgc.DGC.{clean(), dirty()}

Returned By: ObjID.read()

Operation

Java 1.1; Deprecated in Java 1.2

java.rmi.server

PJ1.1(opt)

An Operation contains a description of a method on a remote object. This class is used only in the stub classes generated by the rmic compiler. The Java 2 rmic compiler no longer uses the Operation class, so it is deprecated, but still present in the Java 2 SDK 1.2 to support RMI stubs generated by the JDK 1.1 rmic compiler.

public class Operation {
//	Public Constructors
#	public Operation (String op);
//	Deprecated Public Methods
#	public String getOperation ();
#	public String toString ();	Overrides:Object
}

Passed To: RemoteRef.newCall()

Returned By: Skeleton.getOperations()

RemoteCall

Java 1.1; Deprecated in Java 1.2

java.rmi.server

PJ1.1(opt)

RemoteCall is the interface used by stubs and skeletons to perform remote method calls. The getInputStream() and getOutputStream() methods return streams that can marshal arguments, or return values and then unmarshal them on the other end of the method call.

public abstract interface RemoteCall {
//	Deprecated Public Methods
#	public abstract void done () throws IOException;
#	public abstract void executeCall () throws Exception;
#	public abstract ObjectInput getInputStream () throws IOException;
#	public abstract ObjectOutput getOutputStream () throws IOException;
#	public abstract ObjectOutput getResultStream (boolean success) throws IOException, StreamCorruptedException;
#	public abstract void releaseInputStream () throws IOException;
#	public abstract void releaseOutputStream () throws IOException;
}

Passed To: RemoteRef.{done(), invoke()}, Skeleton.dispatch()

Returned By: RemoteRef.newCall()

RemoteObject

Java 1.1

java.rmi.server

serializable remote PJ1.1(opt)

The RemoteObject class reimplements key Object methods for remote objects. It also maintains a RemoteRef object, which is a handle to the actual remote object. The equals() implementation returns true only if the two referenced remote objects are equal. The hashCode() method is implemented so that every remote stub that refers to the same remote object has the same hash code.

public abstract class RemoteObject implements Remote, Serializable {
//	Protected Constructors
	protected RemoteObject ();
	protected RemoteObject (RemoteRef newref);
//	Public Class Methods
1.2	public static Remote toStub (Remote obj) throws NoSuchObjectException;
//	Public Instance Methods
1.2	public RemoteRef getRef ();
//	Public methods overriding Object
	public boolean equals (Object obj);
	public int hashCode ();
	public String toString ();
//	Protected Instance Fields
	protected transient RemoteRef ref ;
}

Hierarchy: Object-->RemoteObject(Remote,Serializable)

Subclasses: RemoteServer, RemoteStub

Passed To: RemoteRef.newCall()

RemoteRef

Java 1.1

java.rmi.server

serializable PJ1.1(opt)

A RemoteRef is a handle on the object that implements a remote object reference. Each RemoteObject contains a RemoteRef that acts as its interface to the actual remote object it represents. Normally, you don't need to interact directly with RemoteRef objects from your application code. Rather, application code interacts with RemoteObject objects, which use their internal RemoteRef objects to perform remote method invocations.

The newCall() method creates a call object for invoking a remote method on the referenced object. The invoke() method actually executes a remote-method invocation. If a remote method returns successfully, the done() method is called to clean up the connection to the remote object.

The remoteEquals(), remoteHashCode(), and remoteToString() methods on RemoteRef are used by RemoteObject to implement the remote versions of the equals(), hashCode(), and toString() methods.

public abstract interface RemoteRef extends Externalizable {
//	Public Constants
	public static final String packagePrefix ;	="sun.rmi.server"
1.2	public static final long serialVersionUID ;	=3632638527362204081
//	Public Instance Methods
	public abstract String getRefClass (ObjectOutput out);
1.2	public abstract Object invoke (Remote obj, java.lang.reflect.Method method, Object[ ] params, long opnum) throws Exception;
	public abstract boolean remoteEquals (RemoteRef obj);
	public abstract int remoteHashCode ();
	public abstract String remoteToString ();
//	Deprecated Public Methods
#	public abstract void done (RemoteCall call) throws RemoteException;
#	public abstract void invoke (RemoteCall call) throws Exception;
#	public abstract RemoteCall newCall (RemoteObject obj, Operation[ ] op, int opnum, long hash) throws RemoteException;
}

Hierarchy: (RemoteRef(Externalizable(Serializable)))

Implementations: ServerRef

Passed To: java.rmi.activation.ActivationGroup_Stub.ActivationGroup_Stub(), RemoteObject.RemoteObject(), RemoteRef.remoteEquals(), RemoteServer.RemoteServer(), RemoteStub.{RemoteStub(), setRef()}

Returned By: RemoteObject.getRef()

Type Of: RemoteObject.ref

RemoteServer

Java 1.1

java.rmi.server

serializable remote PJ1.1(opt)

This class acts as an abstract base class for all remote object server implementations. The intent is for subclasses to implement the semantics of the remote object (e.g., multicast remote objects, replicated objects). As of JDK 1.1 and later, the only concrete sub-class provided is UnicastRemoteObject, which implements a nonreplicated remote object. The java.activation.Activatable class is a new abstract subclass in Java 2 that represents a server object that is persistent and activatable.

The getClientHost() method returns the name of the host for the client being served in the current thread. The getLog() and setLog() methods access the call log for a RemoteServer.

public abstract class RemoteServer extends RemoteObject {
//	Protected Constructors
	protected RemoteServer ();
	protected RemoteServer (RemoteRef ref);
//	Public Class Methods
	public static String getClientHost () throws ServerNotActiveException;
	public static PrintStream getLog ();
	public static void setLog (java.io.OutputStream out);
}

Hierarchy: Object-->RemoteObject(Remote,Serializable)-->RemoteServer

Subclasses: java.rmi.activation.Activatable, UnicastRemoteObject

RemoteStub

Java 1.1

java.rmi.server

serializable remote PJ1.1(opt)

All client stub classes generated by the rmic compiler are derived from this abstract class. A client receives a RemoteStub when it successfully looks up a remote object through the RMI registry. A client stub serves as a client interface to the remote object it references, converting method calls on its interface to remote method invocations on the remote object implementation.

public abstract class RemoteStub extends RemoteObject {
//	Protected Constructors
	protected RemoteStub ();
	protected RemoteStub (RemoteRef ref);
//	Deprecated Protected Methods
#	protected static void setRef (RemoteStub stub, RemoteRef ref);
}

Hierarchy: Object-->RemoteObject(Remote,Serializable)-->RemoteStub

Subclasses: java.rmi.activation.ActivationGroup_Stub

Passed To: RemoteStub.setRef()

Returned By: ServerRef.exportObject(), UnicastRemoteObject.exportObject()

RMIClassLoader

Java 1.1

java.rmi.server

PJ1.1(opt)

This class loads classes over the network using URLs. The class has two loadClass() methods, one for loading a class from a given (absolute) URL and another for loading a class from a given (relative) URL, starting at a particular codebase.

public class RMIClassLoader {
//	No Constructor
//	Public Class Methods
1.2	public static String getClassAnnotation (Class cl);
	public static Class loadClass (java.net.URL codebase, String name) throws java.net.MalformedURLException, ClassNotFoundException;
1.2	public static Class loadClass (String codebase, String name) throws java.net.MalformedURLException, ClassNotFoundException;
//	Deprecated Public Methods
#	public static Object getSecurityContext (ClassLoader loader);
#	public static Class loadClass (String name) throws java.net.MalformedURLException, ClassNotFoundException;
}

RMIClientSocketFactory

Java 1.2

java.rmi.server

This interface represents a source for client sockets that is used by the RMI internals to make client connections during RMI calls. It is possible to provide a custom socket factory to be used with a particular remote object, by using the appropriate constructors on the UnicastRemoteObject or Activatable classes, or, with a particular registry, by using the appropriate LocateRegistry.createRegistry() method. This can be useful in situations where a firewall lies between the client and the server object or remote registry, and specialized sockets are needed to negotiate the firewall protocol.

The RMIClientSocketFactory associated with a remote object is used by any remote stub references to establish connections with the server object.

public abstract interface RMIClientSocketFactory {
//	Public Instance Methods
	public abstract java.net.Socket createSocket (String host, int port) throws IOException;
}

Implementations: RMISocketFactory

Passed To: java.rmi.activation.Activatable.{Activatable(), exportObject()}, java.rmi.registry.LocateRegistry.{createRegistry(), getRegistry()}, UnicastRemoteObject.{exportObject(), UnicastRemoteObject()}

RMIFailureHandler

Java 1.1

java.rmi.server

PJ1.1(opt)

The failure() method on the current RMIFailureHandler is called when the RMI communication system fails to create a Socket or ServerSocket. The current handler is set using the setFailureHandler() method on RMISocketFactory. The failure() method returns a boolean value that indicates whether the RMI system should retry the socket connection.

public abstract interface RMIFailureHandler {
//	Public Instance Methods
	public abstract boolean failure (Exception ex);
}

Passed To: RMISocketFactory.setFailureHandler()

Returned By: RMISocketFactory.getFailureHandler()

RMIServerSocketFactory

Java 1.2

java.rmi.server

This interface represents a source for server sockets that is used by the RMI internals to make client connections during RMI calls. It is possible to provide a custom socket factory to be used with a particular remote object, by using the appropriate constructors on the UnicastRemoteObject or Activatable classes, or, with a particular registry, by using the appropriate LocateRegistry.createRegistry() method. This can be useful in situations where a firewall lies between the client and the server object or the remote registry, and specialized sockets are needed to negotiate the firewall protocol.

The RMIServerSocketFactory creates ServerSocket objects that are used by remote objects to accept client connections.

public abstract interface RMIServerSocketFactory {
//	Public Instance Methods
	public abstract java.net.ServerSocket createServerSocket (int port) throws IOException;
}

Implementations: RMISocketFactory

Passed To: java.rmi.activation.Activatable.{Activatable(), exportObject()}, java.rmi.registry.LocateRegistry.createRegistry(), UnicastRemoteObject.{exportObject(), UnicastRemoteObject()}

RMISocketFactory

Java 1.1

java.rmi.server

PJ1.1(opt)

This abstract class provides an interface for the RMI internals to use to create sockets for both client and server communications. It implements both the RMIClientSocketFactory and the RMIServerSocketFactory interfaces, so it can create either Socket objects for clients or ServerSocket objects for servers. The factory maintains a RMIFailureHandler to deal with failures encountered while attempting to create sockets. If an error is encountered while creating a socket, the failure() method on the current RMIFailureHandler is called. If the return value is true, the RMISocketFactory attempts the socket creation again; otherwise the factory gives up and throws an IOException.

Client sockets are created using the createSocket() method (inherited from RMIClientSocketFactory), while server sockets are created using the createServerSocket() method (inherited from RMIServerSocketFactory). The current RMISocketFactory for the runtime system can be accessed using the static getSocketFactory() and setSocketFactory() methods. The RMIFailureHandler for the current factory is accessed using the getFailureHandler() and setFailureHandler() methods.

public abstract class RMISocketFactory implements RMIClientSocketFactory, RMIServerSocketFactory {
//	Public Constructors
	public RMISocketFactory ();
//	Public Class Methods
1.2	public static RMISocketFactory getDefaultSocketFactory ();	synchronized
	public static RMIFailureHandler getFailureHandler ();	synchronized
	public static RMISocketFactory getSocketFactory ();	synchronized
	public static void setFailureHandler (RMIFailureHandler fh);	synchronized
	public static void setSocketFactory (RMISocketFactory fac) throws IOException;	synchronized
//	Methods implementing RMIClientSocketFactory
	public abstract java.net.Socket createSocket (String host, int port) throws IOException;
//	Methods implementing RMIServerSocketFactory
	public abstract java.net.ServerSocket createServerSocket (int port) throws IOException;
}

Hierarchy: Object-->RMISocketFactory(RMIClientSocketFactory,RMIServerSocketFactory)

Passed To: RMISocketFactory.setSocketFactory()

Returned By: RMISocketFactory.{getDefaultSocketFactory(), getSocketFactory()}

ServerCloneException

Java 1.1

java.rmi.server

serializable checked PJ1.1(opt)

This exception is thrown if an attempt to clone a RemoteServer object fails while the clone is being exported. The nested exception is the RemoteException that was thrown during the cloning operation.

public class ServerCloneException extends CloneNotSupportedException {
//	Public Constructors
	public ServerCloneException (String s);
	public ServerCloneException (String s, Exception ex);
//	Public methods overriding Throwable
	public String getMessage ();
1.2	public void printStackTrace ();
1.2	public void printStackTrace (PrintStream ps);
1.2	public void printStackTrace (PrintWriter pw);
//	Public Instance Fields
	public Exception detail ;
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->CloneNotSupportedException-->ServerCloneException

ServerNotActiveException

Java 1.1

java.rmi.server

serializable checked PJ1.1(opt)

This exception is thrown if the getClientHost() method is called on a RemoteServer when the server isn't handling a remote method call.

public class ServerNotActiveException extends Exception {
//	Public Constructors
	public ServerNotActiveException ();
	public ServerNotActiveException (String s);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->ServerNotActiveException

Thrown By: RemoteServer.getClientHost(), ServerRef.getClientHost()

ServerRef

Java 1.1

java.rmi.server

serializable PJ1.1(opt)

This is an interface to the server-side implementation of a remote object. The getClientHost() method returns the name of the host whose remote method call is currently being serviced by the object implementation. If the server object is not servicing a remote method call when getClientHost() is called, a ServerNotActiveException is thrown. Using the data provided, the exportObject() method either creates or finds a client stub for the given object implementation.

public abstract interface ServerRef extends RemoteRef {
//	Public Constants
1.2	public static final long serialVersionUID ;	=-4557750989390278438
//	Public Instance Methods
	public abstract RemoteStub exportObject (Remote obj, Object data) throws RemoteException;
	public abstract String getClientHost () throws ServerNotActiveException;
}

Hierarchy: (ServerRef(RemoteRef(Externalizable(Serializable))))

Skeleton

Java 1.1; Deprecated in Java 1.2

java.rmi.server

PJ1.1(opt)

Server-side skeleton classes generated by the rmic compiler implement the Skeleton interface. The dispatch() method invokes a method on the server object, and getOperations() returns an array of Operation objects that represent the methods available on the server object.

The Skeleton interface is used in classes generated by the rmic compiler in JDK 1.1. The Java 2 SDK 1.2 rmic compiler doesn't use the Skeleton interface for its skeleton classes, so it has been deprecated as of Java 2.

public abstract interface Skeleton {
//	Deprecated Public Methods
#	public abstract void dispatch (Remote obj, RemoteCall theCall, int opnum, long hash) throws Exception;
#	public abstract Operation[ ] getOperations ();
}

SkeletonMismatchException

Java 1.1; Deprecated in Java 1.2

java.rmi.server

serializable checked PJ1.1(opt)

This RemoteException is thrown during a remote method call if a mismatch is detected on the server between the hash code of the client stub and the hash code of the server implementation. It is usually received by the client wrapped in a ServerException.

public class SkeletonMismatchException extends RemoteException {
//	Public Constructors
#	public SkeletonMismatchException (String s);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->SkeletonMismatchException

SkeletonNotFoundException

Java 1.1; Deprecated in Java 1.2

java.rmi.server

serializable checked PJ1.1(opt)

This RemoteException is thrown during the export of a remote object, if the corresponding skeleton class for the object either cannot be found or loaded for some reason.

public class SkeletonNotFoundException extends RemoteException {
//	Public Constructors
	public SkeletonNotFoundException (String s);
	public SkeletonNotFoundException (String s, Exception ex);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->SkeletonNotFoundException

SocketSecurityException

Java 1.1

java.rmi.server

serializable checked PJ1.1(opt)

This exception is a subclass of ExportException that is thrown if a socket security violation is encountered while attempting to export a remote object. An example would be an attempt to export an object on an illegal port.

public class SocketSecurityException extends ExportException {
//	Public Constructors
	public SocketSecurityException (String s);
	public SocketSecurityException (String s, Exception ex);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->ExportException-->SocketSecurityException

UID

Java 1.1

java.rmi.server

serializable PJ1.1(opt)

A UID is an identifier that is unique with respect to a particular host. UID objects are used internally by RMI's distributed garbage collector and are generally not dealt with directly in application code.

public final class UID implements Serializable {
//	Public Constructors
	public UID ();
	public UID (short num);
//	Public Class Methods
	public static UID read (DataInput in) throws IOException;
//	Public Instance Methods
	public void write (DataOutput out) throws IOException;
//	Public methods overriding Object
	public boolean equals (Object obj);
	public int hashCode ();
	public String toString ();
}

Hierarchy: Object-->UID(Serializable)

Returned By: UID.read()

UnicastRemoteObject

Java 1.1

java.rmi.server

serializable remote PJ1.1(opt)

This class represents a nonreplicated remote object, or in other words, an object that lives as a singular implementation on a server, with a point-to-point connection to each client through reference stubs. This remote server class does not implement persistence, so client references to the object are valid only during the lifetime of the object.

public class UnicastRemoteObject extends RemoteServer {
//	Protected Constructors
	protected UnicastRemoteObject () throws RemoteException;
1.2	protected UnicastRemoteObject (int port) throws RemoteException;
1.2	protected UnicastRemoteObject (int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf) throws RemoteException;
//	Public Class Methods
	public static RemoteStub exportObject (Remote obj) throws RemoteException;
1.2	public static Remote exportObject (Remote obj, int port) throws RemoteException;
1.2	public static Remote exportObject (Remote obj, int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf) throws RemoteException;
1.2	public static boolean unexportObject (Remote obj, boolean force) throws NoSuchObjectException;
//	Public methods overriding Object
	public Object clone () throws CloneNotSupportedException;
}

Hierarchy: Object-->RemoteObject(Remote,Serializable)-->RemoteServer-->UnicastRemoteObject

Subclasses: java.rmi.activation.ActivationGroup

Unreferenced

Java 1.1

java.rmi.server

PJ1.1(opt)

If a server object implements this interface, the unreferenced() method is called by the RMI runtime system when the last client reference to a remote object is dropped. A remote object shouldn't be garbage collected until all its remote and local references are gone. So the unreferenced() method isn't a trigger for an object to be finalized, but rather a chance for the remote object to respond appropriately when its client reference count goes to zero. The unreferenced object could, for example, start a timer countdown to move the object to persistent storage after a given idle time with respect to remote clients.

public abstract interface Unreferenced {
//	Public Instance Methods
	public abstract void unreferenced ();
}

Chapter 17. The java.rmi.server Package

Figure 17-1. The java.rmi.server package