Appendix D. RMI Quick Reference

A RemoteException caused by an attempt to perform an improper operation on the Naming or Registry interface. A registry only allows local requests to bind, rebind or unbind objects, so an attempt to call these methods on a remote registry results in an AccessException.

public class AccessException extends java.rmi.RemoteException {
// Public constructors
    public AccessException(String descr);
    public AccessException(String descr, Exception detail);
} 

An exception that is thrown when an attempt is made to bind an object to a name that is already bound.

public class AlreadyBoundException extends java.lang.Exception {
// Public constructors
    public AlreadyBoundException();
    public AlreadyBoundException(String descr);
}

A RemoteException that's thrown when a remote host refuses to connect during a remote method call.

public class ConnectException extends RemoteException {
// Public constructors
    public ConnectException(String descr);
    public ConnectException(String descr, Exception nestedExc);
}

A RemoteException thrown if there is an I/O error while attempting to make a remote method call.

public class ConnectIOException extends RemoteException {
    public ConnectIOException(String descr);
    public ConnectIOException(String descr, Exception ex);
}

A RemoteException thrown if an I/O error occurs while attempting to marshal any part of a remote method call (header data or method arguments).

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

This is the primary application interface to the naming service within the RMI registry. References to remote objects are obtained with the lookup() method. Local object implementations can be bound to names within the local registry using the bind() and rebind() methods. Locally bound objects can be removed from the name registry using unbind(). All of the names for objects currently stored in the registry can be obtained using the list() method.

Each name argument to the methods on the Naming interface takes the form of a URL (e.g., rmi://remoteHost:port/objName). If a local object is being referenced, and the object is exported to the default registry port, then the URL can simply take the form of the object's name in the local registry (e.g., objName). This is possible because the rmi: protocol is assumed if it isn't present in the URL, and the default host is the local host.

While the lookup() method can reference any remote RMI registry, the bind(), rebind(), and unbind() methods can only be called on the local registry. Attempting to call these methods against a remote registry will result in an AccessException being thrown.

public final class Naming {
// Class Methods
    public static void bind(String name, Remote obj) // Register
        throws AlreadyBoundException, java.net.MalformedURLException,
        UnknownHostException, RemoteException;
    public static String[] list(String name) // List bound object names
        throws RemoteException, java.net.MalformedURLException,
        UnknownHostException
    public static Remote lookup(String name) // Gets remote object
        throws NotBoundException, java.net.MalformedURLException,
        UnknownHostException, RemoteException;
    public static void rebind(String name, Remote obj)
        throws RemoteException, java.net.MalformedURLException,
        UnknownHostException;
    public static void unbind(String name) // Remove an object
        throws RemoteException, NotBoundException, 
        java.net.MalformedURLException, UnknownHostException;
}

A RemoteException thrown when you attempt to invoke a method on a remote object that is no longer available.

public class NoSuchObjectException extends java.rmi.RemoteException {
// Public constructors
    public NoSuchObjectException(String descr);
}

An exception that is thrown when a lookup is attempted using a name with no object bound to it.

public class NotBoundException extends java.lang.Exception {
// Public constructors
    public NotBoundException();
    public NotBoundException(String descr);
}

Every remote object has to implement this interface, and any methods intended to be remotely callable have to be defined within a Remote interface. This is a placeholder interface that identifies all remote objects, but doesn't define any methods of its own.

public interface Remote {}

An IOException that is thrown when an error occurs during any remote object operation. The RemoteException includes a Throwable data member that represents the nested exception that caused the RemoteException to be thrown. For example, if an exception occurs on the server while executing a remote method, then the client receives a RemoteException (in the form of a ServerException, one of its subclasses) with its Throwable data member initialized to the server-side exception that caused the client-side RemoteException.

public class RemoteException extends java.io.IOException {
// Public Constructors
    public RemoteException();
    public RemoteException(String descr);
    public RemoteException(String descr, Throwable nestedExc);
// Public Instance Methods
    public String getMessage();
// Public Instance Variables
    public Throwable detail;
}

A SecurityException thrown by the RMISecurityManager when a security violation is detected during a remote operation.

public class RMISecurityException extends java.lang.SecurityException {
// Public Constructors
    public RMISecurityException(String name);
    public RMISecurityException(String name, String arg);
}

The RMISecurityManager enforces the security policy for classes that are loaded as stubs for remote objects, by overriding all of the relevant access-check methods from the SecurityManager. By default, stub objects are only allowed to perform class definition and class access operations. If the local security manager is not an RMISecurityManager (using the System.setSecurityManager() method), then stub classes will only be loadable from the local file system.

You normally won't need to interact with the RMISecurityManager directly within your application code, except to set it as the system security manager before entering your RMI code.

public class RMISecurityManager extends SecurityManager {
// Public Constructors
    public RMISecurityManager();
// Public Instance Methods
    public synchronized void checkAccept(String host, int port);
    public synchronized void checkAccess(Thread t);
    public synchronized void checkAccess(ThreadGroup g);
    public void checkAwtEventQueueAccess();
    public synchronized void checkConnect(String host, int port);
    public void checkConnect(String host, int port, Object context);
    public synchronized void checkCreateClassLoader();
    public void checkDelete(String file);
    public synchronized void checkExec(String cmd);
    public synchronized void checkExit(int status);
    public synchronized void checkLink(String lib);
    public synchronized void checkListen(int port);
    public void checkMemberAccess(Class clazz, int which);
    public void checkMulticast(InetAddress maddr);
    public void checkMulticast(InetAddress maddr, byte ttl);
    public synchronized void checkPackageAccess(String pkg);
    public synchronized void checkPackageDefinition(String pkg);
    public void checkPrintJobAccess();
    public synchronized void checkPropertiesAccess();
    public synchronized void checkPropertyAccess(String key);
    public synchronized void checkRead(FileDescriptor fd);
    public synchronized voidcheckRead(String file);
    public void checkRead(String file, Object context);
    public void checkSecurityAccess(String provider);
    public synchronized void checkSetFactory();
    public void checkSystemClipboardAccess();
    public synchronized boolean checkTopLevelWindow(Object window);
    public synchronized void checkWrite(FileDescriptor fd);
    public synchronized void checkWrite(String file);
    public Object getSecurityContext();
}

An error that occurs while a server is executing a remote method. The nested Throwable data member (inherited from RemoteException) contains the server-side exception that generated the error.

public class ServerError extends RemoteException {
// Public Constructors
    public ServerError(String descr, Error err);
}

An exception that occurs while a server is executing a remote method. The nested Throwable data member (inherited from RemoteException) contains the server-side exception that generated the exception.

public class ServerException extends RemoteException {
// Public Constructors
    public ServerException(String descr);
    public ServerException(String descr, Exception nestedExc);
}

A RemoteException that occurs while the server is executing a remote method.

public class ServerRuntimeException extends RemoteException {
// Public Constructors
    public ServerRuntimeException(String descr, Exception nestedExc);
}

This exception can occur either when an object is being exported to participate in remote RMI calls, or during a remote method call. During export on the server, this exception is thrown if the stub class for the object can't be found or used for some reason (e.g., the stub class isn't in the CLASSPATH of the server process, or the stub class can't be instantiated). During a remote method call, the client can receive this exception if the remote object hasn't been exported completely or correctly.

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

All exceptions are unexpected, right? An UnexpectedException is thrown if an exception that isn't specified on a remote method's signature is encountered during the return from a remote method call. The unexpected exception can occur on the server or on the client. The nested Throwable object inherited from RemoteException contains the actual exception that occurred.

public class UnexpectedException extends RemoteException {
// Public Constructors
    public UnexpectedException(String descr);
    public UnexpectedException(String descr, Exception NestedExc);
}

This RemoteException is thrown if the host specified during a Naming lookup can't be found.

public class UnknownHostException extends RemoteException {
// Public Constructors
    public UnknownHostException(String descr);
    public UnknownHostException(String descr, Exception nestedEx);
}

This RemoteException is thrown if an error occurs while unmarshaling the return value from a remote method call. The source of the error could be an I/O error while sending the header or the value of the return from the server to the client, or the fact that the class of the return object is not found.

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