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.
- Change to the directory that contains the file Hello.idl.
- 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.
- Compile the .java files, including the stubs and skeletons
(which are in the directory HelloApp):
javac *.java HelloApp/*.java
- 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.
- 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.
- Run the Hello application client or applet from a different shell than the server:
- To run the client application,
- 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,
- Open another prompt or shell.
- Change to the applet directory, HelloApp.
- 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.
Copyright © 1995-2000
Sun Microsystems, Inc.
All Rights Reserved.