Logo of the Java RMI Plug-in for Eclipse

RMI Plug-in for Eclipse
version 2.0

The RMI Stubs Builder



The RMI builder is responsible for generating the stubs (and skeletons, when compatibility mode is selected) for all remote classes in a project. It replaces the manual compilation of the stubs using the command line "rmic" compiler. To enable the RMI builder for a Java project, right click on a Java project and locate the "RMI" submenu. In the "RMI" submenu select the "Enable Stubs Generation" option. If you don't see the "RMI" submenu, make sure you're using either the "Package Explorer" or the "Navigator" view.


(click to enlarge)

The RMI builder begins by scanning your project for all remote classes and then invokes JDK's RMI compiler (rmic) on these classes (the RMI compiler is part of your Java SDK). Depending on your project's settings, the compiler is invoked either inside the Eclipse VM or in a separate process (using the command line "rmic" tool). If the RMI compilation fails, the RMI Plug-in for Eclipse tries to parse the error messages and create the most appropriate "error" entries in the "Problems" view. The complete error messages are always stored in the ".log" file which is located in the ".metadata" subdirectory of your workspace.

The RMI Plug-in for Eclipse supports Sun's JDK RMI compiler on all platforms. IBM J9 (that comes with RAD6.0) is supported on Windows only. Weblogic's RMI is currently not supported.

Remote classes

A remote class is any class that directly implements a remote interface; and a remote interface is any interface that extends "java.rmi.Remote". All methods in a remote interface must declare throwing a "RemoteException", or you will receive an error during stubs generation (or even worse - at runtime). Typically remote classes extend the java.rmi.server.UnicastRemoteObject.

RMI Project properties

It is possible to change the flags used for the RMI compilation. These flags can be changed in the project's "RMI Compiler Properties" properties page. In order to open this page, right click a project that has stubs generation enabled, and select "Properties" from the context menu. All the properties are described below.

Protocol Selection

There are two versions of the RMI protocol. Without going into further details the main difference from the developer's perspective is that v1.1 protocol requires both stub files and skeletons, while v1.2 protocol only requires stub files. The version numbers are the version numbers of the corresponding Java releases - JDK 1.1 (released in 1997) and JDK 1.2 (released in 1998). So both protocols are quite old and v1.2 protocol is used in most applications today. Unless you're working with a very old code base you should stay with the (now) default -v1.2.
Note: While the default protocol version in the RMI Plug-in for Eclipse is always -v1.2 the default of JDK1.4's command line tool is -vcompat and since JDK 1.5, the command line default is also -v1.2.

Other flags

-g

Generate debug information (on by default). There is no real reason why you would like to turn it off.
When you export the generated files to a jar file you might see the following warning:

JAR export finished with warnings. See details for additional information.
Exported with compile warnings: /sun-rmi-tutorial-server/engine/ComputeEngine.java Could not find source file attribute for: ComputeEngine_Stub.class Source name not found in a class file - exported all class files in /sun-rmi-tutorial-server/engine


The reason for this error message is that "rmic" does not generate all debug attributes. The warning is harmless , but in order to get rid of it, you should use the "-keep" flag.

-keep

Generate the source (.java) files of the stub classes. Use this flag to get rid of the warnings during export or if you just want to check what a stub file looks like.

Invoke the compiler inside Eclipse VM

This option, which is on by default, instructs the RMI Plug-in for Eclipse to load the RMI compiler (rmic) code into the Eclipse VM and invoke it internally. When the option is unchecked, the RMI Plug-in will locate the command line version of the RMI compiler and invoke it in a separate process. Obviously invoking the compilation inside the Eclipse VM is much faster. However, internal invocation may not work in all cases. In particular, if project's JDK version is not the same as the Eclipse JDK version, internal compilation is likely to fail. The RMI Plug-in for Eclipse tries to detect the cases in which internal compilation is going to fail and automatically switches to external compilation (regardless of this option).
See the help item about "tools.jar" location for additional informaiton about internal compilation.

Non-standard "tools.jar" location

This setting is only available if the "Invoke compiler inside Eclipse VM" option is checked and is usually not needed on MacOSX installations.

The RMI compiler that comes with a JDK installation is implemented as a set of classes in the tools.jar file. Usually this file is located in the lib/ subdirectory of the JDK installation. Sometimes, when Eclipse did not properly configure the JDK locations, the RMI Plug-in for Eclipse might not find the tools.jar file in the location where it is expected to be found. In such case, you should first try to configure the JDK locations in Eclipse. If for some reason it does not help, you can manually specify the location of the tools.jar file using this setting. It is best to use a tools.jar file that belongs to a JDK version at least the same as the project's JDK. If you still expericece problems, please read about troubleshooting.

Few technical notes: When the Eclipse VM internally loads the RMI compiler it expects to recognize the .class file format of the RMI compiler classes (the class file file version). So if the Eclipse VM is a JDK 1.4 (understands class file versions up to 48.0) and the compiler belongs to JDK 1.5 (class file version is 49.0), Eclipse may fail to load the compiler classes. In such case, you should use JDK 1.5 to run Eclipse [1.4 is too old anyway] (read more about using the -vm switch). On the other hand if your project is developed using JDK 1.4 and the Eclipse VM is JDK 1.5, the RMI compiler code (which expects 1.4 classes, up to class version 48.0) won't be able to run since it can't process the other classe that are already loaded in the Eclipse VM (JDK 1.5 classes have class file version 49.0). The solution for such situation is to use a tools.jar file from a JDK 1.5 installation. It works well with the Eclipse VM and the produced classes are still compatible with your code. Another solution to all tools.jar problems is of course using external compilation.

The following table summarizes the working Eclipse VM/Project's JDK configurations:

Project's VM

1.4 1.5 1.6

Eclipse VM

1.4+

External compilation only

External compilation only

1.5

Can use "tools.jar" from a JDK 1.5 installation.

+

External compilation only

1.6

Can use "tools.jar" from a JDK 1.6 installation.

Can use "tools.jar" from a JDK 1.6 installation.

+

Detect hierarchy changes of remote classes

The RMI Plug-in for Eclipse tries to minimize the number of times stub files are generated. In some situations it is possible that stubs generation won't be run when the class hierarchy of the remote class changes. This options, when checked, instructs the RMI Plug-in for Eclipse to look for possible hierarchy changes of the remote classes. Note: turning this option on may hurt performance on projects with lots of remote classes (and therefore the default is off).

Stubs and Java 5.0

Although since Java 5.0 you don't have to generate the stubs explicitly (under some limitations), it is a good idea to do so. More information can be found here.

RMI-IIOP and Corba support

The RMI Plug-in for Eclipse does not support these two protocols. Corba has been very popular in the late 1990's but its popularity has dropped since then, and new technologies such as web services took over. Only few new projects use Corba today. A very illuminating article by Michi Henning has been published in the "ACM Queue" in June 2006. Get the link and discuss the article here. There isn't much demand for RMI-IIOP either, but if you need such support feel free to contact us for possible solutions.


© 2002-14 Genady Beryozkin, rmi-info@genady.net. Read our Privacy policy. Hosted on RimuHosting. Visit Javalobby.