RMI: Programmer's Checklist

Source

The Remote interface

• Create or modify public interface XYZ extends java.rmi.Remote
• Add the Remote method.
• The return type and parameters are Serializable: Each either:
  • implements java.io.Serializable
  • extends a Serializable class
  • is a Remote object (i.e., implements an interface that extends Remote directly or indirectly).

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

The server (implementation of the interface)

• extends UnicastRemoteObject or its constructor invokes UnicastRemoteObject.exportObject(this) (see Javadoc).
• 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 instantiate within a try-catch).
  • may need to bind the object to its 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.
  • Start an rmiregistry internally (i.e., within its own JVM) on some port. Then, we don't have rmiregistries running in the background on GSL 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. Naming.lookup can throw various exceptions (see Java API for java.rmi.Naming.lookup): 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, which must either
  • be within a try-catch block for RemoteException
  • include the RemoteException in the invoking method's throws clause

Compile

Compile all the .java files as usual.

Run

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; 
};
	

Establish the code base:

Make a codebase for all client classes that the server needs but does not have in its classpath (e.g., classes of Remote method parameters)

• put class files in your codebase that the client/server 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: Point a web browser to the directory containing 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 the codebase when you run the server

For example, the command below runs a Java application called Application. In this case, the system expects the policy file called policy to be in the directory from which the java command executes.

java -Djava.rmi.server.codebase=http://www.cs.ucsb.edu/~cappello/classes/ \ 
     -Djava.security.policy=policy                                        \ 
      Application 
	

I need class files in my public_html/classes directory to be readable by all. The classes directory needs to be readable and executable by all. The trailing slash on the codebase specification is crucial.

Runtime Exceptions

java.io.NotSerializableException

The object, Obj, in question either:

• must implement java.io.Serializable, or
• both:
• implements an interface that extends Remote, and
• is exported by either:
• extending UnicastRemoteObject, or
• the static method UnicastRemoteObject.exportObject( Obj )

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.