Lesson 1: Writing the IDL Interface

It is a good idea to create a temporary directory to hold your tutorial files as you work.

Note: You will need to download the idltojava compiler in order to perform the tasks in this Lesson. All command and troubleshooting instructions apply to this version of idltojava only.

Lesson Overview

In this lesson, you will write a simple IDL interface for the Hello World program. The IDL interface defines the contract between the client and server parts of your application, specifying what operations and attributes are available. OMG IDL is programming-language-independent. You must map it to Java before writing any of the implementation code. (Running idltojava on the IDL file does this for you automatically.)

Included in this lesson are:

1. Writing Hello.idl
2. Mapping Hello.idl to Java
3. Understanding the Output of idltojava

To see a completed version of the Hello.idl file, follow the link.

Writing Hello.idl

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 idltojava 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

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.

1. Start your favorite text editor and create a file named Hello.idl.

2. In your file, enter the module statement:

   module HelloApp
   {
       // Add subsequent lines of code here.
   };
   

3. Save the file.

When you run idltojava on the IDL, this 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, enter the interface statement:

module HelloApp
{
  interface Hello  // Add
  {                // these
                   // four
  };               // lines.
};

Save the file. 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, enter the operation statement:

module HelloApp
{
  interface Hello
  {
    string sayHello();  // Add this line.
  };
};

Save the file. Because our little Hello World application has only a single operation, Hello.idl is now complete. You can close your text editor if you wish.

Mapping Hello.idl from IDL to Java

The tool idltojava reads OMG IDL files and creates the required Java files. The idltojava defaults are set up so that if you need both client and server files (as you do for our Hello World program), you simply enter the tool name and the name of your IDL file:

1. Go to a command line prompt.

2. Change directory to the location of your Hello.idl file

3. Enter the compiler command:
   

      
   	idltojava 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 five files. Try opening Hello.java in your text editor. It looks like this:

/* Hello.java as generated by idltojava */

package HelloApp;
public interface Hello
    extends org.omg.CORBA.Object {
    String sayHello();
}

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
string sayHello();	String sayHello();

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 idltojava; you do not need to do any mapping yourself.

Understanding the idltojava Compiler Output

idltojava generates a number of files, based on the options chosen on the command line. Because these provide standard functionality, you can ignore them until it is time to deploy and run your program. The five files generated by the idltojava 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. It contains the single method sayHello(). The Hello.java interface extends org.omg.CORBA.Object, providing standard CORBA object functionality as well.

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 has but which do not map easily to Java's semantics.

When you write the IDL interface, you do all the programming required to generate all these files for your distributed application. The only additional work required is the actual implementation of client and server classes. In the lessons that follow, you will create HelloClient.java and HelloApplet.java client classes and the HelloServer.java class.

Troubleshooting

Error Message: "idltojava" not found

Error Message: preprocessor failed

Mapping IDL to Java: Overview

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

Chapter 3 of the OMG CORBA specification

Provides the complete specification for OMG Interface Definition Language