Book Home Java Distributed Computing Search this book

D.3. The java.rmi.server Package

This package contains the classes used in server implementations of remote objects. The RemoteServer class acts as the base class for all RMI server objects. UnicastRemoteObject, the single subclass of RemoteServer provided in this package, implements a non-persistent, point-to-point object communication scheme. Other subclasses of RemoteServer could be written to implement multicast object communication, replicated objects, etc. The java.rmi.server package also contains several Exception subclasses relevant to the server implementation of a remote object.

java.rmi.server.ExportException

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

public class ExportException extends java.rmi.RemoteException {
// Public Constructors
    public ExportException(String descr);
    public ExportException(String descr, Exception nestedExc);
}
java.rmi.server.LoaderHandler

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

public interface LoaderHandler {
// Class Constants
    public final static String packagePrefix;
// Public Instance Methods
    public Object getSecurityContext(ClassLoader loader);
    public Class loadClass(String name);
    public Class loadClass(URL codebase, String name)
                 throws MalformedURLException, ClassNotFoundException;
}
java.rmi.server.LogStream

This class provides the server with an output stream to an error log. LogStreams can't be created directly by the 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 used to create new LogStreams can be gotten through the getDefaultStream() method, and set using the setDefaultStream() method.

public class LogStream extends PrintStream {
// Class Constants
    public static final int SILENT;
    public static final int BRIEF;
    public static final int VERBOSE;
// Class Methods
    public static synchronized PrintStream getDefaultStream();
    public static LogStream log(String name);
    public static int parseLevel(String s);
    public static synchronized void setDefaultStream(
       PrintStream newDefault);
// Public Instance Methods
    public synchronized OutputStream getOutputStream();
    public synchronized void setOutputStream(OutputStream out);
    public String toString();
    public void write(byte b[], int off, int len);
    public void write(int b);
} 
java.rmi.server.ObjID

An ObjID is used on an object server to uniquely identify exported remote objects. It's used primarily 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 ObjIDs are equal. The ObjID class also has read() and write() methods that serve to marshal and unmarshal an ObjID from I/O streams.

public final class ObjID implements java.io.Serializable {
// Public Constructors
    public ObjID();
    public ObjID(int num);
// Class Constants
    public static final int REGISTRY_ID;
    public static final int DGC_ID;
// Class Methods
    public static ObjID read(ObjectInput in) 
                        throws java.io.IOException;
// Public Instance Methods
    public boolean equals(Object obj);
    public int hashCode();
    public String toString();
    public void write(ObjectOutput out) throws java.io.IOException;
}
java.rmi.server.Operation

An Operation contains a description of a method on a remote object.

public class Operation {
// Public Constructors
    public Operation(String op);
// Public Instance Methods
    public String getOperation();
    public String toString();
}
java.rmi.server.RemoteCall

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

public interface RemoteCall {
    public void done() throws IOException;
    public void executeCall() throws Exception;
    public ObjectInput getInputStream()  throws IOException;
    public ObjectOutput getOutputStream()  throws IOException;
    public ObjectOutput getResultStream(boolean success)
                        throws IOException, StreamCorruptedException;
    public void releaseInputStream() throws IOException;
    public void releaseOutputStream()  throws IOException;
} 
java.rmi.server.RemoteObject

The RemoteObject class reimplements key Object methods for remote objects, and maintains a RemoteRef object that 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 will have the same hash code.

public abstract class RemoteObject 
    implements Remote, java.io.Serializable {
// Protected Constructors
    protected RemoteObject();
    protected RemoteObject(RemoteRef newref);
// Protected Instance Variables
    transient protected RemoteRef >ref;
// Public Instance Methods
    public boolean equals(Object obj);
    public int hashCode();
    public String toString();
} 
java.rmi.server.RemoteRef

A handle on the object implementing a remote object reference. Each RemoteObject contains a RemoteRef, which acts as its interface to the actual remote object it represents. Normally, you won't need to interact directly with RemoteRefs from your application code. Rather, application code will interact with RemoteObjects, which use their internal RemoteRefs to perform remote method invocations.

The newCall() method is used to create 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, then 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 RemoteObjects to implement the remote versions of the equals(), hashCode(), and toString() methods.

public interface RemoteRef extends java.io.Externalizable {
// Class Constants
    public final static String packagePrefix;
// Public Instance Methods
    public void done(RemoteCall call) throws RemoteException;
    public String getRefClass(java.io.ObjectOutput out);
    public void invoke(RemoteCall call) throws Exception;
    public RemoteCall newCall(RemoteObject obj, Operation[] op,
                              int opnum, long hash) 
                      throws RemoteException;
    public boolean remoteEquals(RemoteRef obj);
    public int remoteHashCode();
    public String remoteToString();
}
java.rmi.server.RemoteServer

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). In the current version of RMI, the only concrete subclass provided is UnicastRemoteServer, which implements a nonreplicated remote object.

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 this RemoteServer.

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

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 into remote method invocations on the remote object implementation.

public abstract class RemoteStub extends RemoteObject {
// Protected Constructors
    protected RemoteStub();
    protected RemoteStub(RemoteRef ref);
// Protected Class Methods
    protected static void setRef(RemoteStub stub, RemoteRef ref);
} 
java.rmi.server.RMIClassLoader

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, which starts at a particular codebase.

public class RMIClassLoader {
// Class Methods
    public static Object getSecurityContext(ClassLoader loader);
    public static Class loadClass(String name)
        throws MalformedURLException, ClassNotFoundException;
    public static Class loadClass(URL codebase, String name)
        throws MalformedURLException, ClassNotFoundException;
}
java.rmi.server.RMIFailureHandler

The failure() method on the current RMIFailureHandler is called when the RMI communications 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 interface RMIFailureHandler {
// Public Instance Methods
    public boolean failure(Exception ex);
}
java.rmi.server.RMISocketFactory

This abstract class provides an interface for the RMI internals to use to create sockets. The factory can create either Sockets for clients, or ServerSockets for servers. The factory maintains an RMIFailureHandler that it uses 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, then the RMISocketFactory attempts the socket creation again, otherwise the factory gives up and throws an IOException.

Client sockets are created using the createSocket() method, while server sockets are created using the createServerSocket() method. The current RMISocketFactory is 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 {
// Public Instance Methods
    public abstract ServerSocket createServerSocket(int port)
                                 throws IOException;
    public abstract Socket createSocket(String host, int port)
                           throws IOException;
// Class Methods
    public static RMIFailureHandler getFailureHandler();
    public static RMISocketFactory getSocketFactory();
    public static void setFailureHandler(RMIFailureHandler fh);
    public static void setSocketFactory(RMISocketFactory fac)
                       throws IOException;
}
java.rmi.server.ServerCloneException

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 desc)
    public ServerCloneException(String desc, Exception nestedExc);
// Public Instance Variables
    public Exception detail;
// Public Instance Methods
    public String getMessage();
}
java.rmi.server.ServerNotActiveException

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 java.lang.Exception {
// Public Constructors
    public ServerNotActiveException();
    public ServerNotActiveException(String desc);
}
java.rmi.server.ServerRef

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, then a ServerNotActiveException is thrown. The exportObject() method is meant to either create or find a client stub for the given object implementation, using the data provided.

public interface ServerRef extends RemoteRef {
    public RemoteStub exportObject(Remote obj, Object data)
                      throws RemoteException;
    public String getClientHost() throws ServerNotActiveException;
}
java.rmi.server.Skeleton

A Skeleton object lives with a server-side object implementation, dispatching method calls to the remote object implementation. Server implementations generated by the rmic compiler use skeletons.

The dispatch() method invokes the method specified by the operation number opnum on the object implementation obj. It unmarshals the method arguments from the input stream obtained from the RemoteCall argument, passes them to the appropriate method on the Remote object, marshals the results (if any), and returns them to the caller using the output stream on the RemoteCall. The getOperations() method returns an array of Operation objects, which represent the methods available on the remote object.

public interface Skeleton {
    public void dispatch(Remote obj, RemoteCall theCall,
                         int opnum, long hash) 
                throws Exception;
    public Operation[] getOperations();
} 
java.rmi.server.SkeletonMismatchException

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);
}
java.rmi.server.SkeletonNotFoundException

This RemoteException is thrown during the export of a remote object, if the corresponding skeleton class for the object either can't be found or can't be loaded.

public class SkeletonNotFoundException extends RemoteException {
// Public Constructors
    public SkeletonNotFoundException(String desc);
    public SkeletonNotFoundException(String desc, Exception nestedEx);
}
java.rmi.server.SocketSecurityException

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 SocketSecurityException(String s);
    public SocketSecurityException(String s, Exception ex);
}
java.rmi.server.UID

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

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

This class represents a nonreplicated remote object: one that lives as a singular implementation on a server with point-to-point connections to each client. through reference stubs. This remote server class does not implement persistence, so client references to the object are only valid during the lifetime of the object. This is the only concrete subclass of RemoteServer offered in the standard JDK 1.1 distribution.

public class UnicastRemoteObject extends RemoteServer {
// Protected Constructors
    protected UnicastRemoteObject() throws RemoteException;
// Class Methods
    public static RemoteStub exportObject(Remote obj)
                             throws RemoteException;
// Public Instance Methods
    public Object clone() throws CloneNotSupportedException;
}
java.rmi.server.Unreferenced

Appropriately enough, the last interface in this reference is the Unreferenced interface. If a server object implements this interface, then the unreferenced() method is called by the RMI runtime when the last client reference to a remote object is dropped. A remote object shouldn't be garbage collected until all of 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.

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


Library Navigation Links

Copyright © 2001 O'Reilly & Associates. All rights reserved.