2.3 RMI Interfaces and Classes

The interfaces and classes that are responsible for specifying the remote behavior of the RMI system are defined in the java.rmi and the java.rmi.server packages. The following figure shows the relationship between these interfaces and classes:

2.3.1 The Remote Interface

All remote interfaces extend, either directly or indirectly, the interface java.rmi.remote. The Remote interface defines no methods, as shown here:

public interface Remote {}

For example, the following code fragment defines a remote interface for a bank account that contains methods that deposit to the account, get the account balance, and withdraw from the account:

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

The methods in a remote interface must be defined as follows:

• Each method must declare java.rmi.RemoteException in its throws clause, in addition to any application-specific exceptions.
• A remote object passed as an argument or return value (either directly or embedded within a local object) must be declared as the remote interface, not the implementation class.

2.3.2 The RemoteException Class

The java.rmi.RemoteException class is the superclass of all exceptions that can be thrown by the RMI runtime. To ensure the robustness of applications using the RMI system, each method declared in a remote interface must specify java.rmi.RemoteException in its throws clause.

java.rmi.RemoteException is thrown when a remote method invocation fails (for example when the network fails or the server for the call cannot be reached). This allows the application making the remote invocation to determine how best to deal with the remote exception.

2.3.3 The RemoteObject Class and its Subclasses

RMI server functions are provided by java.rmi.server.RemoteObject and its subclasses, java.rmi.server.RemoteServer and java.rmi.server.UnicastRemoteObject:

• The java.rmi.server.RemoteObject class provides the remote semantics of Object by implementing methods for hashCode, equals, and toString.
• The functions needed to create objects and export them (make them available remotely) are provided abstractly by java.rmi.server.RemoteServer and concretely by its subclass(es). The subclass identifies the semantics of the remote reference, for example whether the server is a single object or is a replicated object requiring communications with multiple locations.
• The java.rmi.server.UnicastRemoteObject class defines a singleton (unicast) remote object whose references are valid only while the server process is alive.