Manual Pages for UNIX Darwin command on man idlj

idlj(1) idlj(1)

NAME

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

iiddlljj generates Java bindings from a given IDL file.

SYNOPSIS

iiddlljj [ 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 iiddllttoojjaavvaa. EEmmiittttiinngg CClliieenntt aanndd SSeerrvveerr BBiinnddiinnggss To generate Java bindings for an IDL file named MMyy..iiddll: iiddlljj MMyy..iiddll

This generates the client-side bindings and is equivalent to:

iiddlljj -ffcclliieenntt MMyy..iiddll

The client-side bindings do not include the server-side skeleton. If

you want to generate the server-side bindings for the interfaces:

iiddlljj -ffsseerrvveerr MMyy..iiddll

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:

iiddlljj -ffcclliieenntt -ffsseerrvveerr MMyy..iiddll

iiddlljj -ffaallll MMyy..iiddll

There are two possible server-side models: the Inneritance Model and

the Tie Model.

The default server-side model is the PPoorrttaabbllee SSeerrvvaanntt IInnhheerriittaannccee

MMooddeell. Given an interface My defined in MMyy..iiddll, the file MMyyPPOOAA..jjaavvaa is generated. You must provide the implementation for MMyy and it must inherit from MMyyPPOOAA.

MMyyPPOOAA..jjaavvaa is a stream-based skeleton that extends oorrgg..oommgg..PPoorrttaabbllee-

SSeerrvveerr..SSeerrvvaanntt and implements the IInnvvookkeeHHaannddlleerr interface and the oper-

ations interface associated with the IDL interface the skeleton imple-

ments. The PPoorrttaabblleeSSeerrvveerr module for the PPoorrttaabbllee OObbjjeecctt AAddaapptteerr ((PPOOAA)) defines the native Servant type. In the Java programming language, the SSeerrvvaanntt type is mapped to the Java oorrgg..oommgg..PPoorrttaabblleeSSeerrvveerr..SSeerrvvaanntt 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 -oollddIImmppllBBaassee

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:

iiddlljj -ffcclliieenntt -ffsseerrvveerr -oollddIImmppllBBaassee MMyy..iiddll

iiddlljj -ffaallll -oollddIImmppllBBaassee MMyy..iiddll

Given an interface MMyy defined in MMyy..iiddll, the file MMyyIImmpplleeBBaassee..jjaavvaa is generated. You must provide the implementation for MMyy and it must inherit from MMyyIImmppllBBaassee.

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:

iiddlljj -ffaallll MMyy..iiddll

iiddlljj -ffaallllTTIIEE MMyy..iiddll

For the interface MMyy, the second command generates MMyyPPOOAATTiiee..jjaavvaa. The

constructor to MMyyPPOOAATTiiee 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 MMyyOOppeerraattiioonnss. But to use it with the ORB, you must wrap your implementation within MMyyPPOOAATTiiee. For instance: MMyyIImmppll mmyyIImmppll == nneeww MMyyIImmppll (());; MMyy PPOOAATTiiee ttiiee == nneeww MMyyPPOOAATTiiee ((mmyyIImmppll));; oorrbb..ccoonnnneecctt ((ttiiee));; 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.

iiddlljj -oollddIImmppllBBaassee -ffaallll MMyy..iiddll

iiddlljj -oollddIImmppllBBaassee -ffaallllTTIIEE MMyy..iiddll

For the interface MMyy, this will generate MMyyTTiiee..jjaavvaa. The constructor to MMyyTTiiee takes a iimmppll. You must provide the implementation for iimmppll,

but it does not have to inherit from any other class, only the inter-

face HHeellllooOOppeerraattiioonnss. But to use it with the ORB, you must wrap your implementation within MMyyTTiiee. For instance: MMyyIImmppll mmyyIImmppll == nneeww MMyyIImmppll (());; MMyyTTiiee ttiiee == nneeww MMyyTTiiee ((mmyyIImmppll));; oorrbb..ccoonnnneecctt ((ttiiee));; SSppeecciiffyyiinngg AAlltteerrnnaattee LLooccaattiioonnss ffoorr EEmmiitttteedd FFiilleess If you want to direct the emitted files to a directory other than the current directory, invoke the compiler as:

iiddlljj -ttdd //aallttddiirr MMyy..iiddll

For the interface MMyy, the bindings will be emitted to //aallttddiirr//MMyy..jjaavvaa, etc., instead of ..//MMyy..jjaavvaa.. SSppeecciiffyyiinngg AAlltteerrnnaattee LLooccaattiioonnss ffoorr IInncclluuddee FFiilleess If MMyy..iiddll included another idl file, MMyyOOtthheerr..iiddll, the compiler assumes that MMyyOOtthheerr..iiddll resides in the local directory. If it resides in //iinncclluuddeess, for example, then you would invoke the compiler with the following command:

iiddlljj -ii //iinncclluuddeess MMyy..iiddll

If MMyy..iiddll also included AAnnootthheerr..iiddll that resided in //mmoorreeIInncclluuddeess, for example, then you would invoke the compiler with the following command:

iiddlljj -ii //iinncclluuddeess -ii //mmoorreeIInncclluuddeess MMyy..iiddll

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 iiddll..ccoonnffiigg in a directory that is listed in your CLASSPATH. Inside of iiddll..ccoonnffiigg, provide a line with the following form: iinncclluuddeess==//iinncclluuddeess;;//mmoorreeIInncclluuddeess 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. EEmmiittttiinngg BBiinnddiinnggss ffoorr IInncclluuddee FFiilleess 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: MMyy..iiddll

#include

interface My { }; MMyyOOtthheerr..iiddll interface MyOther { }; The following command will only generate the java bindings for MMyy: iiddlljj MMyy..iiddll To generate all of the types in MMyy..iiddll and all of the types in the

files that MMyy..iiddll includes (in this example, MMyyOOtthheerr..iiddll), use the fol-

lowing command:

iiddlljj -eemmiittAAllll MMyy..iiddll

There is a caveat to the default rule. ##iinncclluuddee statements which

appear at global scope are treated as described. These ##iinncclluuddee state-

ments can be thought of as import statements. ##iinncclluuddee statements

which appear within some enclosing scope are treated as true ##iinncclluuddee

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: MMyy..iiddll

#include

interface My {

#include

}; MMyyOOtthheerr..iiddll interface MyOther { }; EEmmbbeeddddeedd..iiddll enum E {one, two, three}; Running the following command: iiddlljj MMyy..iiddll will generate the following list of Java files: Notice that MMyyOOtthheerr..jjaavvaa was not generated because it is defined in an

import-like ##iinncclluuddee. But EE..jjaavvaa was generated because it was defined

in a true ##iinncclluuddee. Also notice that since EEmmbbeeddddeedd..iiddll was included

within the scope of the interface MMyy, it appears within the scope of MMyy (that is,in MMyyPPaacckkaaggee).

If the -eemmiittAAllll flag had been used in the previous example, then all

types in all included files would be emitted. IInnsseerrttiinngg PPaacckkaaggee PPrreeffiixxeess Suppose that you work for a company named ABC that has constructed the following IDL file: WWiiddggeettss.. iiddll 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 ccoomm..<.. The WWiiddggeettss package is not good enough. To follow convention, it should be ccoomm..aabbcc..WWiiddggeettss. To

place this package prefix onto the WWiiddggeettss module, execute the follow-

ing:

iiddlljj -ppkkggPPrreeffiixx WWiiddggeettss ccoomm..aabbcc WWiiddggeettss..iiddll

If you have an IDL file which includes WWiiddggeettss..iiddll, the -ppkkggPPrreeffiixx flag

must appear in that command also. If it does not, then your IDL file will be looking for a WWiiddggeettss package rather than a ccoomm..aabbcc..WWiiddggeettss package. If you have a number of these packages that require prefixes, it might be easier to place them into the iiddll..ccoonnffiigg file described above. Each package prefix line should be of the form: PPkkggPPrreeffiixx..<>==<> So the line for the above example would be: PPkkggPPrreeffiixx..WWiiddggeettss==ccoomm..aabbcc The use of this options does not affect the Repository ID. DDeeffiinniinngg SSyymmbboollss BBeeffoorree CCoommppiillaattiioonn 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

iiddlljj -dd MMYYDDEEFF MMyy..iiddll

is the equivalent of putting the line ##ddeeffiinnee MMYYDDEEFF inside MMyy..iiddll.

PPrreesseerrvviinngg PPrree-EExxiissttiinngg BBiinnddiinnggss

If the Java binding files already exist, the -kkeeeepp 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 -kkeeeepp option is very useful. The command

iiddlljj -kkeeeepp MMyy..iiddll

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

VViieewwiinngg PPrrooggrreessss ooff CCoommppiillaattiioonn

The IDL-to-Java compiler will generate status messages as it progresses

through its phases of execution. Use the -vv option to activate this

"verbose" mode:

iiddlljj -vv MMyy..iiddll

By default the compiler does not operate in verbose mode. DDiissppllaayyiinngg VVeerrssiioonn IInnffoorrmmaattiioonn

To display the build version of the IDL-to-Java compiler, specify the

-vveerrssiioonn option on the command-line:

iiddlljj -vveerrssiioonn

Version information also appears within the bindings generated by the

compiler. Any additional options appearing on the command-line are

ignored. OOPPTTIIOONNSS

-dd symbol

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

##ddeeffiinnee ssyymmbbooll

-eemmiittAAllll

Emit all types, including those found in ##iinncclluuddee files.

-ffssiiddee Defines what bindings to emit. ssiiddee is one of cclliieenntt,, sseerrvveerr,,

sseerrvveerrTTIIEE,, aallll,, or aallllTTIIEE..The -ffsseerrvveerrTTIIEEand -ffaallllTTIIEE options

cause delegate model skeletons to be emitted. Assumes -ffcclliieenntt

if the flag is not specified.

-ii include-path

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

-kkeeeepp If a file to be generated already exists, do not overwrite it.

By default it is overwritten.

-nnooWWaarrnn

Supresses warning messages.

-oollddIImmppllBBaassee

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 IImmppllBBaassee Inheritance Model classes.

-ppkkggPPrreeffiixx type prefix

Wherever ttyyppee is encountered at file scope, prefix the generated Java package name with pprreeffiixx for all files generated for that

type. The ttyyppee is the simple name of either a top-level module,

or an IDL type defined outside of any module.

-ppkkggTTrraannssllaattee type package

Wherever the type or module name ttyyppee is encountered, replace it in the with ppaacckkaaggee for all files in the generated Java package. Note that ppkkggPPrreeffiixx changes are made first. ttyyppee 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 -ppkkggTTrraannssllaattee will be treated as an error.

-sskkeelleettoonnNNaammee xxx%yyy

Use xxxxxx%%yyyyyy as the pattern for naming the skeleton. The defaults

are

+o %POA for the POA base class (

-ffsseerrvveerr or -ffaallll)

+o %ImplBase for the oldImplBase class (

-oollddIImmppllBBaassee and ( -ffsseerrvveerr or -ffaallll))

-ttdd dir

Use ddiirr for the output directory instead of the current direc-

tory.

-ttiieeNNaammee xxx%yyy

Name the tie according to the pattern. The defaults are:

+o %POATie for the POA tie base class (

-ffsseerrvveerrTTiiee or -ffaallllTTiiee)

+o %Tie for the

oollddIImmppllBBaassee tie class ( -oollddIImmppllBBaassee and ( -ffsseerrvveerrTTiiee or

-ffaallllTTiiee))

-nnoowwaarrnn,-vveerrbboossee

Verbose mode.

-vveerrssiioonn

Display version information and terminate. See the Description section for more option information. RReessttrriiccttiioonnss +o Escaped identifiers in the global scope may not have the same spelling as IDL primitive types, OObbjjeecctt, or VVaalluueeBBaassee. 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.