Learning Java, 4th Edition

Remote Method Invocation

The most fundamental means of communication in Java is method invocation. Mechanisms such as the Java event model are built on simple method invocations between objects in the same virtual machine. Therefore, when we want to communicate between virtual machines on different hosts, it’s natural to want a mechanism with similar capabilities and semantics—to run a method “over there.” Java’s RMI mechanism does just that. It lets us get a reference to an object on a remote host and use it almost as if it were in our own virtual machine. RMI lets us invoke methods on remote objects, passing real Java objects as arguments and getting real Java objects as returned values.

Remote invocation is nothing new. For many years, C programmers have used remote procedure calls (RPC) to execute a C function on a remote host and return the results. The primary difference between RPC in other languages and RMI is that RPC is usually primarily concerned with data structures. It’s relatively easy to pack up data and ship it around, but RMI tries to do one better. In Java, we don’t just work with data structures; we work with objects that contain both data and methods for operating on the data. Not only do we have to be able to ship the state of an object (the data) over the wire, but the recipient has to be able to interact with the object (use its methods) after receiving it. With Java RMI, you can work with network services in an object-oriented fashion, using real, extensible types and pass “live” references between client and server.

It should be no surprise that RMI uses object serialization, which allows us to send graphs of objects (objects and the tree of all the connected objects that they reference). When necessary, RMI can also use dynamic class loading and the security manager to transport Java classes safely. In addition to making remote method calls almost as easy to use as local calls, RMI makes it possible to ship both data and behavior (code) around the Net.

Real-World Usage

Now that the introduction has you all excited, we should put things in a little more context. While Java RMI has proven to be very powerful, it has never really caught on as a way to build general applications. Instead, RPC-like web services using XML and HTTP to transfer data using standardized network protocols have ruled for many years. The reason for this is primarily that they are cross-platform and can be easily consumed by JavaScript running within web browsers. Web services that run over HTTP are also generally immune to firewall issues since they use the same mechanism as all web pages. Since the tools to develop applications using web services have become mature and easy to use, developers tend to use them even when building applications purely in Java, where RMI might otherwise be more powerful. In this section we’ll go ahead and show you what can be done with RMI; however, you will definitely want to check out the chapters on web services and web applications later in this book as well.

Remote and Nonremote Objects

Before an object can be used remotely through RMI, it must be serializable. But that’s not sufficient. Remote objects in RMI are real distributed objects. As the name suggests, a remote object can be an object on a different machine or an object on the local host. The term remote means that the object is used through a special kind of object interface that can be passed over the network. Like normal Java objects, remote objects are passed by reference. Regardless of where the reference is used, the method invocation occurs on the original object, which still lives on its original host. If a remote host returns a reference to one of its remote objects to you, you can call the object’s methods; the actual method invocations happen on the remote host where the underlying object resides.

Nonremote objects are simpler; they’re just normal serializable objects. (You can pass these over the network as we did in the previous section.) The catch is that when you pass a nonremote object over the network, it is simply copied, so references to the object on one host are not the same as those on the remote host. Nonremote objects are passed by value (copying) as opposed to by reference. This may be acceptable for many kinds of data holder objects on your host, such as the client requests and server responses in our previous example. These types of objects are sometimes called value objects or data transfer objects (DTOs).

Remote interfaces

Remote objects implement a special remote interface that specifies which of the object’s methods can be invoked remotely. The remote interface is part of the application that you create by extending the java.rmi.Remote interface. Your remote object then implements its remote interface as it would any other Java interface. In your client-side code, you should then refer to the remote object as an instance of the remote interface—not as an instance of its implementation class. Because both the real object and stub that the client receives implement the remote interface, they are equivalent as far as we are concerned (for method invocation); locally, we never have to worry about whether we have a reference to a stub or to an actual object. This type equivalence means that we can use normal language features such as casting with remote objects. Of course, public fields (variables) of the remote object are not accessible through an interface, so you must make accessor methods if you want to manipulate the remote object’s fields.

One additional requirement for remote objects distinguishes them from local objects. All methods in the remote interface must declare that they can throw the exception java.rmi.RemoteException. This exception (or one of its subclasses) is thrown when any kind of networking error happens (for example, a server crash, network failure, or timeout). Some people see this as a limitation and try to paper over it in various ways. However, the RemoteException is there for a reason—remote objects can behave differently from local objects and your code needs to deal with that issue explicitly. There is no magic bullet (automatic retries, transactions) that truly makes the difference go away.

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

    import java.rmi.*;

    public interface RemoteObject extends Remote {
        public Value doSomething() throws RemoteException;
        public Value doSomethingElse() throws RemoteException;
    }

Exporting remote objects

You make a remote object available to the outside world by using the java.rmi.server.UnicastRemoteObject class. One way is simply to have the implementation of your remote object extend UnicastRemoteObject. When a subclass of UnicastRemoteObject is constructed, the RMI runtime system automatically “exports” it to start listening for network connections from clients. Like java.lang.Object, this superclass also provides implementations of equals(), hashcode(), and toString() that make sense for a remote object.

Here’s a remote object class that implements the RemoteObject interface we showed earlier and extends UnicastRemoteObject; we haven’t shown implementations for the two methods or the constructor:

    public class MyRemoteObject implements RemoteObject
            extends java.rmi.UnicastRemoteObject
    {
        public MyRemoteObject() throws RemoteException {...}
        public Value doSomething() throws RemoteException {...}
        public Value doSomethingElse() throws RemoteException {...}
        // nonremote methods
        private void doSomethingInternal() { ... }
    }

Note that we have to supply a constructor that can throw a RemoteException (even if it does nothing) because UnicastRemoteObject’s default constructor throws RemoteException and, even if it’s not shown, the Java language always delegates to the superclass constructor. This class can have as many additional methods as it needs (presumably most of them will be private, but that isn’t strictly necessary), but these nonremote methods are not required to throw the remote exception.

Now, what if we can’t or don’t want to make our remote object implementation a subclass of UnicastRemoteObject? Suppose, for example, that it has to be a subclass of BankAccount or some other special base type for our system. Well, we can simply take over the job of exporting the object ourselves, using the static method exportObject() of UnicastRemoteObject. The exportObject() method takes as an argument a Remote interface and accomplishes what the UnicastRemoteObject constructor normally does for us. It returns as a value the remote object’s client stub. However, you will normally not do anything with this directly. In the next section, we’ll discuss how clients actually find your service, through the RMI registry (a lookup service).

Normally, exported objects listen on individual ephemeral (randomly assigned) port numbers by default. (This is implementation-dependent.) You can control the port number allocation explicitly by exporting your objects using another form of UnicastRemoteObject.exportObject(), which takes both a Remote interface and a port number as arguments.

Finally, the name UnicastRemoteObject begs the question, “What other kinds of remote objects are there?” Right now, few. There is another type of object called Activatable that is for RMI objects that require persistence over time. We’ll say a few more words about RMI activation later in this chapter, but it’s not something we will get into in detail.

The RMI registry

The registry is RMI’s phone book. You use the registry to look up a reference to a registered remote object on another host, using an application-specified name. We’ve already described how remote references can be passed back and forth by remote method calls. The registry is needed to bootstrap the process by allowing the client to look up an initial object on the remote host.

The registry is implemented by a class called Naming and an application called rmiregistry. The rmiregistry application must be running on a host before you start a Java program that wants to advertise in the registry. You can then create instances of remote objects and bind them to particular names in the registry. A registry 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.

So, which objects need to register themselves with the registry? Initially, this can be any object that the client has no other way of finding. After that, 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 such 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 factory that returns references to all the remote objects your application uses. Depending on how you structure your application, this may happen naturally anyway.

The RMI registry is just one implementation of a lookup mechanism for remote objects. It 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. More generally, the Java Naming and Directory Interface (JNDI) is a Java API allowing access to other widely used name services that can provide this kind of functionality. JNDI is used with RMI as part of the Enterprise JavaBeans APIs.

An RMI Example

In our first example using RMI, we duplicate the simple serialized object protocol from the previous section. We make a remote RMI object called MyServer on which we can invoke methods to get a Date object or execute a WorkRequest object. First, we define our Remote interface:

    //file: ServerRemote.java
    import java.rmi.*;
    import java.util.*;
      
    public interface ServerRemote extends Remote {
        Date getDate() throws RemoteException;
        Object execute( WorkRequest work ) throws RemoteException;
    }

The ServerRemote interface extends the java.rmi.Remote interface, which identifies objects that implement it as remote objects. We supply two methods that take the place of our old protocol: getDate() and execute().

Next, we implement this interface in a class called MyServer that defines the bodies of these methods. (Another common convention for naming the implementation of remote interfaces is to append Impl to the class name. Using that convention, MyServer would instead be named something like ServerImpl.)

    //file: MyServer.java
    import java.rmi.*;
    import java.util.*;

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

        public MyServer() throws RemoteException { }

        // implement the ServerRemote interface
        public Date getDate() throws RemoteException {
            return new Date();
        }

        public Object execute( WorkRequest work )
          throws RemoteException {
            return work.execute();
        }
      
        public static void main(String args[]) {
            try {
                ServerRemote server = new MyServer();
                Naming.rebind("NiftyServer", server);
            } catch (java.io.IOException e) {
                // problem registering server
            }
        }
    }

MyServer extends UnicastRemoteObject so that when we create an instance of MyServer, it is automatically exported and starts listening to the network. We start by providing a constructor that must throw RemoteException, which accommodates errors that might occur in exporting an instance. Next, MyServer implements the methods of the remote interface ServerRemote. These methods are straightforward.

The last method in this class is main(). This method lets the object set itself up as a server. main() creates an instance of the MyServer object and then calls the static method Naming.rebind() to place the object in the registry. The arguments to rebind() include the name of the remote object in the registry (NiftyServer)—which clients use to look up the object—and a reference to the server object itself. We could have called bind() instead, but rebind() handles the case where there’s already a NiftyServer registered by replacing it.

We wouldn’t need the main() method or this Naming business if we weren’t expecting clients to use the registry to find the server—that is, we could omit main() and still use this object as a remote object. We would just be limited to passing the object in method invocations or returning it from method invocations—but that could be part of a factory pattern, as we discussed before.

Now we need our client:

    //file: MyClient.java
    import java.rmi.*;
    import java.util.*;

    public class MyClient {
      
        public static void main(String [] args)
          throws RemoteException {
            new MyClient( args[0] );
        }
      
        public MyClient(String host) {
            try {
                ServerRemote server = (ServerRemote)
                    Naming.lookup("rmi://"+host+"/NiftyServer");
                System.out.println( server.getDate() );
                System.out.println(
                  server.execute( new MyCalculation(2) ) );
            } catch (java.io.IOException e) {
                  // I/O Error or bad URL
            } catch (NotBoundException e) {
                  // NiftyServer isn't registered
            }
        }
    }

When we run MyClient, we pass it the hostname of the server on which the registry is running. The main() method creates an instance of the MyClient object, passing the hostname from the command line as an argument to the constructor.

The constructor for MyClient uses the hostname to construct a URL for the object. The URL looks like this: rmi://hostname/NiftyServer. (Remember, NiftyServer is the name under which we registered our ServerRemote.) We pass the URL to the static Naming.lookup() method. If all goes well, we get back a reference to a ServerRemote (the remote interface). The registry has no idea what kind of object it will return; lookup() therefore returns an Object, which we must cast to ServerRemote, the remote interface type.

Running the example

You can run the client and server on the same machine or on different machines. First, make sure all the classes are in your classpath (or the current directory if there is no classpath) and then start the rmiregistry and MyServer on your server host:

    % rmiregistry &(on Windows:start rmiregistry)
    %java MyServer

Next, run the client, passing the name of the server host (or “localhost” for the local machine):

    % java MyClientmyhost

The client should print the date and the number 4, which the server graciously calculated. Hooray! With just a few lines of code, you have created a powerful client/server application.

Dynamic class loading

Before running the example, we told you to distribute all of 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. This involves a few extra steps.

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 a web server (or FTP server) when we run our client or server. This URL specifies the location of a JAR file or a base directory where RMI begins its search for classes. When RMI sends a serialized object (i.e., an object’s data) to a client, it also sends this URL. If the recipient needs the class file in addition to the data, it fetches the file at the specified URL. In addition to stub classes, other classes referenced by remote objects in the application can be loaded dynamically. Therefore, we don’t have to distribute many class files to the client; we can let the client download them as necessary. In Figure 13-3, we see an example of MyClient going to the registry to get a reference to the ServerRemote object. Once there, MyClient dynamically downloads the stub class for MyServer from a web server running on the server object’s host.

We can now split our class files more logically between the server and client machines. For example, we could withhold the MyCalculation class from the server because it really belongs to the client. Instead, we can make the MyCalculation class available via a web server on some machine (probably our client’s) and specify the URL when we run MyClient:

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

The trailing slash in the codebase URL is important: it says that the location is a base directory that contains the class files. In this case, we would expect that MyCalculation would be accessible at the URL http://myserver/foo/MyCalculation.class.

Next, we have to set up security. Since we are loading class files over the network and executing their methods, we must have a security manager in place to restrict the kinds of things those classes may do, at least when they are not coming from a trusted code source. RMI will not load any classes dynamically unless a security manager is installed. One easy way to meet this condition is to install the RMISecurityManager as the system security manager for your application. It is an example security manager that works with the default system policy and imposes some basic restrictions on what downloaded classes can do. To install the RMISecurityManager, simply add the following line to the beginning of the main() method of both the client and server applications (yes, we’ll be sending code both ways in the next section):

    main() {
        System.setSecurityManager( new RMISecurityManager() );
        ...

Figure 13-3. RMI applications and dynamic class loading

The RMISecurityManager works with the system security policy file to enforce restrictions. You have to provide a policy file that allows the client and server to do basic operations like make network connections. Unfortunately, allowing all the operations needed to load classes dynamically requires listing a lot of permission information and we don’t want to get into that here. We suggest that for this example, you simply grant the code all permissions. Here is an example policy file—call it mysecurity.policy:

    grant {
       permission java.security.AllPermission ;
    };

(It’s exceedingly lame, not to mention risky, to install a security manager and then tell it to enforce no real security, but we’re more interested in looking at the networking code at the moment.)

To run our MyServer application, we would use a command such as:

    % java -Djava.rmi.server.codebase='http://myserver/foo/' \
        -Djava.security.policy=mysecurity.policy MyServer

Finally, one last trick is required to enable dynamic class loading. As of the current implementation, the rmiregistry must be run without the classes that are to be loaded in its classpath. If the classes are in the classpath of rmiregistry, it does not annotate the serialized objects with the URLs of their class files, and no classes are dynamically loaded. This limitation is really annoying; all we can say is to heed the warning for now.

If you follow these directions, you should be able to run our client with only the MyClient class and the ServerRemote remote interface in its classpath. All the other classes are loaded dynamically from the specified server as needed.

Passing remote object references

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

    public interface ServerRemote extends Remote {
        ...
        StringIterator getList() throws RemoteException;
        void asyncExecute( WorkRequest work, WorkListener
        listener )
            throws RemoteException;
    }

getList() retrieves a new kind of object from the server: a StringIterator. The StringIterator we’ve created is a simple list of strings with some methods for accessing the strings in order. We make it a remote object so that implementations of StringIterator stay on the server.

Next, we 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 calculation on its own time. The return type for asyncExecute() is void because it doesn’t actually return a value; we get the result later. Along 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:

    //file: StringIterator.java
    import java.rmi.*;

    public interface StringIterator extends Remote {
        public boolean hasNext() throws RemoteException;
        public String next() throws RemoteException;
    }

Next, we provide a simple implementation of StringIterator, called MyStringIterator:

    //file: MyStringIterator.java
    import java.rmi.*;

    public class MyStringIterator
      extends java.rmi.server.UnicastRemoteObject
      implements StringIterator {
      
        String [] list;
        int index = 0;

        public MyStringIterator( String [] list )
          throws RemoteException {
            this.list = list;
        }
        public boolean hasNext() throws RemoteException {
            return index < list.length;
        }
        public String next() throws RemoteException {
            return list[index++];
        }
    }

MyStringIterator extends UnicastRemoteObject. Its methods are simple: it can give you the next string in the list, and it can tell you if there are any strings you haven’t seen yet.

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

    //file: WorkListener.java
    import java.rmi.*;

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

Let’s add the new features to MyServer. We need to add implementations of the getList() and asyncExecute() methods, which we just added to the ServerRemote interface:

    public class MyServer extends java.rmi.server.UnicastRemoteObject
                          implements ServerRemote {
      ...
      public StringIterator getList() throws RemoteException {
        return new MyStringIterator(
            new String [] { "Foo", "Bar", "Gee" } );
      }

      public void asyncExecute(
         final WorkRequest request, final WorkListener listener )
         throws java.rmi.RemoteException
      {
        new Thread() {
          public void run() {
            Object result = request.execute();
            try {
              listener.workCompleted( request, result );
            } catch ( RemoteException e ) {
              System.out.println( e ); // error calling client
            }
        }}.start();
      }
    }

getList() just returns a StringIterator with some stuff in it. asyncExecute() calls a WorkRequest’s execute() method and notifies the listener when it’s done. asyncExecute() runs the request in a separate thread, allowing the remote method call to return immediately. Later, when the work is done, the server uses the client’s WorkListener interface to return the result.

We have to modify MyClient to implement the remote WorkListener interface. This turns MyClient into a remote object, so we will have it extend UnicastRemoteObject. We also add the workCompleted() method the WorkListener interface requires. Finally, we want MyClient to exercise the new features. We’ve put all of this in a new version of the client called MyClientAsync:

    //file: MyClientAsync.java
    import java.rmi.*;
    import java.util.*;
     
    public class MyClientAsync
        extends java.rmi.server.UnicastRemoteObject implements WorkListener
    {
     
        public MyClientAsync(String host) throws RemoteException
        {
            try {
                ServerRemote server = (ServerRemote)
                    Naming.lookup("rmi://"+host+"/NiftyServer");
     
                server.asyncExecute( new MyCalculation( 100 ), this );
                System.out.println("call done...");
            } catch (java.io.IOException e) {
                // I/O Error or bad URL
            } catch (NotBoundException e) {
                // NiftyServer isn't registered
            }
        }
     
        public void workCompleted( WorkRequest request, Object result )
            throws RemoteException
        {
            System.out.println("Async result: "+result );
        }
     
        public static void main(String [] args) throws RemoteException {
            new MyClientAsync( args[0] );
        }
     
    }
     

We use getList() to get the iterator from the server and 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 ourselves (this).

Restart the RMI registry and MyServer on your server, and run the client somewhere. You should get the following:

    Foo
    Bar
    Gee
    Async result = 10000

We hope that this introduction has given you a feel for the tremendous power that RMI offers through object serialization and dynamic class loading. Java is one of the first programming languages to offer this kind of powerful framework for distributed applications. Although some of the advanced features are not used widely in business applications, RMI was the underpinning for the very widely used J2EE Enterprise JavaBeans architecture and is an important technology. For more information on RMI and J2EE, see Java Enterprise in a Nutshell (O’Reilly).

RMI and CORBA

Java supports an important alternative to RMI, called CORBA (Common Object Request Broker Architecture). We won’t say much about CORBA here, but you should know that it exists. CORBA is an older distributed object standard developed by the Object Management Group (OMG), of which Sun Microsystems was one of the founding members. Its major advantage is that it works across languages: a Java program can use CORBA to talk to objects written in other languages, like C or C++. This may be a considerable advantage if you want to build a Java frontend for an older program that you can’t afford to reimplement. CORBA also provides other services similar to those in the Java Enterprise APIs. CORBA’s major disadvantages are that it’s complex, inelegant, and somewhat arcane.