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 @
22 http://docs.oracle.com/javase/7/docs/technotes/guides/idl/map‐
23 ping/jidlMapping.html. Some previous releases of the IDL-to-Java com‐
24 piler were named idltojava.
25 Emitting Client and Server Bindings
27 To generate Java bindings for an IDL file named My.idl:
28 idlj My.idl
30 This generates the client-side bindings and is equivalent to:
33 idlj -fclient My.idl
35 The client-side bindings do not include the server-side skeleton. If
38 you want to generate the server-side bindings for the interfaces:
39 idlj -fserver My.idl
41 Server-side bindings include the client-side bindings plus the skele‐
44 ton, all of which are POA (that is, Inheritance Model) classes. If you
45 want to generate both client and server-side bindings, use one of the
46 following (equivalent) commands:
47 idlj -fclient -fserver My.idl
49 idlj -fall My.idl
50 There are two possible server-side models: the Inheritance Model and
53 the Tie Delegation Model.
54 The default server-side model is the Portable Servant Inheritance
56 Model. Given an interface My defined in My.idl, the file MyPOA.java is
57 generated. You must provide the implementation for My and it must
58 inherit from MyPOA.
59 MyPOA.java is a stream-based skeleton that extends org.omg.Portable‐
61 Server.Servant @
62 http://docs.oracle.com/javase/7/docs/api/org/omg/PortableServer/Ser‐
63 vant.html and implements the InvokeHandler interface and the operations
64 interface associated with the IDL interface the skeleton implements.
65 The PortableServer module for the Portable Object Adapter (POA) @
67 http://docs.oracle.com/javase/7/docs/technotes/guides/idl/POA.html
68 defines the native Servant type. In the Java programming language, the
69 Servant type is mapped to the Java org.omg.PortableServer.Servant
70 class. It serves as the base class for all POA servant implementations
71 and provides a number of methods that may be invoked by the application
72 programmer, as well as methods which are invoked by the POA itself and
73 may be overridden by the user to control aspects of servant behavior.
74 Another option for the Inheritance Model is to use the -oldImplBase
76 flag in order to generate server-side bindings that are compatible with
77 versions of the Java programming language prior to J2SE 1.4. Note that
78 using the -oldImplBase flag is non-standard: these APIs are being dep‐
79 recated. You would use this flag ONLY for compatibility with existing
80 servers written in J2SE 1.3. In that case, you would need to modify an
81 existing MAKEFILE to add the -oldImplBase flag to the idlj compiler,
82 otherwise POA-based server-side mappings will be generated. To generate
83 server-side bindings that are backwards compatible:
84 idlj -fclient -fserver -oldImplBase My.idl
86 idlj -fall -oldImplBase My.idl
87 Given an interface My defined in My.idl, the file _MyImplBase.java is
90 generated. You must provide the implementation for My and it must
91 inherit from _MyImplBase.
92 The other server-side model is called the Tie Model. This is a delega‐
94 tion model. Because it is not possible to generate ties and skeletons
95 at the same time, they must be generated separately. The following com‐
96 mands generate the bindings for the Tie Model:
97 idlj -fall My.idl
99 idlj -fallTIE My.idl
100 For the interface My, the second command generates MyPOATie.java. The
103 constructor to MyPOATie takes a delegate. In this example, using the
104 default POA model, the constructor also needs a poa. You must provide
105 the implementation for delegate, but it does not have to inherit from
106 any other class, only the interface MyOperations. But to use it with
107 the ORB, you must wrap your implementation within MyPOATie. For
108 instance:
109 ORB orb = ORB.init(args, System.getProperties());
111 // Get reference to rootpoa & activate the POAManager
113 POA rootpoa = (POA)orb.resolve_initial_references("RootPOA");
114 rootpoa.the_POAManager().activate();
115 // create servant and register it with the ORB
117 MyServant myDelegate = new MyServant();
118 myDelegate.setORB(orb);
119 // create a tie, with servant being the delegate.
121 MyPOATie tie = new MyPOATie(myDelegate, rootpoa);
122 // obtain the objectRef for the tie
124 My ref = tie._this(orb);
125 You might want to use the Tie model instead of the typical Inheritance
128 model if your implementation must inherit from some other implementa‐
129 tion. Java allows any number of interface inheritance, but there is
130 only one slot for class inheritance. If you use the inheritance model,
131 that slot is used up . By using the Tie Model, that slot is freed up
132 for your own use. The drawback is that it introduces a level of indi‐
133 rection: one extra method call occurs when invoking a method.
134 To generate server-side, Tie model bindings that are compatible with
136 versions of the IDL to Java language mapping in versions prior to J2SE
137 1.4.
138 idlj -oldImplBase -fall My.idl
140 idlj -oldImplBase -fallTIE My.idl
141 For the interface My, this will generate My_Tie.java. The constructor
144 to My_Tie takes a impl. You must provide the implementation for impl,
145 but it does not have to inherit from any other class, only the inter‐
146 face HelloOperations. But to use it with the ORB, you must wrap your
147 implementation within My_Tie. For instance:
148 ORB orb = ORB.init(args, System.getProperties());
150 // create servant and register it with the ORB
152 MyServant myDelegate = new MyServant();
153 myDelegate.setORB(orb);
154 // create a tie, with servant being the delegate.
156 MyPOATie tie = new MyPOATie(myDelegate);
157 // obtain the objectRef for the tie
159 My ref = tie._this(orb);
160 Specifying Alternate Locations for Emitted Files
163 If you want to direct the emitted files to a directory other than the
164 current directory, invoke the compiler as:
165 idlj -td /altdir My.idl
167 For the interface My, the bindings will be emitted to /altdir/My.java,
170 etc., instead of ./My.java.
171 Specifying Alternate Locations for Include Files
173 If My.idl included another idl file, MyOther.idl, the compiler assumes
174 that MyOther.idl resides in the local directory. If it resides in
175 /includes, for example, then you would invoke the compiler with the
176 following command:
177 idlj -i /includes My.idl
179 If My.idl also included Another.idl that resided in /moreIncludes, for
182 example, then you would invoke the compiler with the following command:
183 idlj -i /includes -i /moreIncludes My.idl
185 Since this form of include can become irritatingly long, another means
188 of indicating to the compiler where to search for included files is
189 provided. This technique is similar to the idea of an environment vari‐
190 able. Create a file named idl.config in a directory that is listed in
191 your CLASSPATH. Inside of idl.config, provide a line with the following
192 form:
193 includes=/includes;/moreIncludes
195 The compiler will find this file and read in the includes list. Note
198 that in this example the separator character between the two directo‐
199 ries is a semicolon (;). This separator character is platform depen‐
200 dent. On the Windows platform, use a semicolon, on the Unix platform,
201 use a colon, etc. For more information on includes, see the Setting the
202 Classpath @
203 http://docs.oracle.com/javase/7/docs/technotes/tools/index.html#gen‐
204 eral.
205 Emitting Bindings for Include Files
207 By default, only those interfaces, structs, etc, that are defined in
208 the idl file on the command line have Java bindings generated for them.
209 The types defined in included files are not generated. For example,
210 assume the following two idl files:
211 My.idl
213 #include <MyOther.idl>
215 interface My
216 {
217 };
218 MyOther.idl
221 interface MyOther
223 {
224 };
225 The following command will only generate the java bindings for My:
228 idlj My.idl
230 To generate all of the types in My.idl and all of the types in the
233 files that My.idl includes (in this example, MyOther.idl), use the fol‐
234 lowing command:
235 idlj -emitAll My.idl
237 There is a caveat to the default rule. #include statements which appear
240 at global scope are treated as described. These #include statements can
241 be thought of as import statements. #include statements which appear
242 within some enclosing scope are treated as true #include statements,
243 meaning that the code within the included file is treated as if it
244 appeared in the original file and, therefore, Java bindings are emitted
245 for it. Here is an example:
246 My.idl
248 #include <MyOther.idl>
250 interface My
251 {
252 #include <Embedded.idl>
253 };
254 MyOther.idl
257 interface MyOther
259 {
260 };
261 Embedded.idl
264 enum E {one, two, three};
266 Running the following command:
269 idlj My.idl
271 will generate the following list of Java files:
274 Notice that MyOther.java was not generated because it is defined in an
276 import-like #include. But E.java was generated because it was defined
277 in a true #include. Also notice that since Embedded.idl was included
278 within the scope of the interface My, it appears within the scope of My
279 (that is,in MyPackage).
280 If the -emitAll flag had been used in the previous example, then all
282 types in all included files would be emitted.
283 Inserting Package Prefixes
285 Suppose that you work for a company named ABC that has constructed the
286 following IDL file:
287 Widgets.idl
289 module Widgets
291 {
292 interface W1 {...};
293 interface W2 {...};
294 };
295 Running this file through the IDL-to-Java compiler will place the Java
298 bindings for W1 and W2 within the package Widgets. But there is an
299 industry convention that states that a company's packages should reside
300 within a package named com.<company name>. The Widgets package is not
301 good enough. To follow convention, it should be com.abc.Widgets. To
302 place this package prefix onto the Widgets module, execute the follow‐
303 ing:
304 idlj -pkgPrefix Widgets com.abc Widgets.idl
306 If you have an IDL file which includes Widgets.idl, the -pkgPrefix flag
309 must appear in that command also. If it does not, then your IDL file
310 will be looking for a Widgets package rather than a com.abc.Widgets
311 package.
312 If you have a number of these packages that require prefixes, it might
314 be easier to place them into the idl.config file described above. Each
315 package prefix line should be of the form:
316 PkgPrefix.<type>=<prefix>
318 So the line for the above example would be:
321 PkgPrefix.Widgets=com.abc
322 The use of this option does not affect the Repository ID.
325 Defining Symbols Before Compilation
327 You may need to define a symbol for compilation that is not defined
328 within the IDL file, perhaps to include debugging code in the bindings.
329 The command
330 idlj -d MYDEF My.idl
332 is the equivalent of putting the line #define MYDEF inside My.idl.
335 Preserving Pre-Existing Bindings
337 If the Java binding files already exist, the -keep flag will keep the
338 compiler from overwriting them. The default is to generate all files
339 without considering if they already exist. If you've customized those
340 files (which you should not do unless you are very comfortable with
341 their contents), then the -keep option is very useful. The command
342 idlj -keep My.idl
344 emits all client-side bindings that do not already exist.
347 Viewing Progress of Compilation
349 The IDL-to-Java compiler will generate status messages as it progresses
350 through its phases of execution. Use the -v option to activate this
351 "verbose" mode:
352 idlj -v My.idl
354 By default the compiler does not operate in verbose mode.
357 Displaying Version Information
359 To display the build version of the IDL-to-Java compiler, specify the
360 -version option on the command-line:
361 idlj -version
363 Version information also appears within the bindings generated by the
366 compiler. Any additional options appearing on the command-line are
367 ignored.
368
370 -d symbol
371 This is equivalent to the following line in an IDL file:
372 #define symbol
373 -emitAll
375 Emit all types, including those found in #include files.
376 -fside
378 Defines what bindings to emit. side is one of client, server,
379 serverTIE, all, or allTIE. The -fserverTIE and -fallTIE options
380 cause delegate model skeletons to be emitted. Assumes -fclient if
381 the flag is not specified.
382 -i include-path
384 By default, the current directory is scanned for included files.
385 This option adds another directory.
386 -keep
388 If a file to be generated already exists, do not overwrite it. By
389 default it is overwritten.
390 -noWarn
392 Suppresses warning messages.
393 -oldImplBase
395 Generates skeletons compatible with pre-1.4 JDK ORBs. By default,
396 the POA Inheritance Model server-side bindings are generated.
397 This option provides backward-compatibility with older versions
398 of the Java programming language by generating server-side bind‐
399 ings that are ImplBase Inheritance Model classes.
400 -pkgPrefix type prefix
402 Wherever type is encountered at file scope, prefix the generated
403 Java package name with prefix for all files generated for that
404 type. The type is the simple name of either a top-level module,
405 or an IDL type defined outside of any module.
406 -pkgTranslate type package
408 Whenever the module name type is encountered in an identifier,
409 replace it in the identifier with package for all files in the
410 generated Java package. Note that pkgPrefix changes are made
411 first. type is the simple name of either a top-level module, or
412 an IDL type defined outside of any module, and must match the
413 full package name exactly.
414 If more than one translation matches an identifier, the longest
415 match is chosen. For example, if the arguments include:
416 -pkgTranslate foo bar -pkgTranslate foo.baz buzz.fizz
417 The following translations would occur:
418 foo => bar
419 foo.boo => bar.boo
420 foo.baz => buzz.fizz
421 foo.baz.bar => buzz.fizz.bar
422 The following package names cannot be translated:
423 o org
425 o org.omg or any subpackages of org.omg
427 Any attempt to translate these packages will result in uncompilable
428 code, and the use of these packages as the first argument after
429 -pkgTranslate will be treated as an error.
430 -skeletonName xxx%yyy
432 Use xxx%yyy as the pattern for naming the skeleton. The defaults
433 are:
434 o %POA for the POA base class (-fserver or -fall)
436 o _%ImplBase for the oldImplBase class (-oldImplBase and
438 (-fserver or -fall))
439 -td dir
441 Use dir for the output directory instead of the current direc‐
442 tory.
443 -tieName xxx%yyy
445 Name the tie according to the pattern. The defaults are:
446 o %POATie for the POA tie base class (-fserverTie or -fallTie)
448 o %_Tie for the oldImplBase tie class (-oldImplBase and
450 (-fserverTie or -fallTie))
451 -nowarn, -verbose
453 Verbose mode.
454 -version
456 Display version information and terminate.
457 See the Description section for more option information.
460
462 o Escaped identifiers in the global scope may not have the same
463 spelling as IDL primitive types, Object, or ValueBase. This is
464 because the symbol table is pre-loaded with these identifiers;
465 allowing them to be redefined would overwrite their original defi‐
466 nitions. (Possible permanent restriction).
467 o The fixed IDL type is not supported.
469
472 o No import generated for global identifiers. If you invoke on an
473 unexported local impl, you do get an exception, but it seems to be
474 due to a NullPointerException in the ServerDelegate DSI code.
475 16 Mar 2012 idlj(1)