idlj man page on Debian

Man page or keyword search:  
man Server   8174 pages
apropos Keyword Search (all sections)
Output format
Debian logo
[printable version]

idlj(1)								       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 com‐
       piler 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.Portable‐
	  Server.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.Ser‐
	  vant	class.	It serves as the base class for all POA servant imple‐
	  mentations 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 com‐
	  patible:

	  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 dele‐
	  gation model. Because it is not possible to generate ties and skele‐
	  tons at the same time, they must be generated separately.  The  fol‐
	  lowing 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 Inheri‐
	  tance 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 inheri‐
	  tance	 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	intro‐
	  duces	 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  construc‐
	  tor  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 /alt‐
	  dir/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  com‐
	  piler 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 envi‐
	  ronment 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 direc‐
	  tories 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 state‐
	  ments 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	 pack‐
	  age  is  not	good  enough.  To  follow  convention,	it  should  be
	  com.abc.Widgets. To place this package prefix onto the Widgets  mod‐
	  ule,	execute	 the  following:  idlj -pkgPrefix Widgets com.abc Wid‐
	  gets.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.Wid‐
	  gets=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 bind‐
	  ings. 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  custom‐
	  ized	those  files (which you should not do unless you are very com‐
	  fortable 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 pro‐
	  gresses through its phases of execution. Use the -v option to	 acti‐
	  vate 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	 bind‐
	     ings 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	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;
	    allowing them to be redefined would overwrite their original defi‐
	    nitions. (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)
[top]

List of man pages available for Debian

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net