Java Remote Method Invocation

The following material is collected from http://java.sun.com/.

An Overview of RMI Applications

RMI applications are often comprised of two separate programs: a server and a client. A typical server application creates some remote objects, makes references to them accessible, and waits for clients to invoke methods on these remote objects. A typical client application gets a remote reference to one or more remote objects in the server and then invokes methods on them. RMI provides the mechanism by which the server and the client communicate and pass information back and forth. Such an application is sometimes referred to as a distributed object application.
Distributed object applications need to

Locate remote objects: Applications can use one of two mechanisms to obtain references to remote objects. An application can register its remote objects with RMI's simple naming facility, the rmiregistry, or the application can pass and return remote object references as part of its normal operation.
Communicate with remote objects: Details of communication between remote objects are handled by RMI; to the programmer, remote communication looks like a standard Java method invocation.
Load class bytecodes for objects that are passed around: Because RMI allows a caller to pass objects to remote objects, RMI provides the necessary mechanisms for loading an object's code, as well as for transmitting its data.
The following illustration depicts an RMI distributed application that uses the registry to obtain a reference to a remote object. The server calls the registry to associate (or bind) a name with a remote object. The client looks up the remote object by its name in the server's registry and then invokes a method on it. The illustration also shows that the RMI system uses an existing Web server to load class bytecodes, from server to client and from client to server, for objects when needed.

This lesson contains the following sections:

Advantages of Dynamic Code Loading
Remote Interfaces, Objects, and Methods
Creating Distributed Applications Using RMI
Building a Generic Compute Engine

Advantages of Dynamic Code Loading

One of the central and unique features of RMI is its ability to download the bytecodes (or simply code) of an object's class if the class is not defined in the receiver's virtual machine. The types and the behavior of an object, previously available only in a single virtual machine, can be transmitted to another, possibly remote, virtual machine. RMI passes objects by their true type, so the behavior of those objects is not changed when they are sent to another virtual machine. This allows new types to be introduced into a remote virtual machine, thus extending the behavior of an application dynamically. The compute engine example in this chapter uses RMI's capability to introduce new behavior to a distributed program.

Remote Interfaces, Objects, and Methods

Like any other application, a distributed application built using Java RMI is made up of interfaces and classes. The interfaces define methods, and the classes implement the methods defined in the interfaces and, perhaps, define additional methods as well. In a distributed application some of the implementations are assumed to reside in different virtual machines. Objects that have methods that can be called across virtual machines are remote objects.
An object becomes remote by implementing a remote interface, which has the following characteristics.

A remote interface extends the interface java.rmi.Remote.
Each method of the interface declares java.rmi.RemoteException in its throws clause, in addition to any application-specific exceptions.

RMI treats a remote object differently from a nonremote object when the object is passed from one virtual machine to another. Rather than making a copy of the implementation object in the receiving virtual machine, RMI passes a remote stub for a remote object. The stub acts as the local representative, or proxy, for the remote object and basically is, to the caller, the remote reference. The caller invokes a method on the local stub, which is responsible for carrying out the method call on the remote object.
A stub for a remote object implements the same set of remote interfaces that the remote object implements. This allows a stub to be cast to any of the interfaces that the remote object implements. However, this also means that only those methods defined in a remote interface are available to be called in the receiving virtual machine.

Creating Distributed Applications Using RMI

When you use RMI to develop a distributed application, you follow these general steps.

Design and implement the components of your distributed application.
Compile sources and generate stubs.
Make classes network accessible.
Start the application.

Design and Implement the Application Components

First, decide on your application architecture and determine which components are local objects and which ones should be remotely accessible. This step includes:

Defining the remote interfaces: A remote interface specifies the methods that can be invoked remotely by a client. Clients program to remote interfaces, not to the implementation classes of those interfaces. Part of the design of such interfaces is the determination of any local objects that will be used as parameters and return values for these methods; if any of these interfaces or classes do not yet exist, you need to define them as well.
Implementing the remote objects: Remote objects must implement one or more remote interfaces. The remote object class may include implementations of other interfaces (either local or remote) and other methods (which are available only locally). If any local classes are to be used as parameters or return values to any of these methods, they must be implemented as well.
Implementing the clients: Clients that use remote objects can be implemented at any time after the remote interfaces are defined, including after the remote objects have been deployed.

Compile Sources and Generate Stubs

This is a two-step process. In the first step you use the javac compiler to compile the source files, which contain the implementation of the remote interfaces and implementations, the server classes, and the client classes. In the second step you use the rmic compiler to create stubs for the remote objects. RMI uses a remote object's stub class as a proxy in clients so that clients can communicate with a particular remote object.

Make Classes Network Accessible

In this step you make everything--the class files associated with the remote interfaces, stubs, and other classes that need to be downloaded to clients--accessible via a Web server.

Start the Application

Starting the application includes running the RMI remote object registry, the server, and the client.
The rest of this lesson walks through the steps to create a compute engine.

Building a Generic Compute Engine

This trail focuses on a simple yet powerful distributed application called a compute engine. The compute engine, a remote object in the server, takes tasks from clients, runs them, and returns any results. The tasks are run on the machine where the server is running. This sort of distributed application could allow a number of client machines to make use of a particularly powerful machine or one that has specialized hardware.
The novel aspect of the compute engine is that the tasks it runs do not need to be defined when the compute engine is written. New kinds of tasks can be created at any time and then given to the compute engine to be run. All that is required of a task is that its class implement a particular interface. Such a task can be submitted to the compute engine and run, even if the class that defines that task was written long after the compute engine was written and started. The code needed to accomplish the task can be downloaded by the RMI system to the compute engine, and then the engine runs the task, using the resources on the machine on which the compute engine is running.
The ability to perform arbitrary tasks is enabled by the dynamic nature of the Java platform, which is extended to the network by RMI. RMI dynamically loads the task code into the compute engine's Java virtual machine and runs the task without prior knowledge of the class that implements the task. An application like this, which has the ability to download code dynamically, is often called a behavior-based application. Such applications usually require full agent-enabled infrastructures. With RMI such applications are part of the basic mechanisms for distributed computing on the Java platform.

Writing an RMI Server

The compute engine server accepts tasks from clients, runs the tasks, and returns any results. The server is comprised of an interface and a class. The interface provides the definition for the methods that can be called from the client. Essentially the interface defines the client's view of the remote object. The class provides the implementation.
Designing a Remote Interface
This section shows you the Compute interface, which provides the connection between the client and the server. You will also learn about the RMI API, which supports this communication.

Implementing a Remote Interface
This section explores the class that implements the Compute interface, thereby implementing a remote object. This class also provides the rest of the code that makes up the server program: a main method that creates an instance of the remote object, registers it with the naming facility, and sets up a security manager.

Designing a Remote Interface

At the heart of the compute engine is a protocol that allows jobs to be submitted to the compute engine, the compute engine to run those jobs, and the results of the job to be returned to the client. This protocol is expressed in interfaces supported by the compute engine and by the objects that are submitted to the compute engine, as shown in the following figure.

Each of the interfaces contains a single method. The compute engine's interface, Compute, allows jobs to be submitted to the engine; the client interface, Task, defines how the compute engine executes a submitted task.
The compute.Compute interface defines the remotely accessible part--the compute engine itself. Here is the remote interface with its single method:
package compute;

import java.rmi.Remote;
import java.rmi.RemoteException;

public interface Compute extends Remote {
    Object executeTask(Task t) throws RemoteException;
}
By extending the interface java.rmi.Remote, this interface marks itself as one whose methods can be called from any virtual machine. Any object that implements this interface becomes a remote object.
As a member of a remote interface, the executeTask method is a remote method. Therefore the method must be defined as being capable of throwing a java.rmi.RemoteException. This exception is thrown by the RMI system during a remote method call to indicate that either a communication failure or a protocol error has occurred. A RemoteException is a checked exception, so any code making a call to a remote method needs to handle this exception by either catching it or declaring it in its throws clause.
The second interface needed for the compute engine defines the type Task. This type is used as the argument to the executeTask method in the Compute interface. The compute.Task interface defines the interface between the compute engine and the work that it needs to do, providing the way to start the work.
package compute;

import java.io.Serializable;

public interface Task extends Serializable {
    Object execute();
}
The Task interface defines a single method, execute, which returns an Object, has no parameters, and throws no exceptions. Since the interface does not extend Remote, the method in this interface doesn't need to list java.rmi.RemoteException in its throws clause.
The return value for the Compute's executeTask and Task's execute methods is declared to be of type Object. This means that any task that wants to return a value of one of the primitive types, such as an int or a float, needs to create an instance of the equivalent wrapper class for that type, such as an Integer or a Float, and return that object instead.
Note that the Task interface extends the java.io.Serializable interface. RMI uses the object serialization mechanism to transport objects by value between Java virtual machines. Implementing Serializable marks the class as being capable of conversion into a self-describing byte stream that can be used to reconstruct an exact copy of the serialized object when the object is read back from the stream.
Different kinds of tasks can be run by a Compute object as long as they are implementations of the Task type. The classes that implement this interface can contain any data needed for the computation of the task and any other methods needed for the computation.
Here is how RMI makes this simple compute engine possible. Since RMI can assume that the Task objects are written in the Java programming language, implementations of the Task object that were previously unknown to the compute engine are downloaded by RMI into the compute engine's virtual machine as needed. This allows clients of the compute engine to define new kinds of tasks to be run on the server machine without needing the code to be explicitly installed on that machine. In addition, because the executeTask method returns a java.lang.Object, any type of object can be passed as a return value in the remote call.
The compute engine, implemented by the ComputeEngine class, implements the Compute interface, allowing different tasks to be submitted to it by calls to its executeTask method. These tasks are run using the task's implementation of the execute method. The compute engine reports results to the caller through its return value: an Object.

Implementing a Remote Interface

Let's turn now to the task of implementing a class for the compute engine. In general the implementation class of a remote interface should at least

Declare the remote interfaces being implemented
Define the constructor for the remote object
Provide an implementation for each remote method in the remote interfaces

The server needs to create and to install the remote objects. This setup procedure can be encapsulated in a main method in the remote object implementation class itself, or it can be included in another class entirely. The setup procedure should

Create and install a security manager
Create one or more instances of a remote object
Register at least one of the remote objects with the RMI remote object registry (or another naming service such as one that uses JNDI), for bootstrapping purposes

The complete implementation of the compute engine follows. The engine.ComputeEngine class implements the remote interface Compute and also includes the main method for setting up the compute engine.
package engine;

import java.rmi.*;
import java.rmi.server.*;
import compute.*;

public class ComputeEngine extends UnicastRemoteObject
                           implements Compute
{
    public ComputeEngine() throws RemoteException {
        super();
    }

    public Object executeTask(Task t) {
        return t.execute();
    }

    public static void main(String[] args) {
        if (System.getSecurityManager() == null) {
            System.setSecurityManager(new RMISecurityManager());
        }
        String name = "//host/Compute";
        try {
            Compute engine = new ComputeEngine();
            Naming.rebind(name, engine);
            System.out.println("ComputeEngine bound");
        } catch (Exception e) {
            System.err.println("ComputeEngine exception: " + 
			       e.getMessage());
            e.printStackTrace();
        }
    }
}
Now let's take a closer look at each of the components of the compute engine implementation.

Declare the Remote Interfaces Being Implemented

The implementation class for the compute engine is declared as
public class ComputeEngine extends UnicastRemoteObject
                           implements Compute
This declaration states that the class implements the Compute remote interface (and therefore defines a remote object) and extends the class java.rmi.server.UnicastRemoteObject.
UnicastRemoteObject is a convenience class, defined in the RMI public API, that can be used as a superclass for remote object implementations. The superclass UnicastRemoteObject supplies implementations for a number of java.lang.Object methods (equals, hashCode, toString) so that they are defined appropriately for remote objects. UnicastRemoteObjectalso includes constructors and static methods used to export a remote object, that is, make the remote object available to receive incoming calls from clients.
A remote object implementation does not have to extend UnicastRemoteObject, but any implementation that does not must supply appropriate implementations of the java.lang.Object methods. Furthermore, a remote object implementation must make an explicit call to one of UnicastRemoteObject's exportObject methods to make the RMI runtime aware of the remote object so that the object can accept incoming calls. By extending UnicastRemoteObject, the ComputeEngine class can be used to create a simple remote object that supports unicast (point-to-point) remote communication and that uses RMI's default sockets-based transport for communication.
If you choose to extend a remote object from any class other than Unicast-RemoteObject or, alternatively, extend from the new JDK 1.2 class java.rmi.activation.Activatable (used to construct remote objects that can execute on demand), you need to export the remote object by calling either the UnicastRemoteObject.exportObject or Activatable.exportObject method explicitly from your class's constructor (or another initialization method, as appropriate).
The compute engine example defines a remote object class that implements only a single remote interface and no other interfaces. The ComputeEngine class also contains some methods that can be called only locally. The first of these is a constructor for ComputeEngine objects; the second is a main method that is used to create a ComputeEngine and make it available to clients.

Define the Constructor

The ComputeEngine class has a single constructor that takes no arguments. The code for the constructor is
public ComputeEngine() throws RemoteException {
    super();
}
This constructor simply calls the superclass constructor, which is the no-argument constructor of the UnicastRemoteObject class. Although the superclass constructor gets called even if omitted from the ComputeEngine constructor, we include it for clarity.
During construction, a UnicastRemoteObject is exported, meaning that it is available to accept incoming requests by listening for incoming calls from clients on an anonymous port.

Note: In JDK 1.2 you may indicate the specific port that a remote object uses to accept requests.

The no-argument constructor for the superclass, UnicastRemoteObject, declares the exception RemoteException in its throws clause, so the Compute-Engine constructor must also declare that it can throw RemoteException. A RemoteException can occur during construction if the attempt to export the object fails--due to, for example, communication resources being unavailable or the appropriate stub class not being found.

Provide Implementations for Each Remote Method

The class for a remote object provides implementations for each of the remote methods specified in the remote interfaces. The Compute interface contains a single remote method, executeTask, which is implemented as follows:
public Object executeTask(Task t) {
    return t.execute();
}
This method implements the protocol between the ComputeEngine and its clients. Clients provide the ComputeEngine with a Task object, which has an implementation of the task's execute method. The ComputeEngine executes the Task and returns the result of the task's execute method directly to the caller.
The executeTask method does not need to know anything more about the result of the execute method than that it is at least an Object. The caller presumably knows more about the precise type of the Object returned and can cast the result to the appropriate type.
Passing Objects in RMI

Arguments to or return values from remote methods can be of almost any type, including local objects, remote objects, and primitive types. More precisely, any entity of any type can be passed to or from a remote method as long as the entity is an instance of a type that is a primitive data type, a remote object, or a serializable object, which means that it implements the interface java.io.Serializable.
A few object types do not meet any of these criteria and thus cannot be passed to or returned from a remote method. Most of these objects, such as a file descriptor, encapsulate information that makes sense only within a single address space. Many of the core classes, including those in the packages java.lang and java.util, implement the Serializable interface.
The rules governing how arguments and return values are passed are as follows.

Remote objects are essentially passed by reference. A remote object reference is a stub, which is a client-side proxy that implements the complete set of remote interfaces that the remote object implements.
Local objects are passed by copy, using object serialization. By default all fields are copied, except those that are marked static or transient. Default serialization behavior can be overridden on a class-by-class basis.

Passing an object by reference (as is done with remote objects) means that any changes made to the state of the object by remote method calls are reflected in the original remote object. When passing a remote object, only those interfaces that are remote interfaces are available to the receiver; any methods defined in the implementation class or defined in nonremote interfaces implemented by the class are not available to that receiver.
For example, if you were to pass a reference to an instance of the ComputeEngine class, the receiver would have access only to the compute engine's executeTask method. That receiver would not see either the ComputeEngine constructor or its main method or any of the methods in java.lang.Object.
In remote method calls objects--parameters, return values, and exceptions--that are not remote objects are passed by value. This means that a copy of the object is created in the receiving virtual machine. Any changes to this object's state at the receiver are reflected only in the receiver's copy, not in the original instance.

Implement the Server's main Method

The most involved method of the ComputeEngine implementation is the main method. The main method is used to start the ComputeEngine and therefore needs to do the necessary initialization and housekeeping to prepare the server for accepting calls from clients. This method is not a remote method, which means that it cannot be called from a different virtual machine. Since the main method is declared static, the method is not associated with an object at all but rather with the class ComputeEngine.

Create and Install a Security Manager

The first thing that the main method does is to create and to install a security manager, which protects access to system resources from untrusted downloaded code running within the virtual machine. The security manager determines whether downloaded code has access to the local file system or can perform any other privileged operations.
All programs using RMI must install a security manager, or RMI will not download classes (other than from the local class path) for objects received as parameters, return values, or exceptions in remote method calls. This restriction ensures that the operations performed by downloaded code go through a set of security checks.
The ComputeEngine uses a security manager supplied as part of the RMI system, the RMISecurityManager. This security manager enforces a similar security policy as the typical security manager for applets; that is to say, it is very conservative as to what access it allows. An RMI application could define and use another SecurityManager class that gave more liberal access to system resources or, in JDK 1.2, use a policy file that grants more permissions.
Here's the code that creates and installs the security manager:
if (System.getSecurityManager() == null) {
    System.setSecurityManager(new RMISecurityManager());
}

Make the Remote Object Available to Clients

Next, the main method creates an instance of the ComputeEngine. This is done with the statement
Compute engine = new ComputeEngine();
As mentioned, this constructor calls the UnicastRemoteObject superclass constructor, which in turn exports the newly created object to the RMI runtime. Once the export step is complete, the ComputeEngine remote object is ready to accept incoming calls from clients on an anonymous port, one chosen by RMI or the underlying operating system. Note that the type of the variable engine is Compute, not ComputeEngine. This declaration emphasizes that the interface available to clients is the Compute interface and its methods, not the Compute-Engine class and its methods.
Before a caller can invoke a method on a remote object, that caller must first obtain a reference to the remote object. This can be done in the same way that any other object reference is obtained in a program, such as getting it as part of the return value of a method or as part of a data structure that contains such a reference.
The system provides a particular remote object, the RMI registry, for finding references to remote objects. The RMI registry is a simple remote object name service that allows remote clients to get a reference to a remote object by name. The registry is typically used only to locate the first remote object an RMI client needs to use. That first remote object then provides support for finding other objects.
The java.rmi.Naming interface is used as a front-end API for binding, or registering, and looking up remote objects in the registry. Once a remote object is registered with the RMI registry on the local host, callers on any host can look up the remote object by name, obtain its reference, and then invoke remote methods on the object. The registry may be shared by all servers running on a host, or an individual server process may create and use its own registry, if desired.
The ComputeEngine class creates a name for the object with the statement
String name = "//host/Compute";
This name includes the host name, host, on which the registry (and remote object) is being run and a name, Compute, that identifies the remote object in the registry. The code then needs to add the name to the RMI registry running on the server. This is done later (within the try block) with the statement
Naming.rebind(name, engine);
Calling the rebind method makes a remote call to the RMI registry on the local host. This call can result in a RemoteException being generated, so the exception needs to be handled. The ComputeEngine class handles the exception within the try/catch block. If the exception is not handled in this way, RemoteException would have to be added to the throws clause (currently nonexistent) of the main method.
Note the following about the arguments to the call to Naming.rebind.

The first parameter is a URL-formatted java.lang.String representing the location and the name of the remote object. You will need to change the value of host to be the name, or IP address, of your server machine. If the host is omitted from the URL, the host defaults to the local host. Also, you don't need to specify a protocol in the URL. For example, supplying Compute as the name in the Naming.rebind call is allowed. Optionally a port number may be supplied in the URL; for example, the name //host:1234/objectname is legal. If the port is omitted, it defaults to 1099. You must specify the port number only if a server creates a registry on a port other than the default 1099. The default port is useful in that it provides a well-known place to look for the remote objects that offer services on a particular host.
The RMI runtime substitutes a reference to the stub for the remote object reference specified by the argument. Remote implementation objects, such as instances of ComputeEngine, never leave the VM where they are created, so when a client performs a lookup in a server's remote object registry, a reference to the stub is returned. As discussed earlier, remote objects in such cases are passed by reference rather than by value.
Note that for security reasons, an application can bind, unbind, or rebind remote object references only with a registry running on the same host. This restriction prevents a remote client from removing or overwriting any of the entries in a server's registry. A lookup, however, can be requested from any host, local or remote.

Once the server has registered with the local RMI registry, it prints out a message indicating that it's ready to start handling calls and then the main method exits. It is not necessary to have a thread wait to keep the server alive. As long as there is a reference to the ComputeEngine object in another virtual machine, local or remote, the ComputeEngine object will not be shut down, or garbage collected. Because the program binds a reference to the ComputeEngine in the registry, it is reachable from a remote client, the registry itself! The RMI system takes care of keeping the ComputeEngine's process up. The ComputeEngine is available to accept calls and won't be reclaimed until its binding is removed from the registry, and no remote clients hold a remote reference to the ComputeEngine object.
The final piece of code in the ComputeEngine.main method deals with handling any exception that might arise. The only exception that could be thrown in the code is a RemoteException, thrown either by the constructor of the ComputeEngine class or by the call to the RMI registry to bind the object to the name Compute. In either case the program can't do much more than exit after printing an error message. In some distributed applications it is possible to recover from the failure to make a remote call. For example, the application could choose another server and continue operation.

Creating a Client Program

The compute engine is a pretty simple program: it runs tasks that are handed to it. The clients for the compute engine are more complex. A client needs to call the compute engine, but it also has to define the task to be performed by the compute engine.
Two separate classes make up the client in our example. The first class, ComputePi, looks up and calls a Compute object. The second class, Pi, implements the Task interface and defines the work to be done by the compute engine. The job of the Pi class is to compute the value of to some number of decimal places.
As you recall, the nonremote Task interface is defined as follows:
package compute;

public interface Task extends java.io.Serializable {
    Object execute();
}
The Task interface extends java.io.Serializable so that an object that implements the interface can be serialized by the RMI runtime and sent to a remote virtual machine as part of a remote method invocation. We could have chosen to have our implementation classes implement both the Task interface and the Serializable interface and gotten the same effect. However, the whole purpose of the Task interface is to allow implementations of that interface to be passed to a Compute object, so having a class that implements the Task interface that does not also implement the Serializable interface doesn't make sense. Therefore we associate the two interfaces explicitly in the type system, ensuring that all Task objects are serializable.
The code that calls a Compute object's methods must obtain a reference to that object, create a Task object, and then request that the task be executed. The definition of the task Pi is shown later. A Pi object is constructed with a single argument, the desired precision of the result. The result of the task execution is a java.math.BigDecimal representing calculated to the specified precision.
The client class client.ComputePi is as follows.
package client;

import java.rmi.*;
import java.math.*;
import compute.*;

public class ComputePi {
    public static void main(String args[]) {
        if (System.getSecurityManager() == null) {
            System.setSecurityManager(new RMISecurityManager());
        }
        try {
            String name = "//" + args[0] + "/Compute";
            Compute comp = (Compute) Naming.lookup(name);
            Pi task = new Pi(Integer.parseInt(args[1]));
            BigDecimal pi = (BigDecimal) (comp.executeTask(task));
            System.out.println(pi);
        } catch (Exception e) {
            System.err.println("ComputePi exception: " + 
                               e.getMessage());
            e.printStackTrace();
        }
    }
}
Like the ComputeEngine server, the client begins by installing a security manager. This is necessary because RMI could be downloading code to the client. In this example the ComputeEngine's stub is downloaded to the client. Any time code is downloaded by RMI, a security manager must be present. As with the server, the client uses the security manager provided by the RMI system for this purpose.
After installing a security manager, the client constructs a name used to look up a Compute remote object. The value of the first command line argument, args[0], is the name of the remote host on which the Compute object runs. The client uses the Naming.lookup method to look up the remote object by name in the remote host's registry. When doing the name lookup, the code creates a URL that specifies the host where the compute server is running. The name passed in the Naming.lookup call has the same URL syntax as the name passed in the Naming.rebind call, which was discussed earlier.
Next, the client creates a new Pi object, passing to the Pi constructor the second command line argument, args[1], which indicates the number of decimal places to use in the calculation. Finally, the client invokes the executeTask method of the Compute remote object. The object passed into the executeTask call returns an object of type java.math.BigDecimal, so the program casts the result to that type and stores the return value in the variable result. Then, the program prints out the result. The following figure depicts the flow of messages among the ComputePi client, the rmiregistry, and the ComputeEngine.

Finally, let's look at the reason for all of this in the first place: the Pi class. This class implements the Task interface and computes the value of to a specified number of decimal places. For this example the actual algorithm is unimportant except, of course, for the accuracy of the computation. All that is important is that the computation is numerically rather expensive and thus the sort of thing that you would want to have occur on a more capable server.
Here is the code for the class client.Pi, which implements Task.
package client;

import compute.*;
import java.math.*;

public class Pi implements Task {

    /** constants used in pi computation */
    private static final BigDecimal ZERO = 
        BigDecimal.valueOf(0);
    private static final BigDecimal  ONE = 
        BigDecimal.valueOf(1);
    private static final BigDecimal FOUR = 
        BigDecimal.valueOf(4);

    /** rounding mode to use during pi computation */
    private static final int roundingMode = 
        BigDecimal.ROUND_HALF_EVEN;

    /** digits of precision after the decimal point */
    private int digits;
    
    /**
     * Construct a task to calculate pi to the specified
     * precision.
     */
    public Pi(int digits) {
        this.digits = digits;
    }

    /**
     * Calculate pi.
     */
    public Object execute() {
        return computePi(digits);
    }

    /**
     * Compute the value of pi to the specified number of 
     * digits after the decimal point.  The value is 
     * computed using Machin's formula:
     *
     *          pi/4 = 4*arctan(1/5) - arctan(1/239)
     *
     * and a power series expansion of arctan(x) to 
     * sufficient precision.
     */
    public static BigDecimal computePi(int digits) {
        int scale = digits + 5;
        BigDecimal arctan1_5 = arctan(5, scale);
        BigDecimal arctan1_239 = arctan(239, scale);
        BigDecimal pi = arctan1_5.multiply(FOUR).subtract(
                                  arctan1_239).multiply(FOUR);
        return pi.setScale(digits, 
                           BigDecimal.ROUND_HALF_UP);
    }
    /**
     * Compute the value, in radians, of the arctangent of 
     * the inverse of the supplied integer to the speficied
     * number of digits after the decimal point.  The value
     * is computed using the power series expansion for the
     * arc tangent:
     *
     * arctan(x) = x - (x^3)/3 + (x^5)/5 - (x^7)/7 + 
     *     (x^9)/9 ...
     */   
    public static BigDecimal arctan(int inverseX, 
                                  int scale) 
    {
        BigDecimal result, numer, term;
        BigDecimal invX = BigDecimal.valueOf(inverseX);
        BigDecimal invX2 = 
            BigDecimal.valueOf(inverseX * inverseX);

        numer = ONE.divide(invX, scale, roundingMode);

        result = numer;
        int i = 1;
        do {
            numer = 
                numer.divide(invX2, scale, roundingMode);
            int denom = 2 * i + 1;
            term = 
                numer.divide(BigDecimal.valueOf(denom),
                             scale, roundingMode);
            if ((i % 2) != 0) {
                result = result.subtract(term);
            } else {
                result = result.add(term);
            }
            i++;
        } while (term.compareTo(ZERO) != 0);
        return result;
    }
}
The most interesting feature of this example is that the Compute object never needs Pi's class definition until a Pi object is passed in as an argument to the executeTask method. At that point the code for the class is loaded by RMI into the Compute object's virtual machine, the execute method is called, and the task's code is executed. The resulting Object, which in the case of the Pi task is a java.math.BigDecimal object, is handed back to the calling client, where it is used to print out the result of the calculation.
The fact that the supplied Task object computes the value of Pi is irrelevant to the ComputeEngine object. You could also implement a task that, for example, generated a random prime number by using a probabilistic algorithm. That would also be numerically intensive and therefore a candidate for being shipped over to the ComputeEngine, but it would involve very different code. This code could also be downloaded when the Task object was passed to a Compute object. In just the way that the algorithm for computing Pi is brought in when needed, the code that generates the random prime would be brought in when needed. The Compute object knows only that each object it receives implements the execute method; it does not know, and does not need to know, what the implementation does.

Compiling the Example Programs

In a real-world scenario in which a service like the compute engine is deployed, a developer would likely create a JAR (Java ARchive) file that contains the Compute and Task interfaces for server classes to implement and client program to use. Next, a developer, perhaps the same developer of the interface JAR file, would write an implementation of the Compute interface and deploy that service on a machine available to clients. Developers of client programs can use the Compute and the Task interfaces, contained in the JAR file, and independently develop a task and client program that uses a Compute service.
In this section you learn how to set up the JAR file, server classes, and client classes. You will see that the client's Pi class will be downloaded to the server at runtime. Also, the ComputeEngine's remote stub will be downloaded from the server to the client at runtime.
The example separates the interfaces, remote object implementation, and client code into three packages:

compute ( Compute and Task interfaces)
engine ( ComputeEngine implementation class and its stub)
client ( ComputePi client code and Pi task implementation)

Let's first build the interface JAR file to provide to server and client developers.

Build a JAR File of Interface Classes

First, you need to compile the interface source files in the compute package and then build a JAR file that contains their class files. Let's suppose a user, waldo, has written these particular interfaces and has placed the source files in c:\home\waldo\src\compute (on UNIX:/home/waldo/src/compute). Given these paths, you can use the following commands to compile the interfaces and create the JAR file.
Win32:
cd c:\home\waldo\src
javac compute\Compute.java
javac compute\Task.java
jar cvf compute.jar compute\*.class
UNIX:
cd /home/waldo/src
javac compute/Compute.java
javac compute/Task.java
jar cvf compute.jar compute/*.class
The jar command displays the following output (due to the -v option):
added manifest
adding: compute/Compute.class (in=281) (out=196)
    	(deflated 30%)
adding: compute/Task.class (in=200) (out=164)
    	(deflated 18%)
Now you can distribute the compute.jar file to developers of server and client applications so that they can make use of the interfaces.
When you build either server- or client-side classes with the javac and rmic compilers, you generally need to specify where the resulting class files should reside so that they are network accessible. In this example this location is, for UNIX, /home/user/public_html/classes, because some web servers allow accessing a user's public_html directory via an HTTP URL constructed as http://host/~user/. If your web server does not support this convention, you could use a file URL instead. The file URLs take the form file:/home/user/public_html/classes/ on UNIX or, on the Win32 platform, file:/c:/home/user/public_html/classes/. You may also select another type of URL, as appropriate.
The network accessibility of the class files allows the RMI runtime to download code when needed. Rather than defining its own protocol for code downloading, RMI uses URL protocols supported by the Java platform (for example, HTTP) to download code. Note that a full, heavyweight web server is not needed to accomplish this downloading of class files. In fact, a simple HTTP server that provides all of the functionality needed to make classes available for downloading in RMI via HTTP can be found at ftp://ftp.javasoft.com/pub/jdk1.1/rmi/class-server.zip.

Build the Server Classes

The engine package contains only one server-side implementation class, Com-puteEngine, the remote object implementation of the Compute interface. Since ComputeEngine is an implementation of a remote interface, you need to generate a stub for the remote object so that clients can contact the remote object.
Let's say that ann, the developer of the ComputeEngine class, has placed ComputeEngine.java in the c:\home\ann\src\engine directory and is deploying the class files for clients to use in a subdirectory of her public_html directory, c:\home\ann\public_html\classes (on UNIX that would be /home/ann/public_html/classes, accessible via some web servers as http://host/~ann/classes/).
Now let's assume that the compute.jar file is located in the directory c:\home\ann\public_html\classes. To compile the ComputeEngine class, your class path must include the compute.jar file and the source directory itself.

Note: Normally we recommend that you set the class path on the command line, using the -classpath option. However, for several compounding reasons this example uses the CLASSPATH environment variable, because both javac and rmic require a class path and the -classpath option is treated differently in JDK 1.1 and JDK 1.2. For detailed information on CLASSPATH refer to:

Solaris:
http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/classpath.html

Win32:
http://java.sun.com/products/jdk/1.2/docs/tooldocs/win32/classpath.html

We recommend that you do not set CLASSPATH in a login or startup file and that you remember to unset it when you're finished working with this example.

Here's how to set the CLASSPATH environment variable
Win32:
set CLASSPATH=c:\home\ann\src;c:\home\ann\public_html\classes\compute.jar
UNIX:
setenv CLASSPATH /home/ann/src:/home/ann/public_html/classes/compute.jar
Now you compile the ComputeEngine.java source file, generate a stub for the ComputeEngine class, and make that stub network accessible. To create stub (and optionally skeleton files), run the rmic compiler on the fully qualified class names of the remote object implementations that must be found in the class path. The rmic command takes one or more class names as input and produces as output class files of the form ClassName_Stub.class and ClassName_Skel.class. A skeleton file will not be generated if you run rmic with the -v1.2 option. This option should be used only if all of your clients will be running JDK 1.2 or compatible versions.
Win32:
cd c:\home\ann\src
javac engine\ComputeEngine.java
rmic -d . engine.ComputeEngine
mkdir c:\home\ann\public_html\classes\engine
cp engine\ComputeEngine_*.class
    c:\home\ann\public_html\classes\engine
UNIX:
cd /home/ann/src
javac engine/ComputeEngine.java
rmic -d . engine.ComputeEngine
mkdir /home/ann/public_html/classes/engine
cp engine/ComputeEngine_*.class
    /home/ann/public_html/classes/engine
The -d option tells the rmic compiler to place the generated class files, ComputeEngine_Stub.class and ComputeEngine_Skel.class, in the directory c:\home\ann\src\engine. You also need to make the stubs and the skeletons network accessible, so you must copy the stub and the skeleton class to the area: public_html\classes.
Since the ComputeEngine's stub implements the Compute interface, which refers to the Task interface, you need to make these two interface class files network accessible along with the stub. So the final step is to unpack the compute.jar file in the directory c:\home\ann\public_html\classes to make the Compute and the Task interfaces available for downloading.
Win32:
cd c:\home\ann\public_html\classes
jar xvf compute.jar
UNIX:
cd /home/ann/public_html/classes
jar xvf compute.jar
The jar command displays the following output:
created: META-INF/
extracted: META-INF/MANIFEST.MF
extracted: compute/Compute.class
extracted: compute/Task.class
Now the compute engine is ready to deploy. You could do that now or wait until after you have built the client. While we are on a building spree, let's build the client-side program next.

Build the Client Classes

Let's assume that user jones has created the client code in the directory c:\home\jones\src\client and will deploy the Pi class, so that it can be downloaded to the compute engine, in the network-accessible directoryc:\home\jones\public_html\classes, also available via some web servers as http://host/~jones/classes/. The two client-side classes are contained in the files Pi.java and ComputePi.java in the client subdirectory.
In order to build the client code, you need the compute.jar file that contains the Compute and the Task interfaces that the client uses. Let's say that the compute.jar file is located in c:\home\jones\public_html\classes. The client classes can be built as follows:
Win32:
set CLASSPATH=c:\home\jones\src;c:\home\jones\public_html\classes\compute.jar
cd c:\home\jones\src
javac client\ComputePi.java
javac -d c:\home\jones\public_html\classes client\Pi.java
UNIX:
setenv CLASSPATH /home/jones/src:/home/jones/public_html/classes/compute.jar
cd /home/jones/src
javac client/ComputePi.java
javac -d /home/jones/public_html/classes client/Pi.java
Only the Pi class needs to be placed in the directory public_html\classes\ client. (The client directory is created by javac if it does not exist.) The reason is that only the Pi class needs to be available for downloading to the compute engine's virtual machine. Now you can run the server and then the client.

Running the Example Programs

A Note about Security

The JDK 1.2 security model is more sophisticated than the model used for JDK 1.1. JDK 1.2 contains enhancements for finer-grained security and requires code to be granted specific permissions to be allowed to perform certain operations.
In JDK 1.1 code in the class path is trusted and can perform any operation; downloaded code is governed by the rules of the installed security manager. If you run this example in JDK 1.2, you need to specify a policy file when you run your server and client. Here is a general policy file that allows downloaded code, from any code base, to do two things:

Connect to or accept connections on unprivileged ports (ports greater than 1024) on any host
Connect to port 80 (the port for HTTP)

Here is the code for the general policy file:
grant {
    permission java.net.SocketPermission "*:1024-65535",
        "connect,accept";
    permission java.net.SocketPermission "*:80", "connect";
};
If you make your code available for downloading via HTTP URLs, you should use the preceding policy file when you run this example. However, if you use file URLs instead, you can use the following policy file. Note that in Windows-style file names, the backslash character needs to be represented by two backslash characters in the policy file.
grant {
    permission java.net.SocketPermission "*:1024-65535",
        "connect,accept";
    permission java.io.FilePermission
        "c:\\home\\ann\\public_html\\classes\\-", "read";
    permission java.io.FilePermission
        "c:\\home\\jones\\public_html\\classes\\-", "read";
};
This example assumes that the policy file is called java.policy and that it contains the appropriate permissions. If you run this example on JDK 1.1, you will not need to use a policy file, since the RMISecurityManager provides all of the protection you need.

Start the Server

Before starting the compute engine, you need to start RMI's registry, using the rmiregistry command. As discussed earlier, the RMI registry is a simple server-side bootstrap naming facility that allows remote clients to get a reference to a remote object. Note that before you start the rmiregistry, you must make sure that the shell or window in which you will run rmiregistry either has no CLASSPATH environment variable set or has a CLASSPATH environment variable that does not include the path to any classes, including the stubs for your remote object implementation classes, that you want downloaded to clients of your remote objects.
If you do start the rmiregistry and it can find your stub classes in CLASSPATH, it will not remember that the loaded stub class can be loaded from your server's code base, specified by the java.rmi.server.codebase property when you started up your server application. Therefore, the rmiregistry will not convey to clients the true code base associated with the stub class and, consequently, your clients will not be able to locate and to load the stub class or other server-side classes.
To start the registry on the server, execute the rmiregistry command. This command produces no output and is typically run in the background. For this example, we will start the registry on the host zaphod.
Win32 (use javaw if start is not available):
unset CLASSPATH
start rmiregistry
UNIX:
unsetenv CLASSPATH
rmiregistry &
By default, the registry runs on port 1099. To start the registry on a different port, specify the port number on the command line. Do not forget to unset your CLASSPATH.
Win32:
start rmiregistry 2001
UNIX:
rmiregistry 2001 &
Once the registry is started, you can start the server. First, you need to make sure that both the compute.jar file and the remote object implementation class (since that is what you are starting) are in your class path.
Win32:
set CLASSPATH=c:\home\ann\src;c:\home\ann\public_html\classes\compute.jar
UNIX:
setenv CLASSPATH /home/ann/src:/home/ann/public_html/classes/compute.jar
When you start the compute engine, you need to specify, using the java.rmi.server.codebase property, where the server's classes will be made available. In this example the server-side classes to be made available for downloading are the ComputeEngine's stub and the Compute and the Task interfaces, available in ann's public_html\classes directory. Here, we start the compute engine server on the host zaphod, the same host where we started the registry.
Win32:
java -Djava.rmi.server.codebase=file:/c:\home\ann\public_html\classes/
     -Djava.rmi.server.hostname=zaphod.east.sun.com
     -Djava.security.policy=java.policy
        engine.ComputeEngine
UNIX:
java -Djava.rmi.server.codebase=http://zaphod/~ann/classes/
     -Djava.rmi.server.hostname=zaphod.east.sun.com
     -Djava.security.policy=java.policy
        engine.ComputeEngine
The preceding java command defines several properties.

The java.rmi.server.codebase property specifies the location, a code base URL, of classes originating from this server so that class information for objects sent to other virtual machines will include the location of the class so that a receiver can load it. If the code base specifies a directory (as opposed to a JAR file), you must include the trailing slash in the code base URL.
The java.rmi.server.hostname property indicates the fully qualified host name of your server. In some networked environments a fully qualified host name is not obtainable by using the Java APIs. RMI makes a best-effort attempt to obtain the fully qualified host name. If one cannot be determined, it will fall back and use the IP address. To ensure that RMI will use a host name that is usable from potential clients, you may want to set the java.rmi.server.hostname property as a safety measure.
The java.security.policy property is used to specify the policy file that contains the permissions you intend to grant specific code bases.

The ComputeEngine's stub class is dynamically loaded into a client's virtual machine only when the class is not already available locally and the java.rmi.server.codebas e property has been set properly, to the network-accessible location of the stub class, when the server is started. Once such a stub is loaded, it will not need to be reloaded for additional references to Com-puteEngine's objects.

Start the Client

Once the registry and the engine are running, you can start the client, specifying

The location where the client serves up its classes (the Pi class), using the java.rmi.server.codebase property
As command line arguments the host name of the server--so that the client knows where to locate the Compute remote object--and the number of decimal places to use in the calculation
The java.security.policy property, used to specify the policy file that contains the permissions you intend to grant specific code bases

First, set the CLASSPATH to see jones's client and the JAR file containing the interfaces. Then start the client on another host (one named ford, for example) as follows:
Win32:
set CLASSPATH c:\home\jones\src;c:\home\jones\public_html\classes\compute.jar
java -Djava.rmi.server.codebase=file:/c:\home\jones\public_html\classes/
     -Djava.security.policy=java.policy
	client.ComputePi zaphod.east.sun.com 20
UNIX:
setenv CLASSPATH /home/jones/src:/home/jones/public_html/classes/compute.jar
java -Djava.rmi.server.codebase=http://ford/~jones/classes/
     -Djava.security.policy=java.policy 
        client.ComputePi zaphod.east.sun.com 20
Note that the class path is set on the command line so that the interpreter can find jones's client and the JAR file containing the interfaces.
After starting the client, you should see the following output on your display:
3.14159265358979323846
The following figure illustrates where the rmiregistry, the ComputeEngine server, and the ComputePi client obtain classes during program execution.
When the ComputeEngine server binds its remote object reference in the registry, the registry downloads the ComputeEngine_Stub, as well as the Compute and the Task interfaces on which the stub class depends. These classes are downloaded from the ComputeEngine's web server or file system, as the case may be.
The ComputePi client loads the ComputeEngine_Stub, also from the Compute-Engine's web server, as a result of the Naming.lookup call. Since the ComputePi client has both the Compute and the Task interfaces available in its class path, those classes are loaded from the class path, not the remote location.

Finally, the Pi class is loaded into the ComputeEngine's virtual machine when the Pi object is passed in the executeTask remote call to the ComputeEngine object. The Pi class is loaded from the client's web server.

Start of Tutorial > Start of Trail