manpagez: man pages & more
man idlj(1)
Home | html | info | man
idlj(1)                                                                idlj(1)




NAME

       idlj - The IDL-to-Java Compiler (RMI-IIOP version)

       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  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 skele-
       ton, 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  Inneritance  Model  and
       the Tie 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.Portable-
       Server.Servant and implements the InvokeHandler interface and the oper-
       ations interface associated with the IDL interface the skeleton  imple-
       ments.

       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  pro-
       vides  a  number of methods that may be invoked by the application pro-
       grammer, 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
       older  version of the Java programming language (prior to J2SE 1.4). 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 _MyImpleBase.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  delega-
       tion  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.  You must provide the  imple-
       mentation  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:

              MyImpl myImpl = new MyImpl ();
              My POATie tie = new MyPOATie (myImpl);
              orb.connect (tie);

       You  might want to use the Tie model instead of the typical Inheritance
       model if your implementation must inherit from some  other  implementa-
       tion.  Java  allows  any  number of interface inheritance, but there is
       only one slot for class inheritance. If you 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  indirec-
       tion: one extra method call occurs when invoking a method.

       To  generate  server-side,  Tie model bindings that are compatible with
       older version of the IDL to Java language mapping in versions  of  J2SE
       before 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 inter-
       face HelloOperations.  But to use it with the ORB, you must  wrap  your
       implementation within My_Tie.  For instance:

              MyImpl myImpl = new MyImpl ();
              My_Tie tie = new My_Tie (myImpl);
              orb.connect (tie);



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 vari-
       able.  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  directo-
       ries  is  a  semicolon (;). This separator character is platform depen-
       dent. On NT it is a semicolon, on Solaris it is a colon, etc.  For more
       information on includes, read the CLASSPATH 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 fol-
       lowing 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 state-
       ments 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:


       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.<companyname>.  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 follow-
       ing:

              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 options 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 -fserverTIEand -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
              Supresses warning messages.

       -oldImplBase
              Generates  skeletons  compatible with old (pre-1.4) JDK ORBs. By
              default, the POA Inheritance Model server-side bindings are gen-
              erated.  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
              Wherever the type or module name type is encountered, replace it
              in the 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 out-
              side of any  module,  and  must  match  the  full  package  name
              exactly.  Also  note  that 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 uncompil-
              able  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 direc-
              tory.

       -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; allow-
         ing  them to be redefined would overwrite their original definitions.
         (Possible permanent restriction).

       o The fixed IDL type is not supported.



                                 10 March 2001                         idlj(1)

Mac OS X 10.7.4 - Generated Thu May 10 07:39:04 CDT 2012
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.