1idlj(1) General Commands Manual idlj(1)
2
6 idlj - The IDL-to-Java Compiler
7 idlj generates Java bindings from a given IDL file.
9
11 idlj [ options ] idl-file
12 where idl-file is the name of a file containing Interface Definition
15 Language (IDL) definitions. Options may appear in any order, but must
16 precede the idl-file.
17
19 The IDL-to-Java Compiler generates the Java bindings for a given IDL
20 file. For binding details, see the OMG IDL to Java Language Language
21 Mapping Specification. Some previous releases of the IDL-to-Java com‐
22 piler were named idltojava.
23 Emitting Client and Server Bindings
25 To generate Java bindings for an IDL file named My.idl: idlj My.idl
26 This generates the client-side bindings and is equivalent to: idlj
28 -fclient My.idl
29 The client-side bindings do not include the server-side skeleton. If
31 you want to generate the server-side bindings for the interfaces:
32 idlj -fserver My.idl
33 Server-side bindings include the client-side bindings plus the
35 skeleton, all of which are POA (that is, Inheritance Model) classes.
36 If you want to generate both client and server-side bindings, use
37 one of the following (equivalent) commands: idlj -fclient -fserver
38 My.idl
39 idlj -fall My.idl
40 There are two possible server-side models: the Inheritance Model and
42 the Tie Delegation Model.
43 The default server-side model is the Portable Servant Inheritance
45 Model. Given an interface My defined in My.idl, the file MyPOA.java
46 is generated. You must provide the implementation for My and it must
47 inherit from MyPOA.
48 MyPOA.java is a stream-based skeleton that extends org.omg.Portable‐
50 Server.Servant and implements the InvokeHandler interface and the
51 operations interface associated with the IDL interface the skeleton
52 implements.
53 The PortableServer module for the Portable Object Adapter (POA)
55 defines the native Servant type. In the Java programming language,
56 the Servant type is mapped to the Java org.omg.PortableServer.Ser‐
57 vant class. It serves as the base class for all POA servant imple‐
58 mentations and provides a number of methods that may be invoked by
59 the application programmer, as well as methods which are invoked by
60 the POA itself and may be overridden by the user to control aspects
61 of servant behavior.
62 Another option for the Inheritance Model is to use the -oldImplBase
64 flag in order to generate server-side bindings that are compatible
65 with versions of the Java programming language prior to J2SE 1.4.
66 Note that using the -oldImplBase flag is non-standard: these APIs
67 are being deprecated. You would use this flag ONLY for compatibility
68 with existing servers written in J2SE 1.3. In that case, you would
69 need to modify an existing MAKEFILE to add the -oldImplBase flag to
70 the idlj compiler, otherwise POA-based server-side mappings will be
71 generated. To generate server-side bindings that are backwards com‐
72 patible:
73 idlj -fclient -fserver -oldImplBase My.idl
75 idlj -fall -oldImplBase My.idl
76 Given an interface My defined in My.idl, the file _MyImplBase.java
78 is generated. You must provide the implementation for My and it must
79 inherit from _MyImplBase.
80 The other server-side model is called the Tie Model. This is a dele‐
82 gation model. Because it is not possible to generate ties and skele‐
83 tons at the same time, they must be generated separately. The fol‐
84 lowing commands generate the bindings for the Tie Model:
85 idlj -fall My.idl
87 idlj -fallTIE My.idl
88 For the interface My, the second command generates MyPOATie.java.
90 The constructor to MyPOATie takes a delegate. In this example, using
91 the default POA model, the constructor also needs a poa. You must
92 provide the implementation for delegate, but it does not have to
93 inherit from any other class, only the interface MyOperations. But
94 to use it with the ORB, you must wrap your implementation within
95 MyPOATie. For instance:
96 ORB orb = ORB.init(args, System.getProperties());
97 // Get reference to rootpoa & activate the POAManager
99 POA rootpoa = (POA)orb.resolve_initial_references("RootPOA");
100 rootpoa.the_POAManager().activate();
101 // create servant and register it with the ORB
103 MyServant myDelegate = new MyServant();
104 myDelegate.setORB(orb);
105 // create a tie, with servant being the delegate.
107 MyPOATie tie = new MyPOATie(myDelegate, rootpoa);
108 // obtain the objectRef for the tie
110 My ref = tie._this(orb);
111 You might want to use the Tie model instead of the typical Inheri‐
114 tance model if your implementation must inherit from some other
115 implementation. Java allows any number of interface inheritance, but
116 there is only one slot for class inheritance. If you use the inheri‐
117 tance model, that slot is used up . By using the Tie Model, that
118 slot is freed up for your own use. The drawback is that it intro‐
119 duces a level of indirection: one extra method call occurs when
120 invoking a method.
121 To generate server-side, Tie model bindings that are compatible with
123 versions of the IDL to Java language mapping in versions prior to
124 J2SE 1.4.
125 idlj -oldImplBase -fall My.idl
127 idlj -oldImplBase -fallTIE My.idl
128 For the interface My, this will generate My_Tie.java. The construc‐
130 tor to My_Tie takes a impl. You must provide the implementation for
131 impl, but it does not have to inherit from any other class, only the
132 interface HelloOperations. But to use it with the ORB, you must wrap
133 your implementation within My_Tie. For instance:
134 ORB orb = ORB.init(args, System.getProperties());
136 // create servant and register it with the ORB
138 MyServant myDelegate = new MyServant();
139 myDelegate.setORB(orb);
140 // create a tie, with servant being the delegate.
142 MyPOATie tie = new MyPOATie(myDelegate);
143 // obtain the objectRef for the tie
145 My ref = tie._this(orb);
146 Specifying Alternate Locations for Emitted Files
149 If you want to direct the emitted files to a directory other than
150 the current directory, invoke the compiler as:
151 idlj -td /altdir My.idl
154 For the interface My, the bindings will be emitted to /alt‐
155 dir/My.java, etc., instead of ./My.java.
156 Specifying Alternate Locations for Include Files
158 If My.idl included another idl file, MyOther.idl, the compiler
159 assumes that MyOther.idl resides in the local directory. If it
160 resides in /includes, for example, then you would invoke the com‐
161 piler with the following command: idlj -i /includes My.idl
162 If My.idl also included Another.idl that resided in /moreIncludes,
164 for example, then you would invoke the compiler with the following
165 command: idlj -i /includes -i /moreIncludes My.idl
166 Since this form of include can become irritatingly long, another
168 means of indicating to the compiler where to search for included
169 files is provided. This technique is similar to the idea of an envi‐
170 ronment variable. Create a file named idl.config in a directory that
171 is listed in your CLASSPATH. Inside of idl.config, provide a line
172 with the following form: includes=/includes;/moreIncludes
173 The compiler will find this file and read in the includes list. Note
175 that in this example the separator character between the two direc‐
176 tories is a semicolon (;). This separator character is platform
177 dependent. On the Windows platform, use a semicolon, on the Unix
178 platform, use a colon, etc. For more information on includes, read
179 the CLASSPATH (Solaris) or CLASSPATH (Windows) documentation.
180 Emitting Bindings for Include Files
182 By default, only those interfaces, structs, etc, that are defined in
183 the idl file on the command line have Java bindings generated for
184 them. The types defined in included files are not generated. For
185 example, assume the following two idl files: My.idl
186 #include <MyOther.idl>
188 interface My
189 {
190 };
191 MyOther.idl
192 interface MyOther
194 {
195 };
196 The following command will only generate the java bindings for My:
198 idlj My.idl
199 To generate all of the types in My.idl and all of the types in the
201 files that My.idl includes (in this example, MyOther.idl), use the
202 following command: idlj -emitAll My.idl
203 There is a caveat to the default rule. #include statements which
205 appear at global scope are treated as described. These #include
206 statements can be thought of as import statements. #include state‐
207 ments which appear within some enclosing scope are treated as true
208 #include statements, meaning that the code within the included file
209 is treated as if it appeared in the original file and, therefore,
210 Java bindings are emitted for it. Here is an example: My.idl
211 #include <MyOther.idl>
213 interface My
214 {
215 #include <Embedded.idl>
216 }; MyOther.idl
217 interface MyOther
219 {
220 }; Embedded.idl
221 enum E {one, two, three};
223 Running the following command: idlj My.idl
225 will generate the following list of Java files: ./MyHolder.java
227 ./MyHelper.java
228 ./_MyStub.java
229 ./MyPackage
230 ./MyPackage/EHolder.java
231 ./MyPackage/EHelper.java
232 ./MyPackage/E.java
233 ./My.java
234 Notice that MyOther.java was not generated because it is defined in
236 an import-like #include. But E.java was generated because it was
237 defined in a true #include. Also notice that since Embedded.idl was
238 included within the scope of the interface My, it appears within the
239 scope of My (that is,in MyPackage).
240 If the -emitAll flag had been used in the previous example, then all
242 types in all included files would be emitted.
243 Inserting Package Prefixes
245 Suppose that you work for a company named ABC that has constructed
246 the following IDL file:
247 Widgets.idl
248 module Widgets
250 {
251 interface W1 {...};
252 interface W2 {...};
253 };
254 Running this file through the IDL-to-Java compiler will place the
256 Java bindings for W1 and W2 within the package Widgets. But there is
257 an industry convention that states that a company's packages should
258 reside within a package named com.<company name>. The Widgets pack‐
259 age is not good enough. To follow convention, it should be
260 com.abc.Widgets. To place this package prefix onto the Widgets mod‐
261 ule, execute the following: idlj -pkgPrefix Widgets com.abc Wid‐
262 gets.idl
263 If you have an IDL file which includes Widgets.idl, the -pkgPrefix
265 flag must appear in that command also. If it does not, then your IDL
266 file will be looking for a Widgets package rather than a
267 com.abc.Widgets package.
268 If you have a number of these packages that require prefixes, it
270 might be easier to place them into the idl.config file described
271 above. Each package prefix line should be of the form:
272 PkgPrefix.<type>=<prefix>
274 So the line for the above example would be: PkgPrefix.Wid‐
276 gets=com.abc
277 The use of this option does not affect the Repository ID.
279 Defining Symbols Before Compilation
281 You may need to define a symbol for compilation that is not defined
282 within the IDL file, perhaps to include debugging code in the bind‐
283 ings. The command idlj -d MYDEF My.idl
284 is the equivalent of putting the line #define MYDEF inside My.idl.
286 Preserving Pre-Existing Bindings
288 If the Java binding files already exist, the -keep flag will keep
289 the compiler from overwriting them. The default is to generate all
290 files without considering if they already exist. If you've custom‐
291 ized those files (which you should not do unless you are very com‐
292 fortable with their contents), then the -keep option is very useful.
293 The command idlj -keep My.idl
294 emit all client-side bindings that do not already exist.
296 Viewing Progress of Compilation
298 The IDL-to-Java compiler will generate status messages as it pro‐
299 gresses through its phases of execution. Use the -v option to acti‐
300 vate this "verbose" mode: idlj -v My.idl
301 By default the compiler does not operate in verbose mode.
303 Displaying Version Information
305 To display the build version of the IDL-to-Java compiler, specify
306 the -version option on the command-line:
307 idlj -version
309 Version information also appears within the bindings generated by
311 the compiler. Any additional options appearing on the command-line
312 are ignored.
313
315 -d symbol
316 This is equivalent to the following line in an IDL file:
317 #define symbol
320 -emitAll
322 Emit all types, including those found in #include files.
323 -fside
325 Defines what bindings to emit. side is one of client, server,
326 serverTIE, all, or allTIE. The -fserverTIE and -fallTIE options
327 cause delegate model skeletons to be emitted. Assumes -fclient if
328 the flag is not specified.
329 -i include-path
331 By default, the current directory is scanned for included files.
332 This option adds another directory.
333 -keep
335 If a file to be generated already exists, do not overwrite it. By
336 default it is overwritten.
337 -noWarn
339 Suppresses warning messages.
340 -oldImplBase
342 Generates skeletons compatible with pre-1.4 JDK ORBs. By default,
343 the POA Inheritance Model server-side bindings are generated.
344 This option provides backward-compatibility with older versions
345 of the Java programming language by generating server-side bind‐
346 ings that are ImplBase Inheritance Model classes.
347 -pkgPrefix type prefix
349 Wherever type is encountered at file scope, prefix the generated
350 Java package name with prefix for all files generated for that
351 type. The type is the simple name of either a top-level module,
352 or an IDL type defined outside of any module.
353 -pkgTranslate type package
355 Whenever the module name type is encountered in an identifier,
356 replace it in the identifier with package for all files in the
357 generated Java package. Note that pkgPrefix changes are made
358 first. type is the simple name of either a top-level module, or
359 an IDL type defined outside of any module, and must match the
360 full package name exactly.
361 If more than one translation matches an identifier, the longest
363 match is chosen. For example, if the arguments include:
364 -pkgTranslate foo bar -pkgTranslate foo.baz buzz.fizz
365 The following translations would occur:
367 foo => bar
368 foo.boo => bar.boo
369 foo.baz => buzz.fizz
370 foo.baz.bar => buzz.fizz.bar
371 The following package names cannot be translated:
373 o org
375 o org.omg or any subpackages of org.omg
377 Any attempt to translate these packages will result in uncompilable
379 code, and the use of these packages as the first argument after
380 -pkgTranslate will be treated as an error.
381 -skeletonName xxx%yyy
383 Use xxx%yyy as the pattern for naming the skeleton. The defaults
384 are:
385 o %POA for the POA base class (-fserver or -fall)
387 o _%ImplBase for the oldImplBase class (-oldImplBase and
389 (-fserver or -fall))
390 -td dir
392 Use dir for the output directory instead of the current direc‐
393 tory.
394 -tieName xxx%yyy
396 Name the tie according to the pattern. The defaults are:
397 o %POATie for the POA tie base class (-fserverTie or -fallTie)
399 o %_Tie for the oldImplBase tie class (-oldImplBase and
401 (-fserverTie or -fallTie))
402 -nowarn, -verbose
404 Verbose mode.
405 -version
407 Display version information and terminate.
408 See the Description section for more option information.
411
413 o Escaped identifiers in the global scope may not have the same
414 spelling as IDL primitive types, Object, or ValueBase. This is
415 because the symbol table is pre-loaded with these identifiers;
416 allowing them to be redefined would overwrite their original defi‐
417 nitions. (Possible permanent restriction).
418 o The fixed IDL type is not supported.
420
423 o No import generated for global identifiers. If you invoke on an
424 unexported local impl, you do get an exception, but it seems to be
425 due to a NullPointerException in the ServerDelegate DSI code.
426 07 Aug 2006 idlj(1)