2.4 Overview of RMI Interfaces and Classes

2.4.1 The java.rmi.Remote Interface

• A remote interface must at least extend, either directly or indirectly, the interface java.rmi.Remote.
• Each method declaration in a remote interface or its super-interfaces must satisfy the requirements of a remote method declaration as follows:
  • A remote method declaration must include the exception java.rmi.RemoteException (or one of its superclasses such as java.io.IOException or java.lang.Exception) in its throws clause, in addition to any application-specific exceptions (note that application specific exceptions do not have to extend java.rmi.RemoteException).
  • In a remote method declaration, a remote object declared as a parameter or return value (either declared directly in the parameter list or embedded within a non-remote object in a parameter) must be declared as the remote interface, not the implementation class of that interface.

    public interface Remote {}

• A remote interface may also extend another non-remote interface, as long as all of the methods (if any) of the extended interface satisfy the requirements of a remote method declaration.

    public interface BankAccount extends java.rmi.Remote {
        public void deposit(float amount)
                throws java.rmi.RemoteException;
        public void withdraw(float amount)
                throws OverdrawnException, java.rmi.RemoteException;
        public float getBalance()
                throws java.rmi.RemoteException;
}

    public interface Alpha {
        public final String okay = "constants are okay too";
        public Object foo(Object obj)
                throws java.rmi.RemoteException;
        public void bar() throws java.io.IOException;
        public int baz() throws java.lang.Exception;
}


public interface Beta extends Alpha, java.rmi.Remote {
        public void ping() throws java.rmi.RemoteException;
}

2.4.2 The RemoteException Class

The exception java.rmi.RemoteException is thrown when a remote method invocation fails for some reason. Some reasons for remote method invocation failure include:

• Communication failure (the remote server is unreachable or is refusing connections; the connection is closed by the server, etc.)
• Failure during parameter or return value marshalling or unmarshalling
• Protocol errors

2.4.3 The RemoteObject Class and its Subclasses

• The class java.rmi.server.RemoteObject provides implementations for the java.lang.Object methods, hashCode, equals, and toString that are sensible for remote objects.
• The methods needed to create remote objects and export them (make them available to remote clients) are provided by the classes UnicastRemoteObject and Activatable. The subclass identifies the semantics of the remote reference, for example whether the server is a simple remote object or is an activatable remote object (one that executes when invoked).
• The java.rmi.server.UnicastRemoteObject class defines a singleton (unicast) remote object whose references are valid only while the server process is alive.
• The class java.rmi.activation.Activatable is an abstract class that defines an activatable remote object that starts executing when its remote methods are invoked and can shut itself down when necessary.