A Generic Compute Engine

This page is based on the Java rmi tutorial on java.sun.com.

The compute engine server:

accepts tasks from clients
executes the tasks
returns any results, if any.

It is comprised of an interface and a class. The interface defines the client's view of the remote object, the compute server; the class provides the server's implementation.

The 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
the results of the job to be returned to the client.

This protocol is expressed in 2 interfaces, one supported by the compute engine; the other supported by the objects that are submitted to the compute engine.

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 task.

The Compute interface defines the remotely accessible part---the compute engine itself:

package compute;
import java.rmi.*;

public interface Compute extends Remote
{
Object executeTask(Task t) throws RemoteException;
}

The 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();
}

Since the interface does not extend Remote, the method in this interface doesn't need to list java.rmi.RemoteException in its throws clause.
Since the return value for the executeTask and execute methods is of type Object, any task that would return a primitive type, (e.g., int or float), must use a wrapper class (e.g., Integer or a Float).
The Task interface extends the java.io.Serializable interface because all method parameter and return values are serialized.
Implementations of the Task object are downloaded by RMI into the compute engine's virtual machine when needed.

Implementing the Compute Server

Implement the Compute interface

Declare the remote interface being implemented
Define the no-argument constructor for the remote object
Implement each remote method in the remote interface

Define a main method that

Creates and installs a security manager
Creates an instance of the remote object
Registers the remote object with the RMI remote object registry

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

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

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

    public static void main(String[] args)
    {
        if (System.getSecurityManager() == null)
        {
            System.setSecurityManager(new RMISecurityManager()); //server loads Task objects
        }
        try
        {
            Compute engine = new ComputeEngine(); // engine is a Compute not a ComputeEngine
            Naming.rebind("Compute", engine); // register compute server on this machine
            System.out.println("ComputeEngine bound");
        }
        catch (Exception e)
        {
            System.err.println("ComputeEngine exception: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

During construction, a UnicastRemoteObject is exported: it is able to accept incoming method invocations from clients on an anonymous port.
In JDK 1.2 you can indicate a specific port that a remote object uses to accept requests.
The implementation of the executeTask method requires that clients provide a Task object, that implements the Task execute method.
The ComputeEngine returns the execute method's return value.

After the server registers with the local RMI registry, it essentially exits.

The main thread does not need to wait to keep the server alive. As long as there is a reference to the Compute object in a virtual machine, local or remote, the Compute object will be alive.
Since the program binds a reference to the Compute object in the registry, it is reachable from a remote client, the registry itself!
The ComputeEngine won't be reclaimed until its binding is removed from the registry, and no remote clients hold a remote reference to the Compute object.

Creating a Compute Client

A client needs to define the task to be performed by the compute engine.
Two classes make up the client in this example:

ComputePi, looks up and calls the Compute object (the compute engine).
Pi, implements the Task interface and defines the work to be done by the compute engine. The Pi class computes the value of to some number of decimal places, returning the result as a BigDecimal object.

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()); //client loads executeTask stub
        }
        try
        {
            String name = "//" + args[0] + "/Compute";
            Compute comp = (Compute) Naming.lookup(name);
            Pi task = new Pi(Integer.parseInt(args[1])); // Pi implements Task
           BigDecimal pi = (BigDecimal) (comp.executeTask(task));
            System.out.println(pi);
        }
        catch (Exception e)
        {
            System.err.println("ComputePi exception: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Create & Install a Security Manager

A security manager 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.
args[0] is the name of the remote host on which the Compute server runs.
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 following figure depicts the flow of messages among the ComputePi client, the rmiregistry, & the ComputeEngine.

package client;
import compute.*;
import java.math.*;

public class Pi implements Task
{
    /** constants */
    private static final BigDecimal ZERO = BigDecimal.valueOf(0);
    private static final BigDecimal ONE = BigDecimal.valueOf(1);
    private static final BigDecimal FOUR = BigDecimal.valueOf(4);
    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)
     *
     * & 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 Compute object needs Pi's class definition only when a Pi object is passed as an argument to the executeTask method.
Then:

the code for the class is loaded by RMI into the Compute object's virtual machine
the execute method is invoked.

The resulting java.math.BigDecimal object, is returned to the client.
The Compute server 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.