Getting Started with Java IDL:
Writing the Interface Definition

Before you start working with Java IDL, you need to install
version 1.4 (or later) of the Java platform. Version 1.4 (and
later) provides the Application Programming Interface (API) and
Object Request Broker (ORB) needed to enable CORBA-based
distributed object interaction, as well as the idlj
compiler. The idlj compiler uses the IDL-to-Java language
mapping to convert IDL interface definitions to corresponding Java
interfaces, classes, and methods, which you can then use to
implement your client and server code.

This section teaches you how to write a simple IDL interface
definition and how to translate the IDL interface to Java. It also
describes the purpose of each file generated by the idlj
compiler.

Understanding the IDL file

OMG IDL is the language used to describe the interfaces that
client objects call and object implementations provide. An
interface definition written in OMG IDL completely defines the
interface and fully specifies each operation's parameters. An OMG
IDL interface provides the information needed to develop clients
that use the interface's operations.

Clients are written in languages for which mappings from OMG IDL
concepts have been defined. The mapping of an OMG IDL concept to a
client language construct will depend on the facilities available
in the client language. OMG specifies a mapping from IDL to several
different programming languages, including C, C++, Smalltalk,
COBOL, Ada, Lisp, Python, and Java. When mapped, each statement in
OMG IDL is translated to a corresponding statement in the
programming language of choice.

For example, you could use the tool idlj to map an IDL
interface to Java and implement the client class. When you mapped the
same IDL to C++ and implemented the server in that language, the Java
client (through the Java ORB) and C++ server (through the C++
ORB) interoperate as though they were written in the same
language.

The IDL for "Hello World" is extremely simple; its single
interface has but two operations. You need perform only three
steps:

A CORBA module is a namespace that acts as a
container for related interfaces and declarations. It corresponds
closely to a Java package. Each module statement in an IDL file is
mapped to a Java package statement.

The module statement looks like this:

module HelloApp
{
// Subsequent lines of code here.
};

When you compile the IDL, the module statement will generate a
package statement in the Java code.

CORBA operations are the
behavior that servers promise to perform on behalf of clients that
invoke them. Each operation statement in the IDL generates a
corresponding method statement in the generated Java interface.

In your Hello.idl file, the operation statement looks
like this:

module HelloApp
{
interface Hello
{
string sayHello(); // This line is an operation statement.
oneway void shutdown(); // This line is another
};
};

The interface definition for our little "Hello World" application
is now complete.

The tool idlj reads OMG IDL files and creates the
required Java files. The idlj compiler defaults to
generating only the client-side bindings. If you need both
client-side bindings and server-side skeletons (as you do for our
"Hello World" program), you must use the
-fall option when running the
idlj compiler. For more information on compiler options,
see the idlj man page
(Solaris, Linux, or Mac OS X or
Windows).

The default server-side mapping generated when either the
-fall or -fserver arguments are used conform to
Chapter 11, Portable Object Adapter (POA) of the CORBA
2.3.1 Specification (formal/99-10-07).
For more information on the POA, see Portable
Object Adapter.

The advantages of using the Portable Object Adaptor (POA)
are:

Allow programmers to construct object implementations that are
portable between different ORB products.

Provide support for objects with persistent identities.

Provide support for transparent activation of objects.

Allow a single servant to support multiple object identities
simultaneously.

Make sure that the jdk/bin directory (or the directory
containing idlj, java, javac, and
orbd) are in your path.

Go to a command line prompt.

Change to the directory containing your Hello.idl
file.

Enter the compiler command:

idlj -fall Hello.idl

If you list the contents of the directory, you will see that a
directory called HelloApp has been created and that it
contains six files. Open Hello.java in your text editor.
Hello.java is the signature interface and is used
as the signature type in method declarations when interfaces of the
specified type are used in other interfaces. It looks like
this:

With an interface this simple, it is easy to see how the IDL
statements map to the generated Java statements.

IDL Statement

Java Statement

module HelloApp

package HelloApp;

interface Hello

public interface Hello

The single surprising item is the extends statement.
All CORBA objects are derived from org.omg.CORBA.Object to
ensure required CORBA functionality. The required code is generated
by idlj; you do not need to do any mapping yourself.

In previous versions of the idlj compiler (known as
idltojava), the operations defined on the IDL interface
would exist in this file as well. Starting with J2SDK v1.3.0, in
conformance with the CORBA 2.3.1 Specification (formal/99-10-07),
the IDL-to-Java mapping puts all of the operations defined on the
IDL interface in the operations interface,
HelloOperations.java. The operations interface is used in
the server-side mapping and as a mechanism for providing optimized
calls for co-located clients and servers. For Hello.idl,
this file looks like this:

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. Under J2SE v.1.4, the files generated by the
idlj compiler for Hello.idl, with the
-fall command line option, are:

HelloPOA.java

This abstract class is the stream-based server skeleton,
providing basic CORBA functionality for the server. It extends
org.omg.PortableServer.Servant,
and implements the InvokeHandler interface and the
HelloOperations interface. The server class,
HelloServant, extends HelloPOA.

_HelloStub.java

This class is the client stub, providing
CORBA functionality for the client. It extends
org.omg.CORBA.portable.ObjectImpl and 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. It also extends the HelloOperations
interface and org.omg.CORBA.portable.IDLEntity.

HelloHelper.java

This class provides auxiliary functionality, notably the
narrow() method required to cast CORBA object references to
their proper types. The Helper class is responsible for reading and
writing the data type to CORBA streams, and inserting and
extracting the data type from Anys. The Holder class
delegates to the methods in the Helper class for reading and
writing.

HelloHolder.java

This final class holds a public instance member of type
Hello. Whenever the IDL type is an out or an
inout parameter, the Holder class is used. It provides
operations for org.omg.CORBA.portable.OutputStream and
org.omg.CORBA.portable.InputStream arguments, which CORBA
allows, but which do not map easily to Java's semantics. The Holder
class delegates to the methods in the Helper class for reading and
writing. It implements
org.omg.CORBA.portable.Streamable.

HelloOperations.java

This interface contains the methods sayHello() and
shutdown(). 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.

When you write the IDL interface, you do all the programming
required to generate all these files for your distributed
application. The next steps are to implement the client and server
classes. In the steps that follow, you will create the HelloClient.java client class and the
HelloServer.java server
class.

If you try to run idlj on the file Hello.idl
and the system cannot find idlj, it is most likely not in
your path. Make certain that the location of idlj (the JDK
bin directory) is in your path, and try again.