# Writing the Interface Definition Language (IDL) file

Note: All command and troubleshooting instructions apply to Java 2 SDK v1.3.0 and its version of `idlj` only.

Before you start working with Java IDL, you need to install version 1.3 of the Java 2 SDK. J2SDK v1.3.0 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 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.

These topics are included in this section:

1. Writing `Hello.idl`
2. Understanding the IDL file
3. Mapping `Hello.idl` to Java
4. Understanding the idlj Compiler Output

## Writing `Hello.idl`

To create the `Hello.idl` file,

1. Create a new directory, named `Hello`, for this application.

2. Start your favorite text editor and create a file named `Hello.idl` in this directory.

3. In your file, enter the code for the interface definition:

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

4. Save the file.

## Understanding the IDL file

OMG IDL is a purely declarative language designed for specifying programming-language-independent operational interfaces for distributed applications. OMG specifies a mapping from IDL to several different programming languages, including C, C++, Smalltalk, COBOL, Ada, and Java. When mapped, each statement in OMG IDL is translated to a corresponding statement in the programming language of choice. You can use the tool `idlj` to map an IDL interface to Java and implement the client class. When you map the same IDL to C++ and implement the server in that language, the Java client and C++ server interoperate through the ORB as though they were written in the same language.

The IDL for Hello World is extremely simple; its single interface has a single operation. You need perform only three steps:

1. Declare the CORBA IDL module
2. Declare the interface
3. Declare the operations

### Declaring the CORBA IDL Module

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.

### Declaring the Interface

Like Java interfaces, CORBA interfaces declare the API contract an object has with other objects. Each interface statement in the IDL maps to a Java interface statement when mapped.

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

    module HelloApp
    {
      interface Hello  // These
      {                // are the
                       // interface
      };               // statement.
    };

When you compile the IDL, this statement will generate an interface statement in the Java code. Your client and server classes will implement the Hello interface in different ways.

### Declaring the Operations

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 the operation statement.
      };
    };

Our little Hello World application has only a single operation, so `Hello.idl` is now complete.

## Mapping Hello.idl to Java

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 the IDL-to-Java compiler options, follow the link.

1. Go to a command line prompt.

2. Change to the directory containing your `Hello.idl` file.

3. 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:

    package HelloApp;

    /**
    * HelloApp/Hello.java
    * Generated by the IDL-to-Java compiler (portable), version "3.0"
    * from Hello.idl
    */

    public interface Hello extends HelloOperations, org.omg.CORBA.Object, org.omg.CORBA.portable.IDLEntity
    {
    } // interface Hello

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, 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:

    package HelloApp;

    /**
    * HelloApp/HelloOperations.java
    * Generated by the IDL-to-Java compiler (portable), version "3.0"
    * from Hello.idl
    */

    public interface HelloOperations
    {
      String sayHello ();
    } // interface HelloOperations

Because there is only one operation defined in this interface, it is easy to see how the IDL statements map to the generated Java statements.

IDL Statement |  | Java Statement
--- | --- | ---
`string sayHello();` | `` | `String sayHello();`

## Understanding the idlj Compiler Output

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 signature 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 `IDLEntity`, and is used as the signature type in method declarations when interfaces of the specified type are used in other interfaces.
`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 operations interface contains the single method `sayHello()`. The IDL-to-Java mapping puts all of the operations defined on the IDL interface into this file. The operations interface is used in the server-side mapping and as a mechanism for providing optimized calls for co-located clients and servers.

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 `HelloClient.java` and `HelloApplet.java` client classes and the `HelloServer.java` class.

## Troubleshooting

- Error Message: "idlj" not found

  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 J2SDK v.1.3 `.bin` directory) is in your path, and try again.

## For More Information

- Mapping IDL to Java: Overview

  Provides the basics on mapping IDL constructs to the corresponding Java statements.

- Chapter 3 of the OMG CORBA/IIOP specification

  Provides the complete specification for OMG Interface Definition Language. At this writing, the specification can be downloaded from http://www.omg.org/technology/documents/new_formal/corba.htm.

Next: Developing a Client Application | Previous: Getting Started with Java IDL | `Hello.idl`

Home

Copyright © 1996, 1997 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.