Warning:
This wiki has been archived and is now read-only.
IDLJ Tutorial
From Device Description Working Group Wiki
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.