KaRMI: Efficient RMI for Java

On this page, you will find information that you will need, if you plan to use KaRMI without JavaParty stand-alone in your application. If you use JavaParty for KaRMI, you need not care about these details, because the JavaParty compiler does everything for you.

KaRMI Features

KaRMI is a fast drop-in replacement for the Java remote method invocation package (RMI). It is based on an efficient object serialization mechanism called uka.transport that replaces regular Java serialization from the java.io package. KaRMI and uka.transport are implemented completely in Java without native code. KaRMI also supports non-TCP/IP communication networks such as Myrinet/GM and Myrinet/ParaStation. It can also be used in clusters interconnected with heterogenous communication technology.

Even on 100MBit/s Ethernet networks, you can expect a strongly reduced overhead of remote method invocations. Between Intel Pentium III 800MHz nodes, KaRMI performs a remote void ping() call in 170μs over 100MBit/s Ethernet and in 40μs over Myrinet/ParaStation. Details can be found in the paper "A More Efficient RMI for Java" in the papers section.

KaRMI License

KaRMI can be used free of charge, either in open-source or proprietary software projects according to the GNU Lesser General Public License.

KaRMI: Efficient remote method invocation for Java.
Copyright (C) 1999 Christian Nester
Copyright (C) 2000-2002 Bernhard Haumacher

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.

Note: This license does not cover karmic the KaRMI stub and skeleton generator. karmic is part of the JavaParty compiler and the same license terms as for the JavaParty compiler apply to karmic: You can freely use karmic, all generated code in source and binary form is yours. At the moment there is no possibility to get the source code of karmic.

Setup

Your KaRMI application at runtime

If you did not made use of any special KaRMI features as described in the next section, you do not need anything more to run your application as including the archive karmi.jar in your application class path.

If you need further configuration, pleas refer to the section dealing with export points in the next section.

Although KaRMI was designed as drop-in replacement for regular RMI, here are some features that have different semantics in KaRMI. This was necessary, because RMI is bound to regular TCP/IP networks, but KaRMI was designed for usage in workstation clusters with high performance non-standard network hardware. Other features of RMI are not supported in KaRMI at all, because they are thought to be less relevant for cluster computing.

Export points instead of ports

With RMI, you can export an object at an arbitrary TCP/IP port. Since KaRMI is not bound to TCP/IP, an object export to a specific port has no meaning in KaRMI: No all supported transport technologies are required to support TCP/IP or even TCP/IP-style ports.

KaRMI therefore replaces ports with export points. Like a port, an export point is identified by a single integer number. The mapping of the export point to its meaning for a specific transport technology must be specified separately in the KaRMI configuration file.

As an example, assume you would like to export an object of class MyServer to the TCP/IP port 4711. In RMI, you would write the following code:

class MyServer extends UnicastRemoteObject {
  public MyServer() throws RemoteException {
    super(4711);
  }
}

MyServer myserver = new MyServer();

In the above RMI code, the meaning of 4711 is the TCP/IP port with the number 4711. If you write the same code with KaRMI, the meaning of 4711 is different: In KaRMI the above code means to export the object of class MyServer on the custom export point with the number 4711. Without further configuration, your program will fail at runtime, because this custom export point is not configured.

Configuring an export point means to install a mapping of the export point number to an export specification for all or some supported transport technologies. This mapping is provided in the KaRMI runtime configuration file called karmi.properties. The search order for the property file at runtime is the following:

KaRMI checks, whether a runtime property with the name
```
uka.karmi.config
```
is passed to the virtual machine. If that property is given, KaRMI reads its value and interprets it as file name, where to load the runtime configuration.
KaRMI tries to load the file
```
~/.karmi.property
```
from your home directory. If this file exists, its contents is read and interpreted as the KaRMI runtime configuration.

Note: this step was first introduced in KaRMI version 1.06d.
If all the above steps fail, KaRMI falls back to its built-in configuration file
```
uka/karmi/rmi/karmi.properties
```
distributed in the archive karmi.jar.

To configure a mapping for the custom export point 4711, you have to provide your custom KaRMI runtime configuration file. This can be done most easily by extracting the file form the archive karmi.jar, modifying it and passing its new location to the KaRMI runtime system as described above.

The following line in the default KaRMI configuration file specifies the mapping for the export point the KaRMI registry is exported on:

karmi.technology.3.export.1099.port = 1099

This configures export point 1099 of technology 3. Since technology 3 is defined to be the socket technology some lines above in the configuration file, this mapping specifies the export point 1099 to be bound to the TCP/IP port 1099. To add a custom export point 4711 that should be bound to the TCP/IP port 1234, add the following line to your configuration file:

karmi.technology.3.export.4711.port = 1234

This mechanism can also be used to define an user specific port for the registry, to run different programs on the same machine that all have their own registry. If you modify the line in your KaRMI configuration file that defines the mapping for the export point 1099, you can request to use TCP/IP port 1200 for your registry instead of the default port 1099.

karmi.technology.3.export.1099.port = 1200

Unsupported remote class loading

RMI is able to download classes that can not be found locally from a specified HTTP server. This feature is not implemented in KaRMI, since KaRMI is designed for usage in cluster environments, where the nodes are supposed to have a common network file system to load the application classes from.

Unsupported object activation

RMI supports persistent server objects that sleep on disk and are waken up, if a call arrives. This feature is not implemented in KaRMI, because KaRMI is mainly used for high performance applications on clusters, where all objects are active until the application terminates.

No interoperability with RMI

It could be useful to have a high performance server application running on a cluster of workstations powered by KaRMI, while client connections are based on standard RMI. This is currently not implemented in KaRMI. If you try to pass KaRMI references in RMI remote method invocations, your program is likely to crash or experience strange results.

JavaParty