Chapter 9. RMI Tools

rmic	JDK 1.1 and later
The Java RMI Compiler

rmic [ options ] fully-qualified-classnames

Description: The rmic compiler generates the stub and skeleton classes for remote objects you've written. Once you've compiled your remote objects using a standard Java compiler, like javac, you need to run rmic, specifying the classnames of your remote implementation classes using their full package names.

Description: As an example, suppose you defined an interface named utils.remote.TimeServer that extends java.rmi.Remote, and wrote an implementation of this interface named utils.remote.TimeServerImpl. After compiling both with a Java compiler, you would run rmic, specifying utils.remote.TimeServerImpl as the class name argument.

Description: Running rmic generates a skeleton class for each remote object type named xxx_Skel, where the xxx is the name of the remote interface. The skeleton is responsible for receiving client requests on a server object and dispatching these requests to the actual remote object. A stub class, named xxx_Stub, is also generated. The stub class is used for client references to the remote object. When a client gets a reference to a remote object, it receives an instance of the stub class, which forwards any method requests to the server object over the network. In our example, the stub and skeleton classes would be called utils.remote.TimeServer_Stub and utils.remote.TimeServer_Skel, respectively.

Description: Both the stub class and the skeleton class implement the same remote interface as your remote object implementation, so they can be typecast to the remote interface.

-classpath pathlist

Provides the classpath rmic uses to find any required classes, overriding the environment CLASSPATH or the default classpath. The directories in the list are separated by colons on Unix environments, by semicolons in Windows environments.

-d path

The destination directory where the compiler should write the generated class files. If a -d option is given, the package of the generated classes places the stubs and skeletons in their proper subdirectories in the given destination. If the directories don't exist, rmic creates them for you. If no -d option is given, the stubs and skeletons are still generated to fall within the same package as the remote implementation, but the class files are placed in the current directory.

-depend

Forces the compiler to attempt to recompile interdependent classes whose class files are out of date with each other. Without this option, the compiler attempts to recompile only class files explicitly referenced in the command-line options.

-g

Includes debugging information in the generated stub and skeleton classes, for use with Java debuggers.

-J

Passes the option immediately following the -J to the Java interpreter. There should be no spaces between the -J and the option to be passed to the interpreter.

-keep

-keepgenerated

Keeps the Java source files for the stub and skeleton classes generated by the compiler. The Java files are written to the same directory as the class files, with or without a -d option specified. Without the -keepgenerated option, the Java source files are removed after the stub and skeleton classes are generated.

-nowarn

Instructs the rmic compiler to eliminate warning messages from its output. Only errors encountered during compilation are reported.

-vcompat

Creates a stub and skeleton classes that are compatible with both JDK 1.1 and the Java 2 SDK 1.2 versions of RMI. This option is enabled by default and does not need to be specified.

-verbose

Prints verbose messages as compilation takes place, including which class is being compiled and class files that are loaded during compilation.

-v1.1

Creates stub and skeleton classes that are compatible with the JDK 1.1 version of RMI. These classes may not run in a Java 2 runtime environment.

-v1.2

Creates stub and skeleton classes that are compatible with the Java 1.2 (Java 2) version of RMI. These classes may not run in a Java 1.1 runtime environment.

CLASSPATH

An ordered list of directories, ZIP files, and/or JAR files that the rmic compiler should use to look for classes. This list is separated by colons on Unix environments, semicolons on Windows environments. The list is searched in order for a given class when it is encountered during compilation. The compiler automatically appends the system classpath to the CLASSPATH, if it is specified. If the CLASSPATH is not set in the environment, the compiler uses the current directory and the system classpath as its classpath. The CLASSPATH environment variable is overridden by the -classpath option to rmic.

rmiregistry	JDK 1.1 and later
The Java RMI Object Registry

rmiregistry [ port ]

Description: The rmiregistry command starts a remote object naming registry on the current host. The RMI registry binds remote objects to names, so that remote clients can request object references by name, using a URL-like syntax, and use the object references to invoke methods.

Description: Internally, the rmiregistry command uses the java.rmi.registry.LocateRegistry class to instantiate a registry object. If no port is provided, the default port for the registry is 1099. Typically, the registry is run in the background on a server and remains running for the lifetime of the objects that it contains. If the registry crashes, and the registry is running in a separate Java VM from the actual remote objects, the remote objects are still available over RMI, and any remote references to these objects that existed before the crash are still valid. But all the name bindings the objects had in the registry are lost and need to be recreated after a new registry is started.

CLASSPATH

An ordered list of directories, ZIP files, and/or JAR files that the rmiregistry command should use to look for classes. This list is separated by colons on Unix environments, semicolons on Windows environments. The list is searched in order for a given class when it is encountered during execution. The registry automatically appends the system classpath to the CLASSPATH, if it is specified. If the CLASSPATH is not set in the environment, the daemon uses the current directory and the system classpath as its classpath.

See Also: java.rmi.registry.LocateRegistry, java.rmi.Naming.

rmid	Java2 SDK 1.2 and later
The RMI Activation Daemon

rmid [ options ]

Description: The rmid command starts an RMI activation daemon on the local host. The activation daemon services all requests to register activatable objects and is responsible for activating objects due to client requests to invoke methods on them.

Description: If no port option is given, the activation daemon runs on a default port of 1098. Internally, the activation daemon creates a java.rmi.activation.Activator and its own RMI naming registry (listening to port 1098). The daemon binds a java.rmi.activation.ActivationSystem object to the name "java.rmi.activation.ActivationSystem" in its internal registry.

-CcmdlineOption

Uses the given option as a command-line option to the Java VM for each activation group started by the daemon. This can pass default properties to the VM, for example, or set its memory limits to some default value. The Java interpreter option should immediately follow the -C option, with no spaces.

-log path

Uses the given directory for any logging or temporary files needed by the activation daemon. If this option is not specified, the daemon writes its log files to a new directory named log in the current directory.

-port portnum

Uses this port for the internal registry started by the activation daemon. If this option is not given, the daemon's internal naming registry runs by default on port 1098 of the local host. If you want the activation daemon's registry to listen to the default registry port, you can start the daemon with this command (Unix version):

$ rmid -port 1099 &

-stop

Stop any activation daemon currently running on the specified port, or the default port if none is specified.

CLASSPATH

An ordered list of directories, ZIP files, and/or JAR files that the rmid daemon should use to look for classes. This list is separated by colons on Unix environments, semicolons on Windows environments. The list is searched in order for a given class when it is encountered during execution. The daemon automatically appends the system classpath to the CLASSPATH, if it is specified. If the CLASSPATH is not set in the environment, the daemon uses the current directory and the system classpath as its classpath.

See Also: rmic, java.rmi.activation.Activator

serialver	JDK 1.1 and later
The RMI Serial Version Utility

serialver [ options ] fully-qualified-classnames

Description: The serialver utility generates a serial version ID you can use to mark a given class definition to track its versions as it evolves. The utility returns a static int member declaration you can paste into your Java class definition. In other words, this command:

% serialver AccountImpl

Description: generates output something like:

AccountImpl: static final long serialVersionUID = 37849129093280989384L;

Description: If versioning of your remote object classes becomes a problem for clients, this utility can tag a class with a version ID that can be checked to see if the proper version is being exported by your server for a given client, or if its local version is out of date. Serial version IDs are used by Java object serialization to uniquely identify class definitions.

-show

Uses the graphical version of the tool, which displays a GUI interface that allows you to type in a fully qualified classname and press a button to see the serial version ID generated.

CLASSPATH

An ordered list of directories, ZIP files, and/or JAR files that the serialver utility should use to look for classes. This list is separated by colons on Unix environments, semicolons on Windows environments. The list is searched in order for a given class when it is encountered during execution. The utility automatically appends the system classpath to the CLASSPATH, if it is specified. If the CLASSPATH is not set in the environment, the utility uses the current directory and the system classpath as its classpath.