The Community OpenORB - RMIoverIIOP

This tutorial is divived into several steps that provide an overview of what is important to know to write RMI applications. All source code used for this tutorial is available in the examples directory of the distribution.

A first application : Hello world !

The source code of this first example is available in examples/hello. First, let's have a look at the remote interface description in the RemoteEcho.java file.

            package hello;

			interface RemoteHello extends java.rmi.Remote
			{
	  		    public void print( String message )
			    throws java.rmi.RemoteException;
			}
            

RMI over IIOP does not require additional rules to define remote interfaces:

To implement a remote interface there is no specific requirement from RMI over IIOP. However, the server class which starts the application has to inherit from javax.rmi.PortableRemoteObject. Moreover, JNDI must be used to bind and to resolve an object reference.

The following source code implements the above interface.

            package hello;

			import javax.naming.InitialContext;

			public class HelloServer
			    extends javax.rmi.PortableRemoteObject
			    implements RemoteHello
			{
			    public HelloServer()
                    throws java.rmi.RemoteException
			    { }
			    public void print( String message )
			        throws java.rmi.RemoteException
			    {
			        System.out.println( message );
			    }
			    public static void main(String args[])
			    {
        	        try
			        {
                        java.util.Properties env =
			                new java.util.Properties ();
         	            InitialContext context = new InitialContext(env);
			            HelloServer helloObj = new HelloServer();
			            context.bind("hello", helloObj );
			        }
			        catch ( Exception ex )
			        {
			            ex.printStackTrace();
			            System.out.println(ex.getMessage());
			        }
			    }
			}
            

Now, we have to compile this application : javac *.java

To be used with RMI over IIOP, the RMI object needs to have a skeleton ( for the server side ) and a stub ( for the client side ). To generate the skeleton and the stub, we have to use a dedicated tool provided with RMIoverIIOP for OpenORB.

This tool named JavaToIdl, provides the following features :

For this example, we are going to generate the stub, the skeleton and no IDL description ( see the next example to know how to generate and how to use an IDL interface for a remote interface ). To generate these artifacts, use the following command line: java org.openorb.rmi.compiler.JavaToIdl -tie -stub -noidl hello.RemoteHello

Now, two files have been generated:

Now, we have to compile these files... javac *.java The last step of this example is to write a client application.

            package hello;

			import javax.naming.InitialContext;

			public class HelloClient
			{
			    public static void main(String args[])
			    {
			        try
			        {
			            InitialContext context = new InitialContext();
			            Object obj = context.lookup ("hello");
			            RemoteHello hello = ( RemoteHello ) javax.rmi.PortableRemoteObject.narrow(obj, RemoteHello.class);
			            hello.print("Hello world !");
			        }
			        catch ( java.lang.Exception ex )
			        {
			            ex.printStackTrace();
			        }
			    }
			}
			

The above bold line is a very important rule in the RMI over IIOP specification :

All casts must be replaced by a call to the javax.rmi.PortableRemoteObject.narrow(...)

After the compilation of the previous class, we have to run the example. First, the CORBA Naming Service must be started ( see your OpenORB documentation ).

To run this application, several elements must be taken into account :

Indeed, the RMI applications use JNDI to bind the provided object. For RMI over IIOP, a special JNDI SPI must be used in order to bind supplied objects in the CORBA naming service. To specify such a JNDI SPI, the system property to set is java.naming.factory.initial. In the case of RMI over IIOP for OpenORB, the value to supply is org.openorb.rmi.jndi.CtxFactory. Thus, the command line is :

To start the server: java -Djava.naming.factory.initial=org.openorb.rmi.jndi.CtxFactory hello.HelloServer

To start the client: java -Djava.naming.factory.initial=org.openorb.rmi.jndi.CtxFactory hello.HelloClient

A CORBA client for the previous RMI object The first step is to generate the IDL description for the RMI object : java org.openorb.rmi.compiler.JavaToIdl hello.RemoteHello

The CORBA client application is very simple :

Here is the source code :

            public class HelloClient

			{
			    public static void main( String [] args )
			    {
			        System.out.println("Hello from CORBA...");
			        org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init(args,null);
			        org.omg.CosNaming.NamingContext naming = null;
			        try
			        {
			            org.omg.CORBA.Object obj =
			                orb.resolve_initial_references("NameService");
			            naming = org.omg.CosNaming.NamingContextHelper.narrow( obj );
			        }
			        catch ( org.omg.CORBA.ORBPackage.InvalidName ex )
			        { }
			        try
			        {
			            org.omg.CosNaming.NameComponent [] name = new
			            org.omg.CosNaming.NameComponent[ 1 ];
			            name[0] = new org.omg.CosNaming.NameComponent("hello","");
			            org.omg.CORBA.Object obj = naming.resolve( name );
			            hello.RemoteHello rmi = hello.RemoteHelloHelper.narrow( obj );
			            rmi.print("Hello World !");
			        }
			        catch ( java.lang.Exception ex )
			        {
			            System.out.println("Exception : " + ex.toString() );
			            System.exit(0);
			        }
			    }
			}
            

To test RMI over IIOP, you have to compile the test scripts provided with the distribution, it means to run the Ant script with the test keyword.

The tests provided with the distribution are developed to be run with JUnit. These tests check several aspects of the specification :

To apply the tests, please enter the following command : java org.openorb.rmi.test.RMIoverIIOPTest -execute

To be able to use RMI over IIOP, there are few rules to know but they are very important.

How to cast an object reference ?

It is not possible to directly use a java cast to cast a remote reference to an interface type. The RMI over IIOP specification requires to use the javax.rmi.PortableRemoteObject.narrow operation to cast a reference.

How to activate or deactivate a RMI object ?

To activate an object, it means to export a RMI object to RMI over IIOP ( as a CORBA object ), you have to use the javax.rmi.PortableRemoteObject.exportObject operation.

In the same way, to deactivate an object, i.e. to un-export a RMI object, you have to use the javax.rmi.PortableRemoteObject.unexportObject operation.

The JavaToIdl tool is a very important piece of the RMI over IIOP extension. This tool provides two main features :

It is very important to understand how to use this tool, because its usage is a mandatory step in the development process of a RMI application over IIOP.

To run this tool, please enter the following command : java org.openorb.rmi.compiler.JavaToIdl

The Java To IDL options can be seen by executing the tool without parameters.