RMI Plug-in for Eclipse
version 2.0

The Codebase Editor

What is a codebase

The codebase is a property of a java remote object that tells its users where they can find the .class file definitions that are needed to use the remote object. The codebase is specified as a java VM property (-Djava.rmi.server.codebase=<....>). You can read some explanations below or skip directly to the description of the codebase editor.

Why do we need codebase - Example #1

The most common example of why codebase is important is is the case of _Stub classes. Stub classes are used by Java on the "client side" to communicate with the corresponding remote objects on the "server side" (RMI Plug-in can automatically generate such stubs). Therefore, these _Stub files that are generated for the server class, must be accessible by the client JVMs. One can propose a simple solution - just copy the files to the client project, and in fact it will work. But when the remote class changes, stubs will have to be re-generated and copied again to all clients. After 10,000 clients have been already deployed, that would be almost impossible to accomplish.

The solution that is used by the Java RMI implementation is to place the _Stub classes (and some other required classes) at a central location that is accessible by the clients. Such location can be a webserver, NFS directory or Windows share. Then, the remote object is annotated by is VM with this location (in a URL form) and each time a reference to the remote object is passed to a new client VM, the Java RMI implementation also receives this location where the required _Stub classes can be found. That location (actually a list of locations) is called the codebase, and it must be set correctly for server VMs in order to let clients operate smoothly. How do we set the codebase? We can manually define the -Djava.rmi.server.codebase property or let the RMI Plug-in do it for us. This page describes how to configure the codebase using the RMI Plug-in for Eclipse.

Note: Since Java 5.0, there is another solution to the problem of distributing _Stub files (that uses dynamic proxies). However codebase is still needed for dynamic proxies and in many other cases.

Why do we need codebase - Example #2

Suppose you've created a server that can perform various computations, like the "Compute Server" example adopted from Sun's RMI tutorial. The server implements a remote interface similar to:


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

The Task interface is defined as (it is serializable and therefore will be executed on server)

public interface Task extends Serializable {
    Object execute();
}

When a client calls the "executeTask" method (after successfully acquiring a reference to the compute engine) he will pass it a concrete implementation of the Task interface, for example a ComputePiTask. However, the java server VM doesn't know the ComputePiTask class and if we do nothing about it, it will throw us the infamous "java.rmi.UnmarshalException". Unlike the previous example, we really don't want the server to know who all its clients are, so we can't just copy the class file to the server project. So the solution to the question of "how does the server find the ComputePiTask class" is to use the codebase property. If we set the codebase property of the client VM to point to a location where the ComputePiTask class can be found, the server will receive the codebase annotation from the client and use it to load the ComputePiTask class. Note that in this example, it is the client who must define a codebase, since it has a class that server does not have.

Debugging codebase problems

Debugging codebase problems is easy with the use Registry Inspector and the RMI Spy. All the java.rmi.ServerException, java.rmi.UnmarshalException and java.lang.ClassNotFoundException-s won't be bothering you anymore.

Additional information

More information about using the codebase can be found in the JDK documentation at http://java.sun.com/j2se/1.5.0/docs/guide/rmi/codebase.html.

The codebase editor.

The codebase editor of the RMI Plug-in can be opened from the RMI Launcher when editing the RMI Java VM properties. When you click inside the value cell of the "java.rmi.server.codebase" property, you'll see the "..." button. Pressing the button will bring the codebase editor window.

The value of codebase property is a space separated list of URLs. The codebase editor makes it easy to edit and test the codebase values. For simple projects, where both the client and the server run on the same machine, pressing the "Compute from classpath" is all you need. If you need the codebase to be available to VMs on remote machines, you have to manually add the corresponding entries.

You can notice that the codebase editor of the RMI Plug-in supports workspace-relative locations through the use of the ${workspace_loc} variable. Through the use of the ${workspace_loc} variable, the codebase will remain correct even when you move your project to a different location or share it through CVS. You can use additional workspace variables as well, as described here.

When you add a new codebase entry or edit an existing one, the codebase element dialog will open. Using the codebase entry dialog you can add a new codebase entry either from a filesystem, from a workspace or you can enter the URL directly into the codebase entry field:

To summarize it - it takes time to understand what Java RMIcodebase is all about. Until then, use the codebase editor to avoid the most common and annoying mistakes. You won't believe how many creative ways there are to get it wrong.

RMI Plug-in for Eclipse version 2.0