IDLJ Tutorial

Introduction

idlj generates Java bindings from an IDL file. It is the compiler bundled with Java SE. The specifications with which the Java 2 Platform Standard Edition (J2SE) 5.0 ORB complies are as follows (the specifications relative to other Java versions can be found in the Java Sun Site).

• CORBA 2.3.1 (formal/99-10-07)
• IDL to Java language mapping (ptc/00-01-08)
• Revised IDL to Java language mapping (ptc/00-11-03)
• Java to IDL language mapping (ptc/00-01-06)
• Interoperable Naming Service (ptc/00-08-07)
• Portable Interceptors (ptc/2001-08-31)

A more detailed description of the idlj compiler and Java IDL-related stuff can be found in the Java IDL page.

idlj

• The command synopsis is as follows.

idlj [ options ] idl-file

where idl-file is the name of a file containing Interface Definition Language (IDL) definitions. Options may appear in any order, but must precede the idl-file.

• Options

   -d symbol
       This is equivalent to the following line in an IDL file: 

       #define symbol

   -emitAll
       Emit all types, including those found in #include files. 

   -fside
       Defines what bindings to emit. side is one of client, server, serverTIE, all, or allTIE. The -fserverTIE and -fallTIE options cause delegate model skeletons to be emitted. Assumes -fclient if the flag is not specified. 

   -i include-path
       By default, the current directory is scanned for included files. This option adds another directory. 

   -keep
       If a file to be generated already exists, do not overwrite it. By default it is overwritten. 

   -noWarn
       Suppresses warning messages. 

   -oldImplBase
       Generates skeletons compatible with pre-1.4 JDK ORBs. By default, the POA Inheritance Model server-side bindings are generated. This option provides backward-compatibility with older versions of the Java programming language by generating server-side bindings that are !ImplBase Inheritance Model classes. 

   -pkgPrefix type prefix
       Wherever type is encountered at file scope, prefix the generated Java package name with prefix for all files generated for that type. The type is the simple name of either a top-level module, or an IDL type defined outside of any module. 

   -pkgTranslate type package
       Whenever the module name type is encountered in an identifier, replace it in the identifier with package for all files in the generated Java package. Note that pkgPrefix changes are made first. type is the simple name of either a top-level module, or an IDL type defined outside of any module, and must match the full package name exactly.

       If more than one translation matches an identifier, the longest match is chosen. For example, if the arguments include:

         -pkgTranslate foo bar -pkgTranslate foo.baz buzz.fizz

       The following translations would occur:

       foo          =>	bar
       foo.boo      =>	bar.boo
       foo.baz      =>	buzz.fizz
       foo.baz.bar  =>	buzz.fizz.bar

       The following package names cannot be translated:

• org
• org.omg or any subpackages of org.omg

       Any attempt to translate these packages will result in uncompilable code, and the use of these packages as the first argument after -pkgTranslate will be treated as an error.

   -skeletonName xxx%yyy
       Use xxx%yyy as the pattern for naming the skeleton. The defaults are:

•  %POA for the POA base class (-fserver or -fall)
• _%!ImplBase for the oldImplBase class (-oldImplBase and (-fserver or -fall))

   -td dir
       Use dir for the output directory instead of the current directory. 

   -tieName xxx%yyy
       Name the tie according to the pattern. The defaults are:

•  %POATie for the POA tie base class (-fserverTie or -fallTie)
•  %_Tie for the oldImplBase tie class (-oldImplBase and (-fserverTie or -fallTie))

   -nowarn, -verbose
       Verbose mode. 

   -version
       Display version information and terminate. 

• To generate Java bindings for an IDL file named Hello.idl:

     idlj -fall Hello.idl

Hello.idl example

Creating the IDL and bindings

• With any text editor we create a simple IDL file called hello.idl

module !HelloApp {

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

};

• We compile it by executing the command idlj -fall Hello.idl . Six new files will be created.

Understanding the results

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

• Only two of those files are needed for the purpose of declaring simple Java bindings as the ones used in the W3C recommendations. The interesting files are the Hello.java and !HelloOperations.java. The former carries the constants defined in the interface and the latter the operations and properties. To generate bindings like those used by previous W3C groups the contents of these files would have to be merged and CORBA-related stuff should be stripped.