RMI: Programmer's Checklist

Source

The interface

• Create or modify public interface XYZ extends java.rmi.Remote
• Add the Remote method.

public <return-type> methodName( <parameter-list> ) throws java.rmi.RemoteException;

• The return type and all the parameters are Serializable: Each either:
• implements java.io.Serializable or are a subclass of a Serializable class
• is a Remote object (i.e., implement an interface that extends Remote directly or indirectly).

The server (implementation of the interface)

• implements XYZ.
• has a no-argument constructor that throws RemoteException.
• The [main] method that instantiates a server object:
• sets a security manager ( needed, only if the server loads classes not found in its CLASSPATH) :
if ( System.getSecurityManager() == null )
{
    System.setSecurityManager( new java.rmi.RMISecurityManager() );
}
• constructs the remote object (can throw a RemoteException: declare this in the method's throws clause or place within a try-catch).
• may need to bind the object to a service reference String in its machine's rmiregistry with the bind or rebind methods.
• If an external rmiregistry is running on the machine:
java.rmi.Naming.rebind("HelloServer", obj);// obj refers to the constructed remote object server; "HelloServer" illustrates the service reference String.
• The server can start an rmiregistry internally (i.e., within its own JVM) on some port. Then, we don't have rmiregistries running in the background on machines where people forgot to terminate the rmiregistries before they logged out.
  

The client

• sets a SecurityManager (see server instructions); it downloads the server stub.
• gets a reference to the remote object

Hello hello = (Hello) Naming.lookup("//" + machineName + "/HelloServer"); // machineName is a String containing either the domain name or the IP address of the machine on whch the server and rmiregistry are running. This can throw various exceptions (see Java API for java.rmi.Naming.lookup). So, it must be within a try-catch block or the method must include these exceptions in its throws clause.
• invokes a remote method on the reference:
• The invocation must either
• be within a try-catch block for RemoteException
• include the RemoteException in the invoking method's throws clause

Compiling

• compile all the .java files as usual.
• rmic all remote objects.

Running

• Establish the code base:
• put stub class files in your codebase, as well as any other classes that the client does not need to have in its classpath.
• these files need to be readable by all.
• the path to them needs to be readable and executable by all.
• Check that this has been done successfully by pointing a web browser to the directory that contains the downloadable files. You must get a directory list that includes the necessary files. If you get any other response, either the files are missing or the permissions are not set correctly on the files or the directories.
• Specify a policy file that allows downloading of your classes. An example of a policy file that is sufficient (but dangerously permissive) is:

grant
{
  // Allow everything for now
  permission java.security.AllPermission;
};

• Specify the codebase when you run the server.

java -Djava.rmi.server.codebase=http://www.cs.ucsb.edu/~cappello/classes/   \
     -Djava.security.policy=policy                                          \
      Application <command-line parameters go here>

Runtime Exceptions

java.io.NotSerializableException

The object in question does not implement java.io.Serializable

java.security.AccessControlException: access denied

The JVM may not have access to a policy file, either because it is missing or unreadable, or the specification of where it is (on the command line) is incorrect.