The JavaTM Tutorial

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Trail: IDL
Lesson: The Hello Client-Server Example

## Writing the IDL Interface

> In this section, 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.) Here's the complete `Hello.idl` file.

### 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 described below.

> ### Step 1: 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.
> 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.

> ### Step 2: Declaring the Interface

> Like Java interfaces, CORBA interfaces declare the API contract that 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.
> >     };

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

> ### Step 3: 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.
> >         };
> >     };

> Because our little Hello World application has only a single operation, `Hello.idl` is now complete.

### 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.

> > Mapping of IDL Statements to 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

> The `idltojava` compiler 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
>   If you try to run `idltojava` on the file `Hello.idl` and the system cannot find `idltojava`, it is most likely not in your executable path. Make certain that the location of `idltojava` is in your path, and try again.
> Error Message: preprocessor failed
>   `idltojava` uses a C/C++ preprocessor by default. You can change the default by setting two environment variables, `CPP` and `CPPARGS`. If you do not want to use a preprocessor, you can turn it off by adding `-fno-cpp` to the `idltojava` command line.

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Copyright 1995-2004 Sun Microsystems, Inc. All rights reserved.