DRL Remote Method Invocation Framework

Revision History

Disclaimer and Legal Information

About This Document

Purpose

Intended Audience

Documentation Conventions

RMI Overview

RMI in DRL

About

Features

System Properties

RMI Registry

RMI Activation

RMI Compiler

References

Revision History

Version Version Information Date
Initial version Vasily Zakharov, Nadya Morozova, Svetlana Konovalova: document created. March 23, 2006

Disclaimer and Legal Information

Copyright 2005-2006 The Apache Software Foundation or its licensors, as applicable.

Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

About This Document

Purpose

This document describes the DRL implementation of the Remote Method Invocation (RMI) framework [1] and gives details on the framework design.

Intended Audience

The target audience for the document includes a wide community of engineers interested in using the RMI framework in their applications and in further work with the product to contribute to its development. The document assumes that readers are familiar with RMI and the Java* programming language.

Documentation Conventions

This document uses the unified conventions for the DRL documentation kit.

Back to Top

RMI Overview

The Remote Method Invocation (RMI) framework enables an object in one virtual machine to call methods of an object in another one, to create applications distributed on various Java* virtual machines on the same or different hosts.

Back to Top

RMI in DRL

About

The RMI framework is an independent implementation of RMI [1].

Back to Top

Features

The DRL RMI implementation is based on public APIs only, so that plugging DRL RMI into other Java* class libraries requires no modifications. No native code or VM implementation dependencies are present.

The DRL RMI framework supports versions 1.1 and 1.2 of the RMI protocol, but not the deprecated multiplexing protocol.

The product implements the Java* 1.5.0 dynamic proxy stubs generation represented by:

Fully-featured logging is implemented both through the command line and through the common logging mechanism in the java.util.logging package.

Back to Top

System Properties

The RMI framework supports the general java.rmi.* properties and the implementation-specific harmony.rmi.* properties. You can also consult additional resources on RMI properties [2] and [3].

Back to Top

RMI Registry

The RMI Registry maps names to remote objects, so that you can look them up by names later.

The DRL RMI implementation does not contain the rmiregistry binary tool.

Instead of this tool, run:

java org.apache.harmony.rmi.registry.RegistryImpl [port]

For [port], use the number of the port where you need to start the registry. Otherwise, the registry starts at port 1099.

Back to Top

RMI Activation

The RMI activation framework is a mechanism for lazy initialization of RMI services. The activation framework consists of the RMI activation daemon (RMID) and a set of auxiliary classes in the java.rmi.activation package, which register services in RMID and use them.

RMI Activation Daemon

The DRL RMI framework does not contain the rmid binary tool.

Instead of this tool, run:

java org.apache.harmony.rmi.activation.Rmid [options]

For [options], you can use the the rmid binary tool options. The only exception is the -J options, which you must pass directly to the Java* virtual machine.

RMID Monitoring

You can plug an external agent to monitor the RMID internal state. To turn on this feature, use the -monitor command-line option.

You can specify your own implementation of the org.apache.harmony.rmi.activation.RmidMonitor interface by defining the org.apache.harmony.rmi.activation.monitor property. Otherwise, the default empty monitor implementation is used.

Example
java -Djava.security.policy=rmid.policy
     -Dorg.apache.harmony.rmi.activation.monitor=my.package.MyMonitor
     org.apache.harmony.rmi.activation.Rmid -monitor

Custom activation groups

The DRL RMI daemon provides full support for custom activation groups in accordance with the specification [1].

Persistence

The RMI daemon saves its state into two files in the log subdirectory of the current directory on the hard drive.
To change the default location of the files, use the -log option.

Note

The files' format is incompatible with the reference implementation format.

Back to Top

RMI Compiler

The RMI compiler generates stubs and skeletons for remote objects.

The DRL RMI framework does not contain the rmic binary tool.
Instead of this tool, run:

java org.apache.harmony.rmi.compiler.Main [options] <class name>

Class loading

During this operation, the RMI compiler uses the system class loader, which sets certain limitations on its configuration. If you use the -classpath or the -bootclasspath option, make sure that you set the corresponding options for Java* virtual machine running the compiler. If you do not specify the proper options, Class not found errors might occur or system classes might be used instead of the ones specified in the -bootclasspath option.

Example
java -classpath path1:path2 -Xbootclasspath:path3:path4 
     org.apache.harmony.rmi.compiler.Main -classpath path1:path2
     -bootclasspath path3:path4 [other options] <class names>

Note

The compiler does not support the -extdirs option.

Locating the Java* compiler

To compile the generated stubs, DRL RMIC uses the Eclipse* compiler or another external Java* compiler. To locate the external compiler, the RMIC implementation uses the following algorithm, checking the following system properties and environment variables:

  1. If the org.apache.harmony.rmi.compiler.class property is set, use the specified class as a Java* compiler class and move to the next step. Otherwise, move to step 3.
  2. If the org.apache.harmony.rmi.compiler.method property is set, call the specified method and skip further steps. Otherwise, call the main method and skip further steps. The resulting method is the compilerClass.compilerMethod(String[]) method.
  3. If the org.apache.harmony.rmi.compiler.executable property is set, run the specified executable and skip further steps.
  4. If the CLASSPATH contains the org.eclipse.jdt.internal.compiler.batch.Main Eclipse* compiler class, use the specified class and skip further steps.
  5. If the ECLIPSE_HOME environment variable is set and the Eclipse* compiler .jar file (ECLIPSE_HOME/plugins/org.eclipse.jdt.core_*.jar) is present, load the Eclipse* compiler class from the .jar archive and skip the last step.
  6. If the JAVA_HOME environment variable is set and the JAVA_HOME/bin/javac executable is present, run the specified executable.

If all the steps failed, RMIC executes javac to search for the compiler in the system PATH variable. If RMIC does not find the compiler, it aborts the operation with error.

IIOP and IDL support

DRL RMIC does not support Internet inter-orb protocol (IIOP) and interactive data language (IDL) stub generation, and, consequently, the options -iiop, -idl, -always, -alwaysgenerate, -nolocalstubs, and -noValueMethods.

Back to Top

References

[1] RMI Specification, http://java.sun.com/j2se/1.5.0/docs/guide/rmi/spec/rmiTOC.html

[2] java.rmi Properties, http://java.sun.com/j2se/1.5.0/docs/guide/rmi/javarmiproperties.html

[3] sun.rmi Properties, http://java.sun.com/j2se/1.5.0/docs/guide/rmi/sunrmiproperties.html 

Back to Top

(C) Copyright 2005-2006 Intel Corporation

* Other brands and names are the property of their respective owners.