Stubs and skeletons

No, we're not talking about a gruesome horror movie. Stubs and skeletons are used in the implementation of remote objects. When you invoke a method on a remote object (which could be on a different host), you are actually calling some local code that serves as a proxy for that object. This is the stub. (It is called a stub because it is something like a truncated placeholder for the object.) The skeleton is another proxy that lives with the real object on its original host. It receives remote method invocations from the stub and passes them to the object.

You never have to work with stubs or skeletons directly; they are hidden from you (in the closet). Stubs and skeletons for your remote objects are created by running the rmic (RMI compiler) utility. After compiling your Java source files normally, you run rmic.

Remote interfaces

So far we've been referring to remote objects as objects (and they are, of course). But to be more specific, remote objects are objects that implement a special remote interface that specifies which of the object's methods can be invoked remotely. The remote interface must extend the java.rmi.Remote interface. Your remote object must implement its remote interface; so does the stub object that is automatically generated for you. In the rest of your code, you should refer to the remote object using its interface--not the object's actual class. Because both the real object and stub implement the remote interface, they are equivalent as far as we are concerned; we never have to worry about whether we have a reference to a stub or an actual implementation of the object locally. This "type equivalence" means that we can use normal language features like casting with remote objects.

All methods in the remote interface must declare that they can throw the exception java.rmi.RemoteException. This exception (actually, one of many subclasses to RemoteException) is thrown when any kind of networking error happens: for example, the server could crash, the network could fail, or you could be requesting an object that for some reason isn't available.

Here's a simple example of the remote interface that defines the behavior of MyRemoteObject; we'll give it two methods that can be invoked remotely, both of which return some kind of Widget object:

public interface MyRemoteObject 
        extends java.rmi.Remote {
    public Widget doSomething() throws java.rmi.RemoteException;
    public Widget doSomethingElse() throws java.rmi.RemoteException;
}

UnicastRemoteObject

The actual implementation of a remote object (not the interface we discussed previously) must extend java.rmi.server.UnicastRemoteObject. This is the RMI equivalent to the familiar Object class. It provides implementations of equals(), hashcode(), and toString() that make sense for remote objects. It also "exports" the object by preparing the Java run-time system to accept network connections for this object. It's possible to do this work yourself, but it isn't necessary.

Here's a remote object class that matches the MyRemoteObject interface; we haven't supplied implementation for the two methods or the constructor:

public class RemoteObjectImpl 
        implements MyRemoteObject
        extends java.rmi.UnicastRemoteObject {
    public RemoteObjectImpl() throws java.rmi.RemoteException {...}
    public Widget doSomething() throws java.rmi.RemoteException {...}
    public Widget doSomethingElse() throws java.rmi.RemoteException {...}
    // other non-public methods
    ...
}

This class can have as many additional methods as it needs; presumably, most of them will be private, but that isn't strictly necessary. We have to supply a constructor explicitly, even if the constructor does nothing, because the constructor (like any method) can throw a RemoteException; we therefore can't use the default constructor.

The name UnicastRemoteObject begs the question, "what other kinds of remote objects are there?" Right now, none. It's possible that JavaSoft will develop remote objects using other protocols or multicast techniques in the future.

The RMI registry

The registry is the RMI phone book. You use the registry to look up a reference to a registered remote object on another host. We've already described how remote references can be passed back and forth by remote method calls. But the registry is needed to bootstrap the process; the client needs some way of looking up some initial object.

The registry is implemented by a class called Naming and an application called rmiregistry, which must be running before you start a Java program that uses the registry. To use the registry, create an instance of a remote object and have it bind itself to a particular name in the registry. (Remote objects that bind themselves to the registry usually provide a main() method for this purpose.) The name can be anything you choose; it takes the form of a slash (/) separated path. When a client object wants to find your object, it constructs a special URL with the rmi: protocol, the hostname, and the object name. On the client, the RMI Naming class then talks to the registry and returns the remote object reference.

Which objects need to register themselves with the registry? Certainly, any object that the client has no other way of finding. A call to a remote method can return another remote object without using the registry. Likewise, a call to a remote method can have another remote object as its argument, without requiring the registry. You could design your system so that only one object registers itself, and then serves as a factory for any other remote objects you need. In other words, it wouldn't be hard to build a simple object request "bouncer" (I won't say "broker") that returns references to various objects. Why avoid using the registry? The current RMI registry is not very sophisticated, and lookups tend to be slow. It is not intended to be a general purpose directory service but simply to bootstrap RMI communications. It wouldn't be surprising if JavaSoft releases a much improved registry in the future, but that's not the one we have now.

Dynamic class loading

Before running the example, we told you to distribute all the class files to both the client and server machines. However, RMI was designed to ship classes, in addition to data, around the network; you shouldn't have to distribute all the classes in advance. Let's go a step further, and have RMI load classes for us, as needed.

First, we need to tell RMI where to find any other classes it needs. We can use the system property java.rmi.server.codebase to specify a URL on an HTTP server when we run our client or server. This URL specifies the base directory in which RMI will begin its search for classes. When RMI sends a serialized object (i.e., an object's data) to some client, it also sends this URL. If the recipient needs the class file in addition to the data, it fetches the file via HTTP. To be more precise: if the object needed is a remote object, the recipient fetches the desired class's stub, which was created by rmic. Remember that stubs are stand-ins for the objects themselves; their job is to talk to the object, which remains on the server. If the object needed doesn't implement the Remote interface, the recipient fetches the object's class file itself, and uses the object locally. Therefore, we don't have to distribute class files; we can let clients download them as necessary. In Figure 11.3, we see MyClient going to the registry to get a reference to the Server object. Then MyClient dynamically downloads the stub class for MyServer from the HTTP daemon running on the server host.

Figure 11.3: RMI clients load classes dynamically

We can now split our class files between the server and client machines. For example, we could withhold the MyCalculation class from the server, since it really belongs to the client. Instead, we can make the MyCalculation class available via an HTTP daemon on some machine (probably our client's) and specify the URL when we run MyClient:

% java -Djava.rmi.server.codebase='http://myserver/foo/' MyClient

Passing remote object references

So far, we haven't done anything that we couldn't have done with the simple object protocol. We only used one remote object, MyServer, and we got its reference from the RMI registry. Now we'll extend our example to pass some remote references between the client and server. We'll add two methods to our remote Server interface:

public interface Server extends java.rmi.Remote {
	...

    StringEnumeration getList() throws java.rmi.RemoteException;

    void asyncExecute( WorkRequest work, WorkListener listener ) 
		throws java.rmi.RemoteException;
}

Next we'll spice up our work request feature by adding an asyncExecute() method. asyncExecute() lets us hand off a WorkRequest object as before, but it does the calulation on its own time. The return type for asyncExecute() is void, because it doesn't actually return a value; we get the result later. With the request, our client passes a reference to a WorkListener object that is to be notified when the WorkRequest is done. We'll have our client implement WorkListener itself.

Because this is to be a remote object, our interface must extend Remote, and its methods must throw RemoteExceptions:

public interface StringEnumeration extends Remote {
    public boolean hasMoreItems() throws RemoteException;
    public String nextItem() throws RemoteException;
}

public class StringEnumerator 
    extends java.rmi.server.UnicastRemoteObject implements StringEnumeration {

    String [] list;
    int index = 0;
 
    public StringEnumerator( String [] list ) throws RemoteException { 
        this.list = list;
    }
    public boolean hasMoreItems() throws RemoteException {
        return index < list.length;
    }
    public String nextItem() throws RemoteException {
        return list[index++];
    }
}

Next, we'll define the WorkListener remote interface. This is the interface that defines how an object should listen for a completed WorkRequest. It has one method, workCompleted(), which the server that is executing a WorkRequest calls when the job is done:

public interface WorkListener extends Remote {
    public void workCompleted( WorkRequest request, Object result ) 
		throws RemoteException;
}

public class MyServer 
    extends java.rmi.server.UnicastRemoteObject implements Server {   
	... 

    public StringEnumeration getList() throws RemoteException {
        return new StringEnumerator( 
            new String [] { "Foo", "Bar", "Gee" } );
    }
    public void asyncExecute( WorkRequest request , WorkListener listener ) 
        throws java.rmi.RemoteException {

        Object result = request.execute();
        listener.workCompleted( request, result );
    }
}

We have to modify MyClient to implement the remote WorkListener interface. This turns MyClient into a remote object, so we must make it a UnicastRemoteObject. We also add the workCompleted() method that the WorkListener interface requires:

public class MyClient extends java.rmi.server.UnicastRemoteObject 
	implements WorkListener {

    ...
    public void workCompleted( WorkRequest request, Object result ) 
        throws RemoteException {
        System.out.println("Async work result = " + result);
    }
}

Finally, we want MyClient to exercise the new features. Add these lines after the calls to getDate() and execute():

    // MyClient constructor
    ...
    StringEnumeration se = server.getList();
    while ( se.hasMoreItems() )
        System.out.println( se.nextItem() );

    server.asyncExecute( new MyCalculation(100), this );

We use getList() to get the enumeration from the server, then loop, printing the strings. We also call asyncExecute() to perform another calculation; this time, we square the number 100. The second argument to asyncExecute() is the WorkListener to notify when the data is ready; we pass a reference to ourself (this).

Now all we have to do is compile everything and run rmic to make the stubs for all our remote objects:

rmic MyClient MyServer StringEnumerator

Fri Jul 11 23:57:19 PDT 1997
4
Foo
Bar
Gee
Async work result = 10000