1idlj(1)                   Java IDL and RMI-IIOP Tools                  idlj(1)
2
3
4

NAME

6       idlj - Generates Java bindings for a specified Interface Definition
7       Language (IDL) file.
8

SYNOPSIS

10       idlj [ options ] idlfile
11
12
13       options
14              The command-line options. See Options. Options can appear in any
15              order, but must precede the idlfile.
16
17       idlfile
18              The name of a file that contains Interface Definition Language
19              (IDL) definitions.
20

DESCRIPTION

22       The IDL-to-Java Compiler generates the Java bindings for a specified
23       IDL file. For binding details, see Java IDL: IDL to Java Language
24       Mapping at
25       http://docs.oracle.com/javase/8/docs/technotes/guides/idl/mapping/jidlMapping.html
26
27       Some earlier releases of the IDL-to-Java compiler were named idltojava.
28
29   EMIT CLIENT AND SERVER BINDINGS
30       The following idlj command generates an IDL file named My.idl with
31       client-side bindings.
32
33       idlj My.idl
34
35       The previous syntax is equivalent to the following:
36
37       idlj -fclient My.idl
38
39       The next example generates the server-side bindings, and includes the
40       client-side bindings plus the skeleton, all of which are POA
41       (Inheritance Model).
42
43       idlg -fserver My.idl
44
45       If you want to generate both client and server-side bindings, then use
46       one of the following (equivalent) commands:
47
48       idlj -fclient -fserver My.idl
49       idlj -fall My.idl
50
51       There are two possible server-side models: the Portal Servant
52       Inheritance Model and the Tie Model. See Tie Delegation Model.
53
54       Portable Servant Inheritance Model. The default server-side model is
55       the Portable Servant Inheritance Model. Given an interface My defined
56       in My.idl, the file MyPOA.java is generated. You must provide the
57       implementation for the My interface, and the My interface must inherit
58       from the MyPOA class. MyPOA.java is a stream-based skeleton that
59       extends the org.omg.PortableServer.Servant class at
60       http://docs.oracle.com/javase/8/docs/api/org/omg/PortableServer/Servant.html
61       The My interface implements the callHandler interface and the
62       operations interface associated with the IDL interface the skeleton
63       implements.The PortableServer module for the Portable Object Adapter
64       (POA) defines the native Servant type. See Portable Object Adapter
65       (POA) at
66       http://docs.oracle.com/javase/8/docs/technotes/guides/idl/POA.html In
67       the Java programming language, the Servant type is mapped to the Java
68       org.omg.PortableServer.Servant class. It serves as the base class for
69       all POA servant implementations and provides a number of methods that
70       can be called by the application programmer, and methods that are
71       called by the POA and that can be overridden by the user to control
72       aspects of servant behavior.Another option for the Inheritance Model is
73       to use the -oldImplBase flag to generate server-side bindings that are
74       compatible with releases of the Java programming language before Java
75       SE 1.4. The -oldImplBase flag is nonstandard, and these APIs are
76       deprecated. You would use this flag only for compatibility with
77       existing servers written in Java SE 1.3. In that case, you would need
78       to modify an existing make file to add the -oldImplBase flag to the
79       idlj compiler. Otherwise POA-based server-side mappings are generated.
80       To generate server-side bindings that are backward compatible, do the
81       following:
82
83       idlj -fclient -fserver -oldImplBase My.idl
84       idlj -fall -oldImplBase My.idl
85
86       Given an interface My defined in My.idl, the file _MyImplBase.java is
87       generated. You must provide the implementation for the My interface,
88       and the My interface must inherit from the _MyImplBase class.
89
90       Tie Delegation Model. The other server-side model is called the Tie
91       Model. This is a delegation model. Because it is not possible to
92       generate ties and skeletons at the same time, they must be generated
93       separately. The following commands generate the bindings for the Tie
94       Model:
95
96       idlj -fall My.idl
97       idlj -fallTIE My.idl
98
99       For the My interface, the second command generates MyPOATie.java. The
100       constructor to the MyPOATie class takes a delegate. In this example,
101       using the default POA model, the constructor also needs a POA. You must
102       provide the implementation for the delegate, but it does not have to
103       inherit from any other class, only the interface MyOperations. To use
104       it with the ORB, you must wrap your implementation within the MyPOATie
105       class, for example:
106
107       ORB orb = ORB.init(args, System.getProperties());
108       // Get reference to rootpoa & activate the POAManager
109       POA rootpoa = (POA)orb.resolve_initial_references("RootPOA");
110       rootpoa.the_POAManager().activate();
111       // create servant and register it with the ORB
112       MyServant myDelegate = new MyServant();
113       myDelegate.setORB(orb);
114       // create a tie, with servant being the delegate.
115       MyPOATie tie = new MyPOATie(myDelegate, rootpoa);
116       // obtain the objectRef for the tie
117       My ref = tie._this(orb);
118
119       You might want to use the Tie model instead of the typical Inheritance
120       model when your implementation must inherit from some other
121       implementation. Java allows any number of interface inheritance, but
122       there is only one slot for class inheritance. If you use the
123       inheritance model, then that slot is used up. With the Tie Model, that
124       slot is freed up for your own use. The drawback is that it introduces a
125       level of indirection: one extra method call occurs when a method is
126       called.
127
128       For server-side generation, Tie model bindings that are compatible with
129       versions of the IDL to Java language mapping in versions earlier than
130       Java SE 1.4.
131
132       idlj -oldImplBase -fall My.idl
133       idlj -oldImplBase -fallTIE My.idl
134
135       For the My interface, the this generates My_Tie.java. The constructor
136       to the My_Tie class takes an impl object. You must provide the
137       implementation for impl, but it does not have to inherit from any other
138       class, only the interface HelloOperations. But to use it with the ORB,
139       you must wrap your implementation within My_Tie, for example:
140
141       ORB orb = ORB.init(args, System.getProperties());
142       // create servant and register it with the ORB
143       MyServant myDelegate = new MyServant();
144       myDelegate.setORB(orb);
145       // create a tie, with servant being the delegate.
146       MyPOATie tie = new MyPOATie(myDelegate);
147       // obtain the objectRef for the tie
148       My ref = tie._this(orb);
149
150
151   SPECIFY ALTERNATE LOCATIONS FOR EMITTED FILES
152       If you want to direct the emitted files to a directory other than the
153       current directory, then call the compiler this way: idlj -td /altdir
154       My.idl.
155
156       For the My interface, the bindings are emitted to /altdir/My.java,
157       etc., instead of ./My.java.
158
159   SPECIFY ALTERNATE LOCATIONS FOR INCLUDE FILES
160       If the My.idl file includes another idl file, MyOther.idl, then the
161       compiler assumes that the MyOther.idl file resides in the local
162       directory. If it resides in /includes, for example, then you call the
163       compiler with the following command:
164
165       idlj -i /includes My.idl
166
167       If My.idl also included Another.idl that resided in /moreIncludes, for
168       example, then you call the compiler with the following command:
169
170       idlj -i /includes -i /moreIncludes My.idl
171
172       Because this form of include can become long, another way to indicate
173       to the compiler where to search for included files is provided. This
174       technique is similar to the idea of an environment variable. Create a
175       file named idl.config in a directory that is listed in your CLASSPATH
176       variable. Inside of idl.config, provide a line with the following form:
177
178       includes=/includes;/moreIncludes
179
180       The compiler will find this file and read in the includes list. Note
181       that in this example the separator character between the two
182       directories is a semicolon (;). This separator character is platform
183       dependent. On the Windows platform, use a semicolon, on the Unix
184       platform, use a colon, and so on.
185
186   EMIT BINDINGS FOR INCLUDE FILES
187       By default, only those interfaces, structures, and so on, that are
188       defined in the idl file on the command line have Java bindings
189       generated for them. The types defined in included files are not
190       generated. For example, assume the following two idl files:
191
192       My.idl file:
193       #include <MyOther.idl>
194       interface My
195       {
196       };
197       MyOther.idl file:
198       interface MyOther
199       {
200       };
201
202       There is a caveat to the default rule. Any #include statements that
203       appear at the global scope are treated as described. These #include
204       statements can be thought of as import statements. The #include
205       statements that appear within an enclosed scope are treated as true
206       #include statements, which means that the code within the included file
207       is treated as though it appeared in the original file and, therefore,
208       Java bindings are emitted for it. Here is an example:
209
210       My.idl file:
211       #include <MyOther.idl>
212       interface My
213       {
214         #include <Embedded.idl>
215       };
216       MyOther.idl file:
217       interface MyOther
218       {
219       };
220       Embedded.idl
221       enum E {one, two, three};
222
223       Runidlj My.idlto generate the following list of Java files. Notice that
224       MyOther.java is not generated because it is defined in an import-like
225       #include. But E.java was generated because it was defined in a true
226       #include. Notice that because the Embedded.idl file is included within
227       the scope of the interface My, it appears within the scope of My (in
228       MyPackage). If the -emitAll flag had been used, then all types in all
229       included files would have been emitted.
230
231       ./MyHolder.java
232       ./MyHelper.java
233       ./_MyStub.java
234       ./MyPackage
235       ./MyPackage/EHolder.java
236       ./MyPackage/EHelper.java
237       ./MyPackage/E.java
238       ./My.java
239
240
241   INSERT PACKAGE PREFIXES
242       Suppose that you work for a company named ABC that has constructed the
243       following IDL file:
244
245       Widgets.idl file:
246       module Widgets
247       {
248         interface W1 {...};
249         interface W2 {...};
250       };
251
252       If you run this file through the IDL-to-Java compiler, then the Java
253       bindings for W1 and W2 are placed within the Widgets package. There is
254       an industry convention that states that a company's packages should
255       reside within a package named com.<company name>. To follow this
256       convention, the package name should be com.abc.Widgets. To place this
257       package prefix onto the Widgets module, execute the following:
258
259       idlj -pkgPrefix Widgets com.abc Widgets.idl
260
261       If you have an IDL file that includes Widgets.idl, then the -pkgPrefix
262       flag must appear in that command also. If it does not, then your IDL
263       file will be looking for a Widgets package rather than a
264       com.abc.Widgets package.
265
266       If you have a number of these packages that require prefixes, then it
267       might be easier to place them into the idl.config file described
268       previously. Each package prefix line should be of the form:
269       PkgPrefix.<type>=<prefix>. The line for the previous example would be
270       PkgPrefix.Widgets=com.abc. This option does not affect the Repository
271       ID.
272
273   DEFINE SYMBOLS BEFORE COMPILATION
274       You might need to define a symbol for compilation that is not defined
275       within the IDL file, perhaps to include debugging code in the bindings.
276       The command idlj -d MYDEF My.idlis equivalent to putting the line
277       #define MYDEF inside My.idl.
278
279   PRESERVE PREEXISTING BINDINGS
280       If the Java binding files already exist, then the -keep flag keeps the
281       compiler from overwriting them. The default is to generate all files
282       without considering that they already exist. If you have customized
283       those files (which you should not do unless you are very comfortable
284       with their contents), then the -keep option is very useful. The command
285       idlj -keep My.idl emits all client-side bindings that do not already
286       exist.
287
288   VIEW COMPILATION PROGRESS
289       The IDL-to-Java compiler generates status messages as it progresses
290       through its phases of execution. Use the -v option to activate the
291       verbose mode: idlj -v My.idl.
292
293       By default the compiler does not operate in verbose mode
294
295   DISPLAY VERSION INFORMATION
296       To display the build version of the IDL-to-Java compiler, specify the
297       -version option on the command-line: idlj -version.
298
299       Version information also appears within the bindings generated by the
300       compiler. Any additional options appearing on the command-line are
301       ignored.
302

OPTIONS

304       -d symbol
305              This is equivalent to the following line in an IDL file:
306
307              #define symbol
308
309
310
311       -demitAll
312              Emit all types, including those found in #include files.
313
314       -fside
315              Defines what bindings to emit. The side parameter can be client,
316              server, serverTIE, all, or allTIE. The -fserverTIE and -fallTIE
317              options cause delegate model skeletons to be emitted. Defaults
318              to -fclient when the flag is not specified.
319
320       -i include-path
321              By default, the current directory is scanned for included files.
322              This option adds another directory.
323
324       -i keep
325              If a file to be generated already exists, then do not overwrite
326              it. By default it is overwritten.
327
328       -noWarn
329              Suppress warning messages.
330
331       -oldImplBase
332              Generates skeletons compatible with pre-1.4 JDK ORBs. By
333              default, the POA Inheritance Model server-side bindings are
334              generated. This option provides backward-compatibility with
335              earlier releases of the Java programming language by generating
336              server-side bindings that are ImplBase Inheritance Model
337              classes.
338
339       -pkgPrefix typeprefix
340              Wherever type is encountered at file scope, prefix the generated
341              Java package name with prefix for all files generated for that
342              type. The type is the simple name of either a top-level module,
343              or an IDL type defined outside of any module.
344
345       -pkgTranslate typepackage
346              Whenever the module name type is encountered in an identifier,
347              replace it in the identifier with package for all files in the
348              generated Java package. Note that pkgPrefix changes are made
349              first. The type value is the simple name of either a top-level
350              module, or an IDL type defined outside of any module and must
351              match the full package name exactly.
352
353              If more than one translation matches an identifier, then the
354              longest match is chosen as shown in the following example:
355
356              Command:
357
358              pkgTranslate type pkg -pkgTranslate type2.baz pkg2.fizz
359
360
361
362              Resulting Translation:
363
364              type => pkg
365              type.ext => pkg.ext
366              type.baz => pkg2.fizz
367              type2.baz.pkg => pkg2.fizz.pkg
368
369
370
371              The following package names org, org.omg, or any subpackages of
372              org.omg cannot be translated. Any attempt to translate these
373              packages results in uncompilable code, and the use of these
374              packages as the first argument after -pkgTranslate is treated as
375              an error.
376
377       -skeletonName xxx%yyy
378              Use xxx%yyy as the pattern for naming the skeleton. The defaults
379              are: %POA for the POA base class (-fserver or -fall), and
380              _%ImplBase for the oldImplBase class (-oldImplBase) and
381              (-fserver or -fall)).
382
383       -td dir
384              Use dir for the output directory instead of the current
385              directory.
386
387       -tieName xxx%yyy
388              Use xxx%yyy according to the pattern. The defaults are: %POA for
389              the POA base class (-fserverTie or -fallTie), and _%Tie for the
390              oldImplBase tie class (-oldImplBase) and (-fserverTie or
391              -fallTie))
392
393       -nowarn, -verbose
394              Displays release information and terminates.
395
396       -version
397              Displays release information and terminates.
398

RESTRICTIONS

400       Escaped identifiers in the global scope cannot have the same spelling
401       as IDL primitive types, Object, or ValueBase. This is because the
402       symbol table is preloaded with these identifiers. Allowing them to be
403       redefined would overwrite their original definitions. Possible
404       permanent restriction.
405
406       The fixed IDL type is not supported.
407

KNOWN PROBLEMS

409       No import is generated for global identifiers. If you call an
410       unexported local impl object, then you do get an exception, but it
411       seems to be due to a NullPointerException in the ServerDelegate DSI
412       code.
413
414
415
416JDK 8                          21 November 2013                        idlj(1)
Impressum