idlj(1)                    OpenBSD Reference Manual                    idlj(1)



NAME
       idlj - The IDL-to-Java Compiler

          idlj generates Java bindings from a given IDL file.

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

Description
       The IDL-to-Java Compiler generates the Java bindings for a given IDL
       file.  For binding details, see the OMG IDL to Java Language Language
       Mapping Specification. Some previous releases of the IDL-to-Java
       compiler were named idltojava.

   Emitting Client and Server Bindings
          To generate Java bindings for an IDL file named My.idl: idlj My.idl

          This generates the client-side bindings and is equivalent to: idlj
          -fclient My.idl

          The client-side bindings do not include the server-side skeleton. If
          you want to generate the server-side bindings for the interfaces:
          idlj -fserver My.idl

          Server-side bindings include the client-side bindings plus the
          skeleton, all of which are POA (that is, Inheritance Model) classes.
          If you want to generate both client and server-side bindings, use
          one of the following (equivalent) commands: idlj -fclient -fserver
          My.idl
          idlj -fall My.idl

          There are two possible server-side models: the Inheritance Model and
          the Tie Delegation Model.

          The default server-side model is the Portable Servant Inheritance
          Model. Given an interface My defined in My.idl, the file MyPOA.java
          is generated. You must provide the implementation for My and it must
          inherit from MyPOA.

          MyPOA.java is a stream-based skeleton that extends
          org.omg.PortableServer.Servant and implements the InvokeHandler
          interface and the operations interface associated with the IDL
          interface the skeleton implements.

          The PortableServer module for the Portable Object Adapter (POA)
          defines the native Servant type. In the Java programming language,
          the Servant type is mapped to the Java
          org.omg.PortableServer.Servant class. It serves as the base class
          for all POA servant implementations and provides a number of methods
          that may be invoked by the application programmer, as well as
          methods which are invoked by the POA itself and may be overridden by
          the user to control aspects of servant behavior.

          Another option for the Inheritance Model is to use the -oldImplBase
          flag in order to generate server-side bindings that are compatible
          with versions of the Java programming language prior to J2SE 1.4.
          Note that using the -oldImplBase flag is non-standard: these APIs
          are being deprecated. You would use this flag ONLY for compatibility
          with existing servers written in J2SE 1.3. In that case, you would
          need to modify an existing MAKEFILE to add the -oldImplBase flag to
          the idlj compiler, otherwise POA-based server-side mappings will be
          generated. To generate server-side bindings that are backwards
          compatible:

          idlj -fclient -fserver -oldImplBase My.idl
          idlj -fall -oldImplBase My.idl

          Given an interface My defined in My.idl, the file _MyImplBase.java
          is generated. You must provide the implementation for My and it must
          inherit from _MyImplBase.

          The other server-side model is called the Tie Model. This is a
          delegation model. Because it is not possible to generate ties and
          skeletons at the same time, they must be generated separately. The
          following commands generate the bindings for the Tie Model:

          idlj -fall My.idl
          idlj -fallTIE My.idl

          For the interface My, the second command generates MyPOATie.java.
          The constructor to MyPOATie takes a delegate. In this example, using
          the default POA model, the constructor also needs a poa. You must
          provide the implementation for delegate, but it does not have to
          inherit from any other class, only the interface MyOperations. But
          to use it with the ORB, you must wrap your implementation within
          MyPOATie. For instance:
              ORB orb = ORB.init(args, System.getProperties());

              // Get reference to rootpoa & activate the POAManager
              POA rootpoa = (POA)orb.resolve_initial_references("RootPOA");
              rootpoa.the_POAManager().activate();

              // create servant and register it with the ORB
              MyServant myDelegate = new MyServant();
              myDelegate.setORB(orb);

              // create a tie, with servant being the delegate.
              MyPOATie tie = new MyPOATie(myDelegate, rootpoa);

              // obtain the objectRef for the tie
              My ref = tie._this(orb);


          You might want to use the Tie model instead of the typical
          Inheritance model if your implementation must inherit from some
          other implementation. Java allows any number of interface
          inheritance, but there is only one slot for class inheritance. If
          you use the inheritance model, that slot is used up . By using the
          Tie Model, that slot is freed up for your own use. The drawback is
          that it introduces a level of indirection: one extra method call
          occurs when invoking a method.

          To generate server-side, Tie model bindings that are compatible with
          versions of the IDL to Java language mapping in versions prior to
          J2SE 1.4.

          idlj -oldImplBase -fall My.idl
          idlj -oldImplBase -fallTIE My.idl

          For the interface My, this will generate My_Tie.java. The
          constructor to My_Tie takes a impl. You must provide the
          implementation for impl, but it does not have to inherit from any
          other class, only the interface HelloOperations. But to use it with
          the ORB, you must wrap your implementation within My_Tie. For
          instance:

              ORB orb = ORB.init(args, System.getProperties());

              // create servant and register it with the ORB
              MyServant myDelegate = new MyServant();
              myDelegate.setORB(orb);

              // create a tie, with servant being the delegate.
              MyPOATie tie = new MyPOATie(myDelegate);

              // obtain the objectRef for the tie
              My ref = tie._this(orb);


   Specifying Alternate Locations for Emitted Files
          If you want to direct the emitted files to a directory other than
          the current directory, invoke the compiler as:


             idlj -td /altdir My.idl
          For the interface My, the bindings will be emitted to
          /altdir/My.java, etc., instead of ./My.java.

   Specifying Alternate Locations for Include Files
          If My.idl included another idl file, MyOther.idl, the compiler
          assumes that MyOther.idl resides in the local directory. If it
          resides in /includes, for example, then you would invoke the
          compiler with the following command: idlj -i /includes My.idl

          If My.idl also included Another.idl that resided in /moreIncludes,
          for example, then you would invoke the compiler with the following
          command: idlj -i /includes -i /moreIncludes My.idl

          Since this form of include can become irritatingly long, another
          means of indicating to the compiler where to search for included
          files is provided. This technique is similar to the idea of an
          environment variable. Create a file named idl.config in a directory
          that is listed in your CLASSPATH. Inside of idl.config, provide a
          line with the following form:  includes=/includes;/moreIncludes

          The compiler will find this file and read in the includes list. Note
          that in this example the separator character between the two
          directories is a semicolon (;). This separator character is platform
          dependent. On the Windows platform, use a semicolon, on the Unix
          platform, use a colon, etc. For more information on includes, read
          the CLASSPATH (Solaris) or CLASSPATH (Windows) documentation.

   Emitting Bindings for Include Files
          By default, only those interfaces, structs, etc, that are defined in
          the idl file on the command line have Java bindings generated for
          them. The types defined in included files are not generated. For
          example, assume the following two idl files:   My.idl

          #include <MyOther.idl>
          interface My
          {
          };
          MyOther.idl

          interface MyOther
          {
          };

          The following command will only generate the java bindings for My:
          idlj My.idl

          To generate all of the types in My.idl and all of the types in the
          files that My.idl includes (in this example, MyOther.idl), use the
          following command: idlj -emitAll My.idl

          There is a caveat to the default rule. #include statements which
          appear at global scope are treated as described. These #include
          statements can be thought of as import statements. #include
          statements which appear within some enclosing scope are treated as
          true #include statements, meaning that the code within the included
          file is treated as if it appeared in the original file and,
          therefore, Java bindings are emitted for it. Here is an example:
          My.idl

          #include <MyOther.idl>
          interface My
          {
            #include <Embedded.idl>
          };   MyOther.idl

          interface MyOther
          {
          };   Embedded.idl

          enum E {one, two, three};

          Running the following command: idlj My.idl

          will generate the following list of Java files: ./MyHolder.java
          ./MyHelper.java
          ./_MyStub.java
          ./MyPackage
          ./MyPackage/EHolder.java
          ./MyPackage/EHelper.java
          ./MyPackage/E.java
          ./My.java

          Notice that MyOther.java was not generated because it is defined in
          an import-like #include. But E.java was generated because it was
          defined in a true #include. Also notice that since Embedded.idl was
          included within the scope of the interface My, it appears within the
          scope of My (that is,in MyPackage).

          If the -emitAll flag had been used in the previous example, then all
          types in all included files would be emitted.

   Inserting Package Prefixes
          Suppose that you work for a company named ABC that has constructed
          the following IDL file:
          Widgets.idl

          module Widgets
          {
            interface W1 {...};
            interface W2 {...};
          };

          Running this file through the IDL-to-Java compiler will place the
          Java bindings for W1 and W2 within the package Widgets. But there is
          an industry convention that states that a company's packages should
          reside within a package named com.<company name>. The Widgets
          package is not good enough. To follow convention, it should be
          com.abc.Widgets. To place this package prefix onto the Widgets
          module, execute the following: idlj -pkgPrefix Widgets com.abc
          Widgets.idl

          If you have an IDL file which includes Widgets.idl, the -pkgPrefix
          flag must appear in that command also. If it does not, then your IDL
          file will be looking for a Widgets package rather than a
          com.abc.Widgets package.

          If you have a number of these packages that require prefixes, it
          might be easier to place them into the idl.config file described
          above. Each package prefix line should be of the form:

          PkgPrefix.<type>=<prefix>

          So the line for the above example would be:
          PkgPrefix.Widgets=com.abc

          The use of this option does not affect the Repository ID.

   Defining Symbols Before Compilation
          You may need to define a symbol for compilation that is not defined
          within the IDL file, perhaps to include debugging code in the
          bindings. The command idlj -d MYDEF My.idl

          is the equivalent of putting the line #define MYDEF inside My.idl.

   Preserving Pre-Existing Bindings
          If the Java binding files already exist, the -keep flag will keep
          the compiler from overwriting them. The default is to generate all
          files without considering if they already exist. If you've
          customized those files (which you should not do unless you are very
          comfortable with their contents), then the -keep option is very
          useful. The command idlj -keep My.idl

          emit all client-side bindings that do not already exist.

   Viewing Progress of Compilation
          The IDL-to-Java compiler will generate status messages as it
          progresses through its phases of execution. Use the -v option to
          activate this "verbose" mode: idlj -v My.idl

          By default the compiler does not operate in verbose mode.

   Displaying Version Information
          To display the build version of the IDL-to-Java compiler, specify
          the -version option on the command-line:

          idlj -version

          Version information also appears within the bindings generated by
          the compiler. Any additional options appearing on the command-line
          are ignored.

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:

             o org

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

             o %POA for the POA base class (-fserver or -fall)

             o _%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:

             o %POATie for the POA tie base class (-fserverTie or -fallTie)

             o %_Tie for the oldImplBase tie class (-oldImplBase and
               (-fserverTie or -fallTie))

          -nowarn, -verbose
             Verbose mode.

          -version
             Display version information and terminate.


       See the Description section for more option information.

Restrictions:
          o Escaped identifiers in the global scope may not have the same
            spelling as IDL primitive types, Object, or ValueBase. This is
            because the symbol table is pre-loaded with these identifiers;
            allowing them to be redefined would overwrite their original
            definitions. (Possible permanent restriction).

          o The fixed IDL type is not supported.


Known Problems:
          o No import generated for global identifiers. If you invoke on an
            unexported local impl, you do get an exception, but it seems to be
            due to a NullPointerException in the ServerDelegate DSI code.


                                  07 Aug 2006                          idlj(1)
