A codebase is a list of one or more URLs separated by spaces. Each item in the list is a standard URL, of the form

protocol://host[:port]/file

where:

When a class file, say rmibook.quicktour.RemoteEcho, can't be found locally on the CLASSPATH, the fully qualified class name is converted to a class filename, say javarmi/quicktour/RemoteEcho.class. What happens next depends on the form of file in the codebase URL.

In either case, if the process fails, the next URL in the codebase is tried. If all codebase URLs fail, a ClassNotFoundException is thrown.

Polymorphism is Greek for “many forms”. In object-oriented terminology, it means that a derived class can be used wherever any of its base classes can be used. This is a fundamental object-oriented design technique, and it is also the basic mechanism for exploiting code mobility.

Just specify your remote interfaces polymorphically. This means specifying the result or parameter types (or both) of your remote interfaces in terms of base classes (or Java interfaces), but passing or returning objects of derived classes. If the derived class is unknown to the receiver, normally this technique fails with a ClassNotFoundException at the receiver. However, if the object is being received by RMI and the class has been annotated with a valid codebase, the RMI runtime in the receiver downloads the class dynamically—on demand—from the codebase, and execution continues.

By this means you can truly exploit object-oriented polymorphism in RMI applications. Consider the following example:

public interface InterfaceKnownToClient { ... }

public interface RemoteService extends java.rmi.Remote
{
       InterfaceKnownToClient method() throws RemoteException;
}

A server which implements RemoteService can return any implementation of InterfaceKnownToClient it likes from RemoteService.method. If the class of the result is not known to the client, and if the correct codebase conditions exist at the server, the implementation class will be downloaded to the client.

This technique allows the server to vary the implementation class unbeknownst to the client, for application-specific reasons. It also allows the implementation class itself to evolve without having to be redeployed to all clients, and without being constrained by the versioning rules of serialization.

The same technique can be used in the reverse direction, allowing the client to supply the implementation class to the server:

public interface InterfaceKnownToServer { ... }

public interface RemoteService extends java.rmi.Remote
{
       void method(InterfaceKnownToServer is) throws RemoteException;
}

You can use code mobility to reduce the amount of code installed at the client.

You can use code mobility to avoid the “rollout” problem—client reinstallations—for classes which are likely to evolve over the life of an application. By ensuring that such classes are always obtained dynamically, you never have to redistribute them statically. You only have to update a single copy of the class at the codebase server: RMI propagates the class as required.

By ensuring that sensitive classes are not installed at the client but are obtained dynamically, you can reduce the possibility of external tampering with class files.

An RMI server or client which wishes its classes to be available to the other party must have an appropriate value set in the system property java.rmi.server.codebase. This causes all classes marshalled by RMI to be annotated with the codebase property.

As an alternative to setting the codebase property, from JDK 1.3 the server or client can acquire a required class via the RMIClassLoader.loadClass method, specifying a URL as the class location. This has the same effect—it causes the loaded class to be annotated with its codebase location—but it has the advantage that multiple codebases can be used at each end. This technique is therefore more flexible, but it is a little more inconvenient to access classes in this way, and it requires that the classes so accessed be unavailable via the CLASSPATH; otherwise no annotation will occur.

RMI code mobility will not work unless the registry is correctly set up. This is a frequent source of error. You must use the “standard” registry configuration described in §6.10.1.

The registry problems most frequently encountered are as follows:

To understand these problems, consider what happens when an RMI server is bound to the registry. When Naming.bind or Registry.bind is called, the registry receives the name and the RMI stub for the server being registered.

If the RMI registry is running in an environment with no java.rmi.server.codebase property and no CLASSPATH access to application classes, and the caller of bind doesn't have a java.rmi.server.codebase set, the registry itself will encounter a ClassNotFoundException when unmarshalling the arguments. This exception will be wrapped in an UnmarshalException and thrown remotely back to the caller—the server.

Example 9.1 shows a server initialization.

Remote     remote = new RemoteXXX(...);// args not shown
Naming.rebind("name",remote);
// If this throws a ClassNotFoundException wrapped in a
// RemoteException, the codebase was not specified
// correctly when running this code

Regardless of the server's codebase settings, if the RMI registry is able to load the stub class from its CLASSPATH it will do so, and if it doesn't have java.rmi.server.codebase set, it won't annotate the class when it has done so. The result is an un-annotated RMI stub class in the registry. Now, when a client calls Naming.lookup or Registry.lookup, a ClassNotFoundException will be thrown when the client unmarshals the result, and this will be wrapped in an UnmarshalException at the client.

Example 9.2 shows a client initialization.

Remote         remote = Naming.lookup("name");
// If this throws a ClassNotFoundException wrapped in a
// RemoteException, the Registry was able to load the stub class directly
// (not via the codebase), or the codebase was not specified
// when running the Registry

The codebase is a list of one or more URLs. Each URL refers to a codebase server, typically an HTTP server. Each such server needs to be running and available at the specified URL. You can check this from a client with a Web browser. The codebase server doesn't need to run in the same computer as the RMI services, or even in the same network segment; it just has to be accessible to codebase clients.

Client installations should contain the JDK and the client side of the application. This includes any remote interfaces, because the client knows about these. It does not include RMI servers, skeletons or stubs. Servers and skeletons do not belong at clients at all; stubs can be downloaded if the system is set up correctly. The client installation should also exclude any classes which you specifically want to download to the client; this would include any classes which the client acquires polymorphically, i.e. via references to base classes or interfaces.

Further control can be gained over dynamic code loading by setting the java.rmi.server.useCodebaseOnly property to true. This forces RMI to ignore the codebase transmitted with the class, and use the codebase configured in java.rmi.server.codebase to load classes not found on the CLASSPATH.

This is useful when both servers and clients are executed with java.rmi.server.codebase properties. It causes each end of a remote call to ignore the codebase information coming from the other end, and to use its own value instead.

This technique provides some additional security. It becomes impossible to tamper with the transmission so as to cause the target to load a class from a different codebase—to interpolate unauthorized classes into the target.

This may be particularly appropriate for RMI servers uploading classes from clients, as client environments may be only partially trusted.

Sun provides a free class file server. This is a “lightweight” and simple HTTP server which can be used during development of RMI systems using code mobility. The class file server is shipped with recent versions of the JDK and Jini, and can be obtained as source code from

Use of the lightweight class server is unrestricted. However, you probably wouldn't choose to deploy this as your codebase server in production, for a number of reasons:

This last restriction means that the server will not handle class files in JAR archives. It also means that the server will not satisfy requests for application resources made via the Class.getResource or Class.getResourceAsStream methods—for instance, application graphics or ResourceBundles associated with classes acquired from a codebase.

The Java 2 Enterprise Edition (J2EE) comes with a built-in HTTP server. Sun's Java Web Server is an HTTP server. Many other free and commercial HTTP servers are available.

You can use the file: protocol. This can only work in an installation where every client has file-level access to the codebase, typically via a network shared drive. It will not work if the file: URL refers to a file on the codebase server in terms of its own local file system, because clients will interpret the URL relative to their own local file systems. URLs must make sense to the client.

You can use the ftp: protocol. This requires you to have an FTP server running at the codebase location.

FTP is not always supported through firewalls, so it would generally not be a suitable choice for:

Most Web servers also provide an FTP service, including Sun's Java Web Server and the servers provided with J2EE. The “lightweight” HTTP class server discussed above does not provide an FTP service.

If you have installed the Java Secure Sockets Extension (JSSE), you can use the https: protocol. HTTPS is a secure version of HTTP; in fact it is HTTP transmitted over secure sockets (SSL) instead of plain sockets, the difference being that secure sockets are authenticated and encrypted. (For more information on SSL see Chapter 16.)

Using HTTPS instead of HTTP provides you with secured access to the codebase from within your application. You must specify https as the protocol in the URL for the codebase, and set the URL's hostname to that of the HTTPS server. If you have HTTP proxies, you must also set the system properties https.proxyHost and https.proxyPort appropriately. You must also arrange for the system property java.content.handler.pkgs to be set appropriately, as described in the JSSE documentation.

J2EE comes with a built-in HTTPS server. Sun's Java Web Server provides an HTTPS service. Many other free and commercial HTTPS servers are available.

Using HTTPS rather than HTTP provides security at the expense of performance. There is an overhead in setting up the initial secure socket connection, and there is an encryption overhead per transmission.

HTTP and HTTPS servers (or their proxies) can be set up to require a client to provide authentication before access to the requested resource is granted.

Normally in a Java HTTP or HTTPS client this will cause an authentication failure. You can provide a java.net.Authenticator to respond to any such authentication process. In this way the application can provide the authentication required itself. This information could be obtained from:

In this technique, the RMIClassLoader is used to acquire the class from a well-known codebase URL, as shown in Example 9.3.

public class URLClientBootstrap
{
       static String codebase    = ...; // codebase URL
       static String clientClass = ...; // client class-name

       public static void    main(String[] args) throws Exception
       {
              System.setSecurityManager(new SecurityManager());
              Class cl = RMIClassLoader.loadClass(codebase,clientClass);
              Runnable  client = (Runnable)cl.newInstance();
              client.run();
       }
}

In a realistic application, the codebase and clientClass values would be acquired via the command line or an external configuration file, and exceptions would be handled more appropriately.

The downloaded-client technique can be used even if the client proper makes no use of RMI. A similar technique is used by Java to force downloading of classes used by Java applets.

In this technique, an RMI call is used to acquire the client from a well-known RMI server. The server must ensure that the java.rmi.server.codebase property is set appropriately, or that it acquires the class to be sent to the client via the RMIClassLoader as in Example 9.3. The client side of this technique is illustrated in Example 9.4.

// Remote interface defining the bootstrap service
public interface    Bootstrap extends java.rmi.Remote
{
       Runnable     getClient() throws RemoteException;
}

// The client bootstrap
public class RMIClientBootstrap
{
       static String bootstrapServer = ...; // RMI registry URL

       public static void main(String[] args) throws Exception
       {
              System.setSecurityManager(new RMISecurityManager());
              Bootstrap  bootstrap = (Bootstrap)Naming.lookup
                                            (bootstrapServer);
              Runnable  client = bootstrap.getClient();
              client.run();
       }
}

In this case, the client implementation class and all classes reachable from it must be serializable or remote.

In a realistic application, the bootstrapServer value would be acquired via the command line or an external configuration file, and exceptions would be handled more appropriately.

In this technique, the client acquires a sequence of bytes from somewhere, possibly a URL, de-serializes an object from it, casts the result to MarshalledObject, and calls MarshalledObject.get to obtain and execute the client (e.g. as a Runnable, followed by a call to Runnable.run). This assumes that the inverse sequence of operations—construction of a MarshalledObject from a client instance, and serializing it to a client-accessible location—has occurred at some previous time. The client side of this technique is illustrated in Example 9.5.

public class MarshalledObjectClientBootstrap
{
       public static void main(String[] args) throws Exception
       {
              System.setSecurityManager(new SecurityManager());
              InputStream in = new URL(args[0]).openStream();
              ObjectInputStream oin = new ObjectInputStream(in);
              Object      object = ((MarshalledObject)oin.readObject)).get();
              Runnable    client = (Runnable)object;
              client.run();
       }
}

The setup required for this technique is illustrated in Example 9.6.

This technique doesn't require the client to be able to connect anywhere. The MarshalledObject can contain arbitrary code to locate the appropriate client object or server; indeed, it could perform a secondary bootstrap via RMI as described above.

public class MarshalledObjectClientBootstrapCreation
{
       public static void  main(String[] args) throws Exception
       {
              System.setSecurityManager(new SecurityManager());
              // Load and annotate client class, and construct a client
              Class        cl = RMIClassLoader
                                 .loadClass(codebase,clientClass);
              Runnable     client = cl.newInstance(...);
              OutputStream         out = ...;    // create some output stream
              ObjectOutputStream           oout = new ObjectOutputStream(out);
              oout.writeObject(new MarshalledObject(client));
              oout.close();
       }
}