Java IDL: The "Hello World" Example

This document is a high-level overview of how to create a complete CORBA (Common Object Request Broker Architecture) application using IDL (Interface Definiton Language) to define interfaces and the Java IDL compiler to generate stubs and skeletons. For more information on the development process, and a more detailed tutorial on creating a CORBA application using IDL, link to Getting Started with Java IDL: The Hello World Tutorial. You can also create CORBA application by defining the interfaces in the Java programming language. For more information and a tutorial on this development process, link to Java RMI-IIOP documentation.

Folow the link to Changes is Java IDL between JDK 1.2 and J2SE 1.3 for an explanation of the changes that have occurred in Java IDL between releases.

This document contains:

• The IDL for a simple "Hello World" program
• A transient server that creates an object and registers it in a naming context
• An application client and an applet that know the object's name, retrieve a reference for it from the naming context, and invokes the object
• An that does the same
• Instructions for compiling and running the example

Defining the Interface (Hello.idl)

The following example OMG IDL describes a CORBA object whose single sayHello() operation returns a string.

module HelloApp
{
    interface Hello
    {
        string sayHello();
    };
};

To complete the application, you simply provide the server (HelloServer.java) and client (HelloClient.java or HelloApplet.java) implementations.

Implementing the Server (HelloServer.java)

The example server consists of two classes, the servant and the server. The servant, HelloServant, is the implementation of the Hello IDL interface; each Hello instance is implemented by a HelloServant instance. The servant is a subclass of _HelloImplBase, which is generated by the idlj compiler from the example IDL. The servant contains one method for each IDL operation, in this example, just the sayHello() method. Servant methods are just like ordinary Java methods; the extra code to deal with the ORB, with marshaling arguments and results, and so on, is provided by the server and the stubs.

The server class has the server's main() method, which:

• Creates an ORB instance
• Creates a servant instance (the implementation of one CORBA Hello object) and tells the ORB about it
• Gets a CORBA object reference for a naming context in which to register the new CORBA object
• Registers the new object in the naming context under the name "Hello"
• Waits for invocations of the new object

For more discussion of the code, see the detailed tutorial topic Getting Started with Java IDL: Developing a Hello World Server.

// Copyright and License 

import HelloApp.*;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.CORBA.*;
 
class HelloServant extends _HelloImplBase 
{
    public String sayHello()
    {
	return "\nHello world !!\n";
    }
}

 
public class HelloServer {
 
    public static void main(String args[])
    {
	try{
	    // create and initialize the ORB
	    ORB orb = ORB.init(args, null);
 
	    // create servant and register it with the ORB
	    HelloServant helloRef = new HelloServant();
	    orb.connect(helloRef);
 
	    // get the root naming context
	    org.omg.CORBA.Object objRef = 
		orb.resolve_initial_references("NameService");
	    NamingContext ncRef = NamingContextHelper.narrow(objRef);
 
	    // bind the Object Reference in Naming
	    //make sure there are no spaces between ""
	    NameComponent nc = new NameComponent("Hello", "");
	    NameComponent path[] = {nc};
	    ncRef.rebind(path, helloRef);
 
	    // wait for invocations from clients
            java.lang.Object sync = new java.lang.Object();
            synchronized (sync) {
                sync.wait();
            }
 
	} catch (Exception e) {
	    System.err.println("ERROR: " + e);
	    e.printStackTrace(System.out);
	}
    }
}
 

The example application client that follows:

• Creates an ORB
• Obtains a reference to the naming context
• Looks up "Hello" in the naming context and receives a reference to that CORBA object
• Invokes the object's sayHello() operation and prints the result

For more discussion of the details of the code, link to Getting Started with Java IDL: Developing a Client Application.

// Copyright and License 
 
import HelloApp.*;
import org.omg.CosNaming.*;
import org.omg.CORBA.*;
 
public class HelloClient 
{
    public static void main(String args[])
    {
	try{
	    // create and initialize the ORB
	    ORB orb = ORB.init(args, null);
 
            // get the root naming context
            org.omg.CORBA.Object objRef = orb.resolve_initial_references("NameService");
            NamingContext ncRef = NamingContextHelper.narrow(objRef);

            // resolve the Object Reference in Naming
            // make sure there are no spaces between ""
            NameComponent nc = new NameComponent("Hello", "");
            NameComponent path[] = {nc};
            Hello helloRef = HelloHelper.narrow(ncRef.resolve(path));
 
	    // call the Hello server object and print results
	    String hello = helloRef.sayHello();
	    System.out.println(hello);
 
	} catch (Exception e) {
	    System.out.println("ERROR : " + e) ;
	    e.printStackTrace(System.out);
	}
    }
}

 

The example applet client that follows:

• Creates an ORB
• Obtains a reference to the naming context
• Looks up "Hello" in the naming context and receives a reference to that CORBA object
• Invokes the object's sayHello() operation and prints the result

For more discussion of the client applet code, link to Getting Started with Java IDL: Developing a Client Applet.

// Copyright and License 

import HelloApp.*;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.CORBA.*;
import java.awt.Graphics;
 
public class HelloApplet extends java.applet.Applet 
{
    public void init() {
	try {
	    // create and initialize the ORB
            ORB orb = ORB.init(this, null);

            // get the root naming context
            org.omg.CORBA.Object objRef = 
		        orb.resolve_initial_references("NameService");
            NamingContext ncRef = NamingContextHelper.narrow(objRef);

            // resolve the Object Reference in Naming
            NameComponent nc = new NameComponent("Hello", "");
            NameComponent path[] = {nc};
            Hello helloRef = HelloHelper.narrow(ncRef.resolve(path));

            // call the Hello server object and print results
            message = helloRef.sayHello();
 
	} catch (Exception e) {
	    System.out.println("HelloApplet exception: " + e.getMessage());
	    e.printStackTrace(System.out);
        }
    }
 

    public void paint(Graphics g) 
    {
	g.drawString(message, 25, 50);
    }
 
    String message = "";
}
 

Once you've written an applet, you need to add it to an HTML page so that you can try it out. You do this by adding an <APPLET> tag to the basic HTML shell. When you have completed this step, you can run your applet using the Applet Viewer or from a J2SE v1.3-enabled Web browser.

The example HTML file, Tutorial.html, would look like this:

<HTML>
<!--Copyright 2000, Sun Microsystems, Inc. -->
<HEAD>
   <TITLE>Getting Started with Java IDL: Running HelloApplet</TITLE>
   <X-SAS-WINDOW TOP=42 BOTTOM=477 LEFT=4 RIGHT=534>
</HEAD>
<BODY BGCOLOR="#FFFFFF">


<H1 ALIGN=CENTER>Running the Hello World Applet</H1>
<HR>

<P>If all goes well, the applet appears below:

<P>
<APPLET CODE=HelloApplet.class 
        CODEBASE='enter_the_path_to_your_project_directory_here'
        WIDTH=500 
        HEIGHT=300>
<PARAM name="org.omg.CORBA.ORBInitialHost" value=enter_server_machine_name>
<PARAM name="org.omg.CORBA.ORBInitialPort" value=1050>
</APPLET>


</BODY>
</HTML>

Despite its simple design, the Hello World program lets you learn and experiment with all the tasks required to develop almost any CORBA program that uses static invocation. To run this client-server application on your development machine:

When running this example, remember that the default port number is 900. When using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024. The -ORBInitialPort option is used to override the default port number in this example. The following instructions assume you can use port 1050 for the Java IDL name server. You can substitute a different port if necessary. When running these examples on a Windows machine, subtitute a backslash (\) in path names.

1. Change to the directory that contains the file Hello.idl.

2. Run the IDL-to-Java compiler, idlj, on the IDL file to create stubs and skeletons.
   

      idlj -fall  Hello.idl
   

   You must use the -fall option with the idlj compiler to generate both client and server-side bindings. For more information on the idlj options, link to IDL-to-Java compiler options.

   The idlj compiler generates a number of files. The actual number of files generated depends on the options selected when the IDL file is compiled. The generated files provide standard functionality, so you can ignore them until it is time to deploy and run your program. The files generated by the idlj compiler for Hello.idl, with the -fall command line option, are:

   _HelloImplBase.java

   This abstract class is the server skeleton, providing basic CORBA functionality for the server. It implements the Hello.java interface. The server class HelloServant extends _HelloImplBase.

   _HelloStub.java

   This class is the client stub, providing CORBA functionality for the client. It implements the Hello.java interface.

   Hello.java

   This interface contains the Java version of our IDL interface. The Hello.java interface extends org.omg.CORBA.Object, providing standard CORBA object functionality.

   HelloHelper.java

   This final class provides auxiliary functionality, notably the narrow() method required to cast CORBA object references to their proper types.

   HelloHolder.java

   This final class holds a public instance member of type Hello. It provides operations for out and inout arguments, which CORBA allows, but which do not map easily to Java's semantics.

   HelloOperations.java

   This interface contains the single method sayHello(). The IDL-to-Java mapping puts all of the operations defined on the IDL interface into this file, which is shared by both the stubs and skeletons.

3. Compile the .java files, including the stubs and skeletons (which are in the directory HelloApp):

      javac *.java HelloApp/*.java
   

4. Start the Java IDL Name Server. To do this from a UNIX command shell, enter:

        tnameserv -ORBInitialPort 1050&
   

   From an MS-DOS system prompt (Windows), enter:

        start tnameserv -ORBInitialPort 1050
   

   Note that 1050 is the port on which you want the name server to run. If you do not specify this, port 900 will be chosen by default. Also note that when using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024.

5. Start the Hello server:

      java HelloServer -ORBInitialHost namerserverhost -ORBInitialPort 1050
   

   Note that nameserverhost is the host on which the IDL name server is running. You can omit -ORBInitialHost nameserverhost if the name server is running on the same host as the Hello server. You can leave out -ORBInitialPort 1050 if the name server is running on the default port.

6. Run the Hello application client or applet from a different shell than the server:
   • To run the client application,
     1. From another DOS prompt or shell, type:

           java HelloClient  -ORBInitialHost namerserverhost -ORBInitialPort 1050
        

        Note that nameserverhost is the host on which the IDL name server is running. You can omit -ORBInitialHost nameserverhost if the name server is running on the same host as the Hello client. You can leave out -ORBInitialPort 1050 if the name server is running on the default port.

   • To run the applet from the appletviewer,
     1. Open another prompt or shell.
     2. Change to the applet directory, HelloApp.
     3. Start the appletviewer and browse Tutorial.html by typing:

           appletviewer Tutorial.html

When you have finished this tutorial, be sure to shut down the server, or to kill the server process. From a DOS prompt, select the window that is running the server and enter Ctrl+C. From a Unix shell, find the process, and select Kill. The server will continue to wait for invocations until it is explicitly stopped.

Running the Hello World Application on 2 Machines describes one way of distributing the simple application across two machines - a client and a server.