Callbacks which work correctly when the callback object is local—i.e. before RMI is introduced—can encounter deadlocks when the callback object is remote.

To demonstrate this problem, consider what happens in Example 12.2 if both the run and the callback methods in the CallbackClient class are synchronized.

When receiver is a remote object, such an implementation of the callback pattern will encounter a deadlock. The reason is that if receiver is a local object, the callback method is called on the same thread as the run method, and therefore no deadlock arises. If receiver is remote, RMI calls the callback method on a new thread created in receiver to deal with incoming calls. This thread blocks on trying to enter the synchronized callback method, because the original thread is still waiting inside the synchronized run method—so a deadlock occurs.

The same thing can happen more indirectly, if the callback object is separate from the calling object but eventually attempts to synchronize on the calling object.

For reasons discussed in Chapter 15, clients behind Internet firewalls cannot export RMI servers visible outside the firewall. This means that callbacks can only be used in the server-to-client direction. The server can send a callback to the client as a result, but the client can't send one to the server as a parameter. The symptom of the latter is a failure when the server tries to execute the callback.

For reasons discussed in Chapter 15, clients behind Internet firewalls cannot export RMI servers visible outside the firewall. This means that mobile servers can only be used in the opposite—client-to-server—direction. The client can send a mobile server to another server as a parameter, but the server can't send one to the client as a result. The symptom of the latter is a failure when the client tries to execute the “call-forward” into the mobile server.

Consider the frequently asked question “how do I implement a remote input stream?”.

A straightforward RMI implementation of a remote input stream, illustrated in Example 12.4, doesn't work.

public interface RemoteInputStream extends Remote
{
       int read(byte[] buffer, int offset, int count)
          throws RemoteException, IOException;
       // ...
}

Why not? There are two problems with this implementation.

Firstly, the semantics of the InputStream.read methods, which we are trying to imitate, are incompatible with those of remote methods. As we saw in §2.5, arguments to remote calls are passed by deep copy, and are not returned after modification at the remote end. This means that the byte[] arguments to the various InputStream.read methods will not receive result data. We have to organize an intermediate interface.

Secondly, we would like clients to receive a real InputStream, which they can use in the usual ways, including the ability to layer a BufferedInputStream, and perhaps a DataInputStream or ObjectInputStream, on top of it. The RemoteInputStream of Example 12.4 is not type-compatible with InputStream—there is no type-relation between them—so it can't be used in constructors for other input stream classes. The following client code based on Example 12.4 won't even compile:

RemoteInputStream     rin = ...;// acquired somehow
InputStream     in = new BufferedInputStream(rin);

Both these can be solved with a better-defined remote interface and a serializable adapter, as illustrated in Example 12.5.

public interface RemoteInputStream extends Remote
{
       int     available()       throws RemoteException, IOException;
       void   close()            throws RemoteException, IOException;
       byte[] read(int count)    throws RemoteException, IOException;
       long   skip(long count)   throws RemoteException, IOException;
}

public class InputStreamAdapter extends InputStream implements Serializable
{
       private RemoteInputStream    rin;

       // constructors, serialVersionUID etc not shown
       public int   read() throws IOException
       {
         byte[] buffer = new byte[1];
         int result = read(buffer);
         return (result > 0) ? (buffer[0] & 0xff) : result;
       }
       public int   read(byte[] buffer, int offset, int count) throws IOException
       {
         byte[] result = rin.read(count);
         System.arrayCopy(result, 0, buffer, offset, result.length);
         return result.length;
       }
       public int   read(byte[] buffer) throws IOException
       {
         return read(buffer, 0, buffer, length);
       }
       public int   available() throws IOException
       {
         return rin.available();
       }
       public long skip(long count) throws IOException
       {
         return rin.skip(long);
       }
}

This solution has the following elements:

Note that InputStreamAdapter is type-compatible with InputStream, which it extends. This means that remote methods can be declared to receive or return InputStream objects: their implementations actually receive or return InputStreamAdapter objects.

Only the adapter and the real RemoteInputStream server know about the RemoteInputStream interface. Clients and other remote interfaces are written in terms of InputStream objects.

This solution takes advantage of the fact that RemoteException extends IOException. There are objections to using this technique: see the discussion in §12.8.2.

To complete the example, we only need to do the following:

A smart proxy is a proxy which contains some intelligence—does more than just delegate. Really, most proxies are smart proxies, or there isn't much point in having them.

A smart proxy can be used to conceal a remote interface. The client may think it's using a non-remote interface, but the object it's using may really be a smart proxy which delegates to a remote extension of the interface. This very useful mechanism allows distributing part of the implementation to the client and part to an RMI server, as the following example shows.

Consider the frequently-asked question “how do I implement a remote output stream?”. It is useful to examine this problem, as it has interesting structural features and deals with a well-known interface. However, for the actual desirability of remote output streams, see §12.15.

A straightforward RMI implementation of a remote output stream might look like Example 12.7.

public interface RemoteOutputStream extends Remote
{
       int write(byte[] buffer, int offset, int count)
              throws RemoteException, IOException;
       // ...
}

Unlike the first attempt at the remote input stream above, this solution will actually work. The remote input stream's problem with the semantics of the byte[] parameter does not arise, as the data is being sent in the same direction as the call.

However, as in the case of the remote input stream example above, we would like clients to receive a real OutputStream, which they can use in the usual ways—including the ability to stack a BufferedOutputStream and/or a DataOutputStream or ObjectOutputStream on top of it—but this RemoteOutputStream is not inherited from OutputStream. There is no type-relation between them, so a RemoteOutputStream cannot function polymorphically as an OutputStream.

To solve this, we need an intermediate class. Unlike the remote input stream example, we aren't changing the interface, so the intermediate class is a proxy rather than an adapter. The intermediate class must extend OutputStream, which suggests that it must be serialized to the client and act there as a Serializable Proxy. Our solution now looks like Example 12.8.

public interface RemoteOutputStream extends Remote
{
       void  close()       throws RemoteException, IOException;
       void  flush()       throws RemoteException, IOException;
       void  write(int ch) throws RemoteException, IOException;
       void  write(byte[] buffer)
                           throws RemoteException, IOException;
       void write(byte[] buffer, int offset, int count)
                          throws RemoteException, IOException;
}

public class OutputStreamProxy extends OutputStream implements Serializable
{
       private RemoteOutputStream rout;

       // constructors, serialVersionUID etc not shown

       public void write(byte[] buffer, int offset, int count) throws IOException
       {
         rout.write(buffer, offset, count);
       }
       // etc for other write() methods, close(), and flush()
}

This solution has the following elements:

Our RemoteOutputStream interface exports all the same methods as OutputStream. Fortuitously, all the methods of OutputStream already throw IOException, which is a base class of RemoteException, satisfying the rule that all methods in a remote interface must be declared to throw RemoteException or one of its base classes.

For the same reason, it was possible for us to change the method signatures in OutputStreamProxy to add RemoteException to the exceptions already declared to be thrown by the base class OutputStream. This is really handy, because by the rules of Java we normally can't do this.^[4] It works in this case because all the methods of OutputStream already throw IOException, which, as we just discussed, is a base class of RemoteException.^[5]

In general we won't be so lucky—we won't have such a convenient base class to extend. In the general case, we will have to catch RemoteException in the methods of OutputStreamProxy and throw an exception acceptable to the rules of Java (possibly—at worst—a RuntimeException).

From the standpoint of purity, one would frown on taking advantage of IOException in this way. Generally speaking, remote interfaces should be purpose-designed, not inherited via this sort of trickery.

To complete the example, we only need to do the following:

The remote output stream example demonstrates a general technique which is useful where clients expect an instance of some pre-existing class which is not already represented by a remote interface.

A remote proxy is “a local representative for an object in a different address space”.^[6]

RMI is itself an instance of this pattern. An RMI stub is a remote proxy—a local representative for the remote object—and it contains, or conceals, the mechanism necessary to communicate with that object. For local purposes, it implements the same remote interfaces as the remote object, so it can be used locally by the client as though it is indeed the remote object.

In the smart remote proxy pattern, the client thinks it's talking to a remote interface, which it is, but it's not talking directly to an RMI stub. Instead, it is talking to a local object which implements the remote interface and which is acting as a proxy to the RMI stub. This is illustrated in skeletal Java code in Example 12.9.

public interface RemoteService extends java.rmi.Remote{}

public class ServiceImplementation implements RemoteService{}

public class ServiceProxy implements RemoteService,Serializable{}

When the client acquires an object of type RemoteService, it receives an instance of ServiceProxy, as opposed to receiving a reference to a ServiceImplementation. The ServiceProxy is transmitted whole—by serialization—whereas the ServiceImplementation is transmitted as a remote stub, by the semantics of RMI results.

As usual, the ServiceProxy would hold a reference to the object it is the proxy for, in this case a ServiceImplementation. This reference is constructed prior to transmission, at the server, probably on construction of the ServiceProxy.

This pattern is useful where the server needs actions to be performed at the client as well as at the server. The pattern has obvious security implications, as its implementation is provided entirely by the server. The client—or its authors—may not even be aware that proxy code is being executed locally.

An RMI stub for an activatable remote object is really itself a smart remote proxy. The Jini Lookup service also uses this pattern.

A virtual proxy “creates expensive objects on demand”,^[7] where “expensive” means “expensive to create”—objects which consume a lot of memory, say, or which take an appreciable time to initialize.

RMI activation is an example of this pattern. An activatable stub is a virtual proxy for an activatable server, which takes appreciable time to be activated.

RMI activation is also an example of the smart reference pattern.^[8]

There are several ways to turn an existing RMI server (typically a UnicastRemoteObject) into an activatable service. The most obvious way is to change the existing remote object so that it is activatable:

In both cases you must also alter the remote object class to export the required activation constructor, and call the appropriate base-class constructors.

A better, less obvious way is to leave the existing RMI server alone, and implement an activatable server “in front” of it which acts as an activatable proxy, forwarding all remote method calls to the original unaltered remote object. You must also arrange to bind the activatable proxies instead of the old non-activatable ones in the RMI registry or whatever naming service you are using.

This second method appeals because it is easier to implement in environments with strong source-code-control régimes. It also appeals because it cleanly separates the requirements of activation from the requirements of implementing the remote server, at the small cost of an extra method call from the activatable proxy to the original remote object. This method call may be either local or via RMI to yet another host machine.

In either method, you must also create an application setup program to register the activatable server.

It is possible to design RMI systems in which objects have remote or local behaviour depending on context: local clients use the local object directly; remote clients use it via RMI; and different behaviour is required depending on whether the object is being used by a local or remote client.

You should avoid such a context-dependent design, in which the object must continually ask itself “context” questions such as:

This situation is a prime candidate for the application of the proxy pattern, so that local clients use the local object directly, and remote clients use it via a remote proxy. In this case, the remote proxy is a remote server which implements the same interface, and which delegates to the local object. When the local and remote versions are split up in this way, the remote version can be certain that it is servicing a remote client, and the local version can be certain that it is servicing a local client.

Each can act accordingly, without complex context decisions having to be made at run-time.

Client-server is a pattern of communication between entities which take on different roles. The client entity initiates the connection and makes a request; the server entity only receives requests and returns replies. The client normally terminates the connection.

RMI is inherently a client-server architecture. You must have a client and you must have a server.

In the client-dispatcher-server pattern,^[10] a “dispatcher” mediates between a client and a server. The client communicates with the dispatcher to access a service by name, and the dispatcher forwards the request to the server registered under that name.

This pattern can be used to provide “ location transparency”, so that clients need not be aware of the actual network location of servers. It can also be used to implement load-balancing.

RMI is itself an instance of this pattern. Under the covers, stubs (clients) communicate directly with the RMI runtime system (dispatcher) which dispatches the call to the appropriate remote objects (servers) by means of a fixed object name (object ID). In a way, the RMI registry is another example of this pattern.

Peer-to-peer is a pattern of communication between entities which are peers of each other—there is no master/slave or client/server relationship between them. Either peer is entitled to initiate and terminate the conversation, and either is entitled to submit requests and return replies. We mention this pattern only to point out that RMI does not support it.

As a general rule, “singleton equals stateless”. When designing RMI servers, one of the first questions is “do I supply a new instance to each new client, or do I supply the same instance to all clients?” The answer depends on whether or not the server accumulates state about a client. If it does, the client needs its own instance of the server; if it does not, all clients can use the same server instance—a singleton.

If the answer is “new instance per client”, you must be designing a server with per-client state. (This might be a time to use the session pattern: see §12.13.)

If the answer is “same instance”, you are really designing a stateless server which can handle any client. There are considerable advantages in designing your servers to be stateless:

The kind of server which is bound to the RMI registry is most usually a singleton. A server which is made available to any client via a name in the registry is normally stateless and therefore a singleton, by the “singleton equals stateless” principle.

The result of registering an Activatable—an activatable stub—represents a singleton ActivationID at the server host. The activatable represented by the ActivationID—the tuple of {groupId, class, location, initial data}—is only instantiated once per host. Unless you have deliberately registered the same ActivationDesc more than once, or registered more than one ActivationDesc for a server class in the same activation group, only one instance of the Activatable class will execute in the activation group.