Remote Method Invocation (RMI)

Remote Method Invocation is Java's "objectization" of the usual Remote Procedure Call capablilites of most modern server-capable operating systems such as Unix/Linux or Windows Server. RMI enables a client computer to access an object located in a remote server as if it were a locally instantiated object in the client.

Quick links:

• Overview
• RMI connectivity issues
• Remote dynamic class loading
• Comparing deserialized objects
• Transient fields in classes
• Threading problems
• Handling RemoteExceptions
• Tips and Traps
• Course-specific RMI resources:
  • Overview
  • Introduction to Remote Method Invocation (RMI)
  • System Topologies, Dynamic Class Loading and Generics
  • Stub passing

RMI Overview

Features:

• Both the client and server are object-oriented systems. The interaction between the server and the client is encapsulated in one or more remotely accessible objects. These objects are instantiated on the server, but the client treats the object as if they were local instantiations.
• Once the inital communication between the server and client has been established, all further communications are completely transparent to both the client and the server.
  • Just as in the methods of ordinary objects, the methods of remote objects can take objects as inputs and return them. There are a couple of things to note:
  • Ordinary objects that are passed as arguments or returned by the methods must implent Serializable. This enables them to be sent as a data stream across the network. Only the data and not the executable code for objects is passed, thus both the client and server must have a copy of the class file for that object.
• Remote objects can be passed from the server to the client as the return value of a method. In this case, the object is not actually transmitted, but rather, just a stub (see below and the link to the left).
• Initial communications between the client and server is established through simple URL-type addressing with minimal references to any underlying communications mechanisms or protocols.

 Main Components:

1. A "client" computer and a "server" computer: The remote object resides on the server and is accessed by the client. Note that the roles of client and server are not permanent and may change/reverse depending on which computer accesses a remote object stored on another computer. It is possible for a single computer to be both a client and a server.
2. An interface that implements java.rmi.Remote: This is the view of the remote object by the client. To the client, the remote object on the server is a local object with the specified interface. All clients accessing the remote object must have a local copy of the same interface class unless it is being dynamically downloaded as part of the deserialization proces ("remote dynamic class loading").
• RECOMMENDED: This interface should NOT extend Serializable. This will help reduce coding errors by producing a "Not Serializable" exception when the wrong object is accidentally transmitted.
3. An instantiation of a class that implements the same interface given in #2 above: This "RMI Server" object is the remotely accessible object that resides on the server.
• Note: Some RMI instructions online advocate having the RMI Server class extend UnicastRemoteObject. While this is a legitimate technique for creating the RMI Server and subsequent RMI Stub objects (see below), because UnicastRemoteObject extends Serializable, these techniques result in a loss in coding safety (see the above recommendation) and hences in NOT RECOMMENDED.
4. A "stub" object (automatically) created from the above remote object's class file: This "RMI Stub" object is instantiated by the same application that holds the above RMI Server object. The RMI Stub object is transmitted to the client whenever a reference to the remotely accessible object (RMI Server object) is established. This is the actual object that the client interacts with. The stub object simply delegates all methods call across the network to its corresponding skeleton object on the server.
5. A "skeleton" object (automatically) created from the above remote object class file: This object resides on the server and delegates method requests received across the network from the stub object to the actual remote object.
6. To make a stub, following the above recommendations:
• IMyRemoteObject stub = (IMyRemoteObject ) UnicastRemoteObject.exportObject(myRemoteObjectInstance , aPortNumber)
• IMyRemoteObject  -- an interface that extends Remote that the stub and the actual server object will implement. 
• myRemoteObjectInstance -- the actual instance of the server object that the stub will forward all calls to back across the network to the server.
• aPortNumber -- a TCP port number that needs to be open through the server machine's firewall (inbound) to allow the stub to talk back to myRemoteObjectInstance
• The created stub is automatically Serializable and thus suitable for transmitting to remote machines that need it.
• The RMI skeleton object is also automatically and transparently created. Developer code never needs to to directly interact with the skeleton object.
7. The RMI Registery: This is a program on the server called rmiregistry that must be running before any RMI connection is established. This program associates an instatiation of a remote object with a name that can accessed with a URL-type call. A name is "bound" into the RMI registry by using Java's built-in method.  There are many ways to do this, but if we already have a stub as from above, we can easily bind the stub to a name in the registry as such:
   • registry.rebind(aName, stub)
   • registry -- a reference to the RMI Registry running on the server machine.  Note: it can be non-trivial to get this reference, which is why utility classes are provided to do this for you.
   • aName -- (a String) the name to which the stub will be bound.   This is the name a remote client will use to find the stub.
   • stub -- the stub object as created above.
     
8.  Finding the and downloading the stub from a remote server, as a RMI client would do, is easy enough:
   •  IMyRemoteObject stub = (IMyRemoteObject ) registry. lookup(aName)
   • where everything is as described above, except that the registry is not the Registry on local client machine, but rather the Registry on the remote (w.r.t. the client) server machine.  Once again, utility classes will be supplied to make it easier to obtain this reference.
     
9. Dynamic Class Loading:  see below.
   

Stubs and Skeletons

Remote clients communicate with server objects via stubs and skeletons. These stubs and skeletons are automatically produced by the Java compiler on class files that extend UnicastRemoteObject and have an interface that extends Remote.   The stubs and skeleton are implementations of the Proxy Design Pattern, which is related to the Decorator Design Pattern.

• The stubs and skeletons are adapters that first adapt the client to the Internet and then the Internet to the server's object.
• Any serializable object (i.e. implements Serializable) can be transmitted to the server by use of an input parameter if a method of the IRemoteObject interface.
• Any serializable object can be sent to the client by use of the return value of a method of the IRemoteObject interface.
• Any method that the client runs on the remote object actually runs on the server.
• Any method of a serializable, non-UnicastRemoteObject object set to the client runs on the client.
• A class server must be running in order for the RMIRegistry to initially load the stubs in preparation for transmitting them to clients.

Factories and RMI

Factories are one of the most useful techniques to use with RMI. Usually the server only binds out one object, a factory object, which the client uses to instantiate all the other objects it actually needs. This makes connecting much simpler, more flexible and more robust.

This technique is important enough that Sun even has a whole web page devoted to it: https://docs.oracle.com/javase/8/docs/technotes/guides/rmi/Factory.html

Remote Dynamic Class Loading

When an object is serialized, Java inserts both the class name and a URL value,  java.rmi.server.codebase, into the byte stream.   The Comp310 RMIUtils.startRMI(portNumber) call will set the  java.rmi.server.codebase value to refer to the class file server that it sets up running on your local (sending) machine on the portNumber port that can retrieve class files from your project's bin folder.

When an object is deserialized, the Java class loader looks at the imbedded class name and first checks whether or not the class is on the local (receiving) machine.  If the class is not found there, then the class loader uses the imbedded  java.rmi.server.codebase value to make an HTTP GET call (the same type of call a browser uses to retrieve a web page) to that URL to retrieve the class file.

The Java class loader is smart enough to realize that if an imbedded object uses other classes, then if those classes are not available locally, the class loader will then use the same java.rmi.server.codebase value to retrieve those classes as well from the remote location.

Sun (the originators of Java) has written a simple class file server that can be used for dynamic class loading. That code is provided here in a slightly modified version of Sun's class file server. It will work properly only if the java.rmi.server.codebase system property is as a URL that points to it. For example, http://foo.cs.rice.edu:2001. The server also needs to know the exact path to the default Java package directory on the server machine.

Note: If both the client and the server have classes with exactly the same name, errors (usually unmarshalling errors) can occur. It is highly recommended that the names of any serialized classes being sent across the RMI connection be "personalized" in some way--by appending one's initials to the classname for instance. This problem can be avoided by carefully setting up exactly what directories are visible to the RMIRegistry, class server and application when they are running, but that is beyond the scope of this web page. For this reason, Java has class naming conventions that, in a nutshell, are that any package create for Internet use should be their creator's URL backwards, e.g. edu.rice.cs.comp310.rmi. 

RMI Start-up Process

1. Start the Java SecurityManager which controls how much of the system RMI can access.
   • The security parameters are controlled by the security.policy file.
2. Configure Java system parameters:
   • java.rmi.server.codebase --  The IP address of the RMI server object
   • java.rmi.server.hostname -- The IP address of the class file server for remote dynamic class loading
   • java.rmi.server.useCodebaseOnly -- If false, remote dynamic class loading is allowed.
   • java.rmi.server.logCalls -- Prints RMI interaction information to (unfortunately) stderr.
3. Start the class server for remote dynamic class loading before binding anything to the Registry
4. Start the Registry on any machines where objects will be bound.
5.  Make sure to start the RMI server end of  the system before the RMI client end tries to connect to it.

Resources

• Java 6 RMI documentation, including examples: http://java.sun.com/javase/6/docs/technotes/guides/rmi/index.html
  • Using factories with RMI: http://java.sun.com/javase/8/docs/technotes/guides/rmi/Factory.html
  • System properties used by RMI:
    • http://java.sun.com/javase/6/docs/technotes/guides/rmi/javarmiproperties.html  -- commonly used properties:
      • java.rmi.server.codebase
      • java.rmi.server.hostname
      • java.rmi.server.logCalls
    • http://java.sun.com/javase/6/docs/technotes/guides/rmi/sunrmiproperties.html
• RMI Short Course
  • http://java.sun.com/developer/onlineTraining/rmi/RMI.html
• HTTP Tunneling and RMI
  • Need to set the System property "http.proxyHost".
  • http://java.sun.com/developer/onlineTraining/rmi/RMI.html#FirewallIssues

Tips and Traps

Do Not Serialize Anonymous Inner Classes

Since the serialization process is a deep-copy process, where object references are followed and any referenced objects are serialized alongside the host object, attempting to serialize an anonymous inner class will cause Java to attempt to serialize the enclosing object(s) that comprise the anonymous inner class's closure.    This is because all inner classes contain a hidden field that references the enclosing class(s) that form its closure.    However, the enclosing class may not be serializable or not desired.  For the most part, the enclosing class is either to big to serialize and transmit or simply not be serializable, thus throwing an error.

This is the #1 cause of serialization/marshalling/unmarshalling errors!

Work-arounds:

• Switch the anonymous inner class to the instantiation of a named class that can either be a normal externally defined class or a nested (static) class.  If the class is stateless, consider also creatng a singleton.
• Switch to using a factory (defined using a named class) to instantiate the anonymous inner class instance. The factory class will limit the range covered by the anonymous inner class's closure to just what is inside of the factory object, which typically isn't much. This technique has the advantage of retaining the ability to curry entities into the anonymous inner class's closure and thus dynamically create "custom" entitites.

Comparing Deserialized Objects

Transient Fields in Classes

RMI executes void returns asynchronously:

UPDATE: As of 12/2015 (Java 8), there is evidence that void returns are not being executed asyncronously.  The Java RMI specification is a bit vague on this issue but there is documention that suggests that it must wait because non-declared run-time exceptions, e.g. IllegalArgumentException, must be passed back to the caller of a method on a stub (https://docs.oracle.com/javase/8/docs/platform/rmi/spec/rmi-stubs24.html).  

In light of this, it is highly recommended that in asychronous message-passing architectures, that all method calls to RMI stubs be handled by a dedicated thread that releases the caller from the waiting for the void return to complete.   For methods that are frequently used, a dedicated producer-consumer mechanism with a BlockingQueue is recommended.

RMI does not wait for the return of a remote void method call to return before proceeding on to the next statement. This can cause some strange behaviors if the code assumes a certain order of execution based on the assumption that the call to the void method waits for it to finish, as normally happens in a non-RMI, single-threaded situation. For instance, the following code can cause problems:

// in ObjectA, initially call method1() below. remoteObjectB is a RMI stub to a remote ObjectB instance.

void method1()
{
remoteObjectB.doIt();
System.out.println("the statement after the call to remoteObjectB");
}

void method2()
{
System.out.println("this might come out first or second!");
// This will mostly likely come out second due to network delays.
// In a non-RMI, single-threaded situation, this line would print first.
}

// The following is in class ObjectB which holds an RMI stub to the above ObjectA instance. 

void doIt()
{
remoteObjectA.method2();
}

Exporting a Stub Does NOT Prevent the Remote Object From Being Garbage-Collected

This issue may be the source of common "Object not in table" or "Connection Refused" errors.   Symptoms include inconsistent program behavior from execution to execution and operations that stop working after working initially when a program is run.

When one exports a Remote object to create a RMI stub, it is tempting to believe that the auto-generated skeleton object would maintain a reference to the original Remote object and thus prevent it from being garbage-collected but this is not so.

IMyRemoteClass stub = (IMyRemoteClass) UnicastRemoteObject.exportObject(myRemoteObject, aPort);

If for instance, 'myRemoteObject" above is an anonymous inner class defined right there, there is no reference to that object anywhere.   The generated RMI skeleton does not keep a reference either so at some point the anonymous inner class object will get garbage collected.   This means that an error will be generated the next time the stub is used because it has no more back-end object to actually perform the operations.

Solutions:

• Use fields in classes to maintain references to the original Remote objects (not the stubs).   Don't rely on local variables or anonymous inner class instances to stick around otherwise.
• Put the original Remote objects in a storage collection, e,g. a Vector to maintain a reference to them.

ALSO, always save the stub generated from an RMI Server object as a field somewhere because Java only allows you to generate a stub from an RMI Server object once but one's code typically needs to use, e.g. transmit, that stub many times.

RMI Application May Run Better From Console Than From IDE

Since RMI relies on I/O ports, one's Integrated Development Environment ("IDE", e.g. Eclipse, DrJava, etc) may not properly manage the I/O resources as your RMI application starts and stops, resulting in erratic behavior such as intermittent connection failures.   Since any Java application is actually a process being run by the JVM, the host operating system is often not able to do the more complete "cleanup" that it does when a normal application terminates.    If the IDE is also using RMI, such as DrJava uses to communicate with its Interaction Pane, there is the possibility that your RMI  application may conflict with the RMI usage of the IDE.

Work-arounds:

• Try using a non-default port for the Registry, i.e. not TCP 1099.
• Be sure to explicitly close any ports used, unbind from the Registry and shut down any class file servers.
• Run the code from the command line to enable the operating to do its full clean-up.   A batch/command file is a convenient way to do this.

Inadvertent Thread Blocking, Deadlocking or Other Problems

When remote calls to methods on RMI skeletons (UnicastRemoteObject) are called, the RMI system starts up a new thread to handle that call. It is important to realize this, as it may cause some strange and unexpected problems:

• Making changes to the GUI is a cross-thread invocation error:    It is a cross-thread invocation error for the code that is running under the RMI processing thread to attempts to update or mutate the GUI in any manner.   (Note: JTextArea.append() is one of the few thread-safe exceptions to this rule.). 

  • Work-around: Use SwingUtiltities.invokeLater() to transfer the GUI-modifying code to the GUI event thread.
• The caller blocks or locks waiting for a return value:  If the remote method being called returns a value, then the caller is blocking until the RMI remote method completes and returns a value. This can make the caller's program slow and unresponsive or worse, lock-up completely. 
  • Work-around: Whenever possible, return simple status values only.   The method on the skeleton (the receiver) should spawn off another thread to perform any processing and quickly return a simple value to the caller.  This will quickly release the caller from its block.   The spawned-off thread can then asynchronously return a value by calling a method back on the caller, passing any values as input parameters. 
  • Work-around: Convert the method that makes the remote RMI call into a void return.   Spawn a new thread that makes the RMI call and processes the returned value (asynchronously with respect to the original thread that calls the method).    This will prevent the original thread from blocking on the RMI call.

A pathological but not-that-uncommon scenario:

1. From the calling machine, the user clicks a button whose code makes an remote RMI call to the their own machine (the caller is connected to itself) on a method that has a return value.
2. The calling machine's GUI thread is now blocking, waiting for the return from the remote call.    The caller's GUI is currently non-operational because of this.
3. The remote method needs user input, and so, attempts to use the GUI.   Properly, the remote method uses an SwingUtilities.invokeLater() call to place an event onto the GUI event queue.
4. The remote method blocks deliberately because it is waiting for the user's input.      
5. But since the remote method is actually running on the caller's machine, it is trying to use the blocked GUI from step 1 above.   The queued event from step 3, thus never executes.   Thus step 4 never unblocks.   Thus the remote method never returns.   Thus the GUI in step 2 never unblocks.
6. The entire application has deadlocked and is frozen solid!  

Curious artifacts of the above problem:

• If the caller is not connected to itself, i.e. is connected to a different machine, the problem does not arise because the receiver's GUI thread is not being blocked.
• If the deliberate (and necessary) blocking in step 4 is removed, then the system will not deadlock.   But since the deliberate block is not being put on the GUI thread, it is not obvious at all that it will deadlock the GUI.

A solution:  In step 1 above, spawn a new thread that will actually perform the remote call and

1.  Allow the GUI thread to immediately return and not block.
2. Asynchonously process the returned value.  Note that the spawned thread is the one that is blocking on the RMI call, not the GUI thread.

For more information, please see the Comp310 Java Resources page on Threads.

All Remote interfaces must be part of the shared API!

It seems that RMI does not handle dynamic class loading of Remote interfaces very well.   The problem arises when a client receives the stubs implementing the same Remote interface from multiple sources.  If the Remote interface is not part of the shared API, i.e. a common code base, then that interface must be dynamically class loaded when the stub is deserialized.    The problem is that when stubs implementing the same dynamically loaded Remote interface are received from multiple sources, RMI can't seem to tell that they are actually implementing the same interface because it sees the objects coming from different source computers.   RMI then tries to load the class file for that interface from each of the computers from which it receives stubs, uniquely identifying each class associated with the each of the downloaded class files. 

Then, under certain circumstances, RMI realizes that it cannot or rather, improperly identifies the class of a new incoming stub of that Remote interface.    The result is a ClassCastException as RMI tries to cast the stub to one of the classes it received from a different source.    This is a very confusing error because it appears to all aspects that RMI is unable to cast an object to its own class because everything about the multiply-downloaded classes all appear the same: fully-qualified name, methods, superclasses, implementing interfaces, i.e. everything except the hash codes of the associated Class objects (which is why RMI thinks they are different).  

Bottom line: The Remote interfaces used by the system MUST ALL be part of the shared, public API.

Thus, the use of implementation-specific stub interfaces will not work.

Address/port in use errors

The most common cause of this error is that an instance of the application is still running. Note that the Java RMI Registry and the class file server are technically separate processes and it is possible from them to keep running even if it looks like the main application has already shut down.

Always explicitly stop the RMI processes (IRMIUtils.stopRMI()) and notify any connections when the application exits.

To figure out if there there are still application processes running:

• Windows: Use the "Task Manager" (right-click the task bar and select "Task Manager")
• Mac: Use the "Activity Monitor" (common+space then type in "Activity Monitor")
• Linux: ??

To see what processes are using a particular address/port:

• Windows:
  • Open a command window with Administrator privileges
  • Type netstat -abo
  • Look through the output to see what process is using the desired address and port.
• Mac: ??
• Linux: ??

If you know any of the commands or procedures for the missing items above, please let the course staff know right away so this page can be updated.

Unless you know exactly what the offending process is, it not recommended to outright kill it as this could cause data corruption problems. Try to exit the offending application gracefully or reboot one's computer if necessary.

Potentially problematic apps (please let the course staff know if you find any other apps so this list can be updated!):

• Windows:
  • Port 2001:
    • Dropbox.exe -- This port is not listed by Dropbox's documentation so it is not clear if this port is always used or if is just a possible random choice.

© 2020 by Stephen Wong