# 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();
        };
    };

NOTE: When writing code in OMG IDL, do not use an interface name as the name of a module. Doing so runs the risk of getting inconsistent results when compiling with tools from different vendors, thereby jeopardizing the code's portability. For example, code containing the same names could be compiled with the IDL to Java compiler from Sun Microsystems and get one result. The same code compiled with another vendor's IDL to Java compiler could produce a different result.

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);
    	}
        }
    }

## Implementing the Client Application (`HelloClient.java`)

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);
    	}
        }
    }

## Implementing the Applet Client (`HelloApplet.java`)

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>

## Building and Running Hello World

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.

Home

Copyright © 1995-2000 Sun Microsystems, Inc. All Rights Reserved.