annotate src/bsd/doc/man/idlj.1 @ 17269:dc0c6d243e2f

8174105: Better naming attribution Reviewed-by: chegar, dfuchs, rriggs
author vtewari
date Fri, 10 Mar 2017 08:29:10 +0530
parents 66c98bd811f1
rev   line source
rgallard@8813 1 '\" t
mfang@12442 2 .\" Copyright (c) 2001, 2013, Oracle and/or its affiliates. All rights reserved.
mfang@12442 4 .\"
mfang@12442 5 .\" This code is free software; you can redistribute it and/or modify it
mfang@12442 6 .\" under the terms of the GNU General Public License version 2 only, as
mfang@12442 7 .\" published by the Free Software Foundation.
mfang@12442 8 .\"
mfang@12442 9 .\" This code is distributed in the hope that it will be useful, but WITHOUT
mfang@12442 10 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
mfang@12442 11 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
mfang@12442 12 .\" version 2 for more details (a copy is included in the LICENSE file that
mfang@12442 13 .\" accompanied this code).
mfang@12442 14 .\"
mfang@12442 15 .\" You should have received a copy of the GNU General Public License version
mfang@12442 16 .\" 2 along with this work; if not, write to the Free Software Foundation,
mfang@12442 17 .\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
mfang@12442 18 .\"
mfang@12442 19 .\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
mfang@12442 20 .\" or visit if you need additional information or have any
mfang@12442 21 .\" questions.
mfang@12442 22 .\"
rgallard@8813 23 .\" Arch: generic
rgallard@8813 24 .\" Software: JDK 8
rgallard@8813 25 .\" Date: 21 November 2013
rgallard@8813 26 .\" SectDesc: Java IDL and RMI-IIOP Tools
rgallard@8813 27 .\" Title: idlj.1
rgallard@8813 28 .\"
rgallard@8813 29 .if n .pl 99999
rgallard@8813 30 .TH idlj 1 "21 November 2013" "JDK 8" "Java IDL and RMI-IIOP Tools"
mfang@12442 31 .\" -----------------------------------------------------------------
mfang@12442 32 .\" * Define some portability stuff
mfang@12442 33 .\" -----------------------------------------------------------------
mfang@12442 34 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
mfang@12442 35 .\"
mfang@12442 36 .\"
mfang@12442 37 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
mfang@12442 38 .ie \n(.g .ds Aq \(aq
mfang@12442 39 .el .ds Aq '
mfang@12442 40 .\" -----------------------------------------------------------------
mfang@12442 41 .\" * set default formatting
mfang@12442 42 .\" -----------------------------------------------------------------
mfang@12442 43 .\" disable hyphenation
mfang@12442 44 .nh
mfang@12442 45 .\" disable justification (adjust text to left margin only)
mfang@12442 46 .ad l
mfang@12442 47 .\" -----------------------------------------------------------------
mfang@12442 48 .\" * MAIN CONTENT STARTS HERE *
mfang@12442 49 .\" -----------------------------------------------------------------
michaelm@5116 50
rgallard@8813 51 .SH NAME
rgallard@8813 52 idlj \- Generates Java bindings for a specified Interface Definition Language (IDL) file\&.
rgallard@8813 53 .SH SYNOPSIS
rgallard@8813 54 .sp
rgallard@8813 55 .nf
michaelm@5116 56
rgallard@8813 57 \fBidlj\fR [ \fIoptions\fR ] \fIidlfile\fR
rgallard@8813 58 .fi
rgallard@8813 59 .sp
rgallard@8813 60 .TP
rgallard@8813 61 \fIoptions\fR
rgallard@8813 62 The command-line options\&. See Options\&. Options can appear in any order, but must precede the \f3idlfile\fR\&.
rgallard@8813 63 .TP
rgallard@8813 64 \fIidlfile\fR
rgallard@8813 65 The name of a file that contains Interface Definition Language (IDL) definitions\&.
rgallard@8813 66 .SH DESCRIPTION
rgallard@8813 67 The IDL-to-Java Compiler generates the Java bindings for a specified IDL file\&. For binding details, see Java IDL: IDL to Java Language Mapping at http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/idl/mapping/jidlMapping\&.html
rgallard@8813 68 .PP
rgallard@8813 69 Some earlier releases of the IDL-to-Java compiler were named \f3idltojava\fR\&.
rgallard@8813 71 The following \f3idlj\fR command generates an IDL file named \f3My\&.idl\fR with client-side bindings\&.
rgallard@8813 72 .sp
rgallard@8813 73 .nf
rgallard@8813 74 \f3idlj My\&.idl\fP
rgallard@8813 75 .fi
rgallard@8813 76 .nf
rgallard@8813 77 \f3\fR
rgallard@8813 78 .fi
rgallard@8813 79 .sp
rgallard@8813 80 The previous syntax is equivalent to the following:
rgallard@8813 81 .sp
rgallard@8813 82 .nf
rgallard@8813 83 \f3idlj \-fclient My\&.idl\fP
rgallard@8813 84 .fi
rgallard@8813 85 .nf
rgallard@8813 86 \f3\fR
rgallard@8813 87 .fi
rgallard@8813 88 .sp
rgallard@8813 89 The next example generates the server-side bindings, and includes the client-side bindings plus the skeleton, all of which are POA (Inheritance Model)\&.
rgallard@8813 90 .sp
rgallard@8813 91 .nf
rgallard@8813 92 \f3idlg \-fserver My\&.idl\fP
rgallard@8813 93 .fi
rgallard@8813 94 .nf
rgallard@8813 95 \f3\fR
rgallard@8813 96 .fi
rgallard@8813 97 .sp
rgallard@8813 98 If you want to generate both client and server-side bindings, then use one of the following (equivalent) commands:
rgallard@8813 99 .sp
rgallard@8813 100 .nf
rgallard@8813 101 \f3idlj \-fclient \-fserver My\&.idl\fP
rgallard@8813 102 .fi
rgallard@8813 103 .nf
rgallard@8813 104 \f3idlj \-fall My\&.idl\fP
rgallard@8813 105 .fi
rgallard@8813 106 .nf
rgallard@8813 107 \f3\fR
rgallard@8813 108 .fi
rgallard@8813 109 .sp
rgallard@8813 110 There are two possible server-side models: the Portal Servant Inheritance Model and the Tie Model\&. See Tie Delegation Model\&.
rgallard@8813 111 .PP
rgallard@8813 112 \f3Portable Servant Inheritance Model\fR\&. The default server-side model is the Portable Servant Inheritance Model\&. Given an interface \f3My\fR defined in \f3My\&.idl\fR, the file \f3MyPOA\&.java\fR is generated\&. You must provide the implementation for the \f3My\fR interface, and the \f3My\fR interface must inherit from the \f3MyPOA\fR class\&. \f3MyPOA\&.java\fR is a stream-based skeleton that extends the \f3org\&.omg\&.PortableServer\&.Servant\fR class at http://docs\&.oracle\&.com/javase/8/docs/api/org/omg/PortableServer/Servant\&.html The \f3My\fR interface implements the \f3callHandler\fR interface and the operations interface associated with the IDL interface the skeleton implements\&.The \f3PortableServer\fR module for the Portable Object Adapter (POA) defines the native \f3Servant\fR type\&. See Portable Object Adapter (POA) at http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/idl/POA\&.html In the Java programming language, the \f3Servant\fR type is mapped to the Java \f3org\&.omg\&.PortableServer\&.Servant\fR class\&. It serves as the base class for all POA servant implementations and provides a number of methods that can be called by the application programmer, and methods that are called by the POA and that can be overridden by the user to control aspects of servant behavior\&.Another option for the Inheritance Model is to use the \f3-oldImplBase\fR flag to generate server-side bindings that are compatible with releases of the Java programming language before Java SE 1\&.4\&. The -\f3oldImplBase\fR flag is nonstandard, and these APIs are deprecated\&. You would use this flag only for compatibility with existing servers written in Java SE 1\&.3\&. In that case, you would need to modify an existing make file to add the \f3-oldImplBase\fR flag to the \f3idlj\fR compiler\&. Otherwise POA-based server-side mappings are generated\&. To generate server-side bindings that are backward compatible, do the following:
rgallard@8813 113 .sp
rgallard@8813 114 .nf
rgallard@8813 115 \f3idlj \-fclient \-fserver \-oldImplBase My\&.idl\fP
rgallard@8813 116 .fi
rgallard@8813 117 .nf
rgallard@8813 118 \f3idlj \-fall \-oldImplBase My\&.idl\fP
rgallard@8813 119 .fi
rgallard@8813 120 .nf
rgallard@8813 121 \f3\fR
rgallard@8813 122 .fi
rgallard@8813 123 .sp
rgallard@8813 124 Given an interface \f3My\fR defined in \f3My\&.idl\fR, the file \f3_MyImplBase\&.java\fR is generated\&. You must provide the implementation for the \f3My\fR interface, and the \f3My\fR interface must inherit from the \f3_MyImplBase\fR class\&.
rgallard@8813 125 .PP
rgallard@8813 126 \f3Tie Delegation Model\fR\&. The other server-side model is called the Tie Model\&. This is a delegation 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:
rgallard@8813 127 .sp
rgallard@8813 128 .nf
rgallard@8813 129 \f3idlj \-fall My\&.idl\fP
rgallard@8813 130 .fi
rgallard@8813 131 .nf
rgallard@8813 132 \f3idlj \-fallTIE My\&.idl\fP
rgallard@8813 133 .fi
rgallard@8813 134 .nf
rgallard@8813 135 \f3\fR
rgallard@8813 136 .fi
rgallard@8813 137 .sp
rgallard@8813 138 For the \f3My\fR interface, the second command generates \f3MyPOATie\&.java\fR\&. The constructor to the \f3MyPOATie\fR class takes a delegate\&. In this example, using the default POA model, the constructor also needs a POA\&. You must provide the implementation for the delegate, but it does not have to inherit from any other class, only the interface \f3MyOperations\fR\&. To use it with the ORB, you must wrap your implementation within the \f3MyPOATie\fR class, for example:
rgallard@8813 139 .sp
rgallard@8813 140 .nf
rgallard@8813 141 \f3ORB orb = ORB\&.init(args, System\&.getProperties());\fP
rgallard@8813 142 .fi
rgallard@8813 143 .nf
rgallard@8813 144 \f3\fR
rgallard@8813 145 .fi
rgallard@8813 146 .nf
rgallard@8813 147 \f3// Get reference to rootpoa & activate the POAManager\fP
rgallard@8813 148 .fi
rgallard@8813 149 .nf
rgallard@8813 150 \f3POA rootpoa = (POA)orb\&.resolve_initial_references("RootPOA");\fP
rgallard@8813 151 .fi
rgallard@8813 152 .nf
rgallard@8813 153 \f3rootpoa\&.the_POAManager()\&.activate();\fP
rgallard@8813 154 .fi
rgallard@8813 155 .nf
rgallard@8813 156 \f3\fR
rgallard@8813 157 .fi
rgallard@8813 158 .nf
rgallard@8813 159 \f3// create servant and register it with the ORB\fP
rgallard@8813 160 .fi
rgallard@8813 161 .nf
rgallard@8813 162 \f3MyServant myDelegate = new MyServant();\fP
rgallard@8813 163 .fi
rgallard@8813 164 .nf
rgallard@8813 165 \f3myDelegate\&.setORB(orb); \fP
rgallard@8813 166 .fi
rgallard@8813 167 .nf
rgallard@8813 168 \f3\fR
rgallard@8813 169 .fi
rgallard@8813 170 .nf
rgallard@8813 171 \f3// create a tie, with servant being the delegate\&.\fP
rgallard@8813 172 .fi
rgallard@8813 173 .nf
rgallard@8813 174 \f3MyPOATie tie = new MyPOATie(myDelegate, rootpoa);\fP
rgallard@8813 175 .fi
rgallard@8813 176 .nf
rgallard@8813 177 \f3\fR
rgallard@8813 178 .fi
rgallard@8813 179 .nf
rgallard@8813 180 \f3// obtain the objectRef for the tie\fP
rgallard@8813 181 .fi
rgallard@8813 182 .nf
rgallard@8813 183 \f3My ref = tie\&._this(orb);\fP
rgallard@8813 184 .fi
rgallard@8813 185 .nf
rgallard@8813 186 \f3\fR
rgallard@8813 187 .fi
rgallard@8813 188 .sp
rgallard@8813 189 You might want to use the Tie model instead of the typical Inheritance model when 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 inheritance model, then that slot is used up\&. With the Tie Model, that slot is freed up for your own use\&. The drawback is that it introduces a level of indirection: one extra method call occurs when a method is called\&.
rgallard@8813 190 .PP
rgallard@8813 191 For server-side generation, Tie model bindings that are compatible with versions of the IDL to Java language mapping in versions earlier than Java SE 1\&.4\&.
rgallard@8813 192 .sp
rgallard@8813 193 .nf
rgallard@8813 194 \f3idlj \-oldImplBase \-fall My\&.idl\fP
rgallard@8813 195 .fi
rgallard@8813 196 .nf
rgallard@8813 197 \f3idlj \-oldImplBase \-fallTIE My\&.idl\fP
rgallard@8813 198 .fi
rgallard@8813 199 .nf
rgallard@8813 200 \f3\fR
rgallard@8813 201 .fi
rgallard@8813 202 .sp
rgallard@8813 203 For the \f3My\fR interface, the this generates \f3My_Tie\&.java\fR\&. The constructor to the \f3My_Tie\fR class takes an \f3impl\fR object\&. You must provide the implementation for \f3impl\fR, but it does not have to inherit from any other class, only the interface \f3HelloOperations\fR\&. But to use it with the ORB, you must wrap your implementation within \f3My_Tie\fR, for example:
rgallard@8813 204 .sp
rgallard@8813 205 .nf
rgallard@8813 206 \f3ORB orb = ORB\&.init(args, System\&.getProperties());\fP
rgallard@8813 207 .fi
rgallard@8813 208 .nf
rgallard@8813 209 \f3\fR
rgallard@8813 210 .fi
rgallard@8813 211 .nf
rgallard@8813 212 \f3// create servant and register it with the ORB\fP
rgallard@8813 213 .fi
rgallard@8813 214 .nf
rgallard@8813 215 \f3MyServant myDelegate = new MyServant();\fP
rgallard@8813 216 .fi
rgallard@8813 217 .nf
rgallard@8813 218 \f3myDelegate\&.setORB(orb); \fP
rgallard@8813 219 .fi
rgallard@8813 220 .nf
rgallard@8813 221 \f3\fR
rgallard@8813 222 .fi
rgallard@8813 223 .nf
rgallard@8813 224 \f3// create a tie, with servant being the delegate\&.\fP
rgallard@8813 225 .fi
rgallard@8813 226 .nf
rgallard@8813 227 \f3MyPOATie tie = new MyPOATie(myDelegate);\fP
rgallard@8813 228 .fi
rgallard@8813 229 .nf
rgallard@8813 230 \f3\fR
rgallard@8813 231 .fi
rgallard@8813 232 .nf
rgallard@8813 233 \f3// obtain the objectRef for the tie\fP
rgallard@8813 234 .fi
rgallard@8813 235 .nf
rgallard@8813 236 \f3My ref = tie\&._this(orb);\fP
rgallard@8813 237 .fi
rgallard@8813 238 .nf
rgallard@8813 239 \f3\fR
rgallard@8813 240 .fi
rgallard@8813 241 .sp
rgallard@8813 243 If you want to direct the emitted files to a directory other than the current directory, then call the compiler this way: \f3i\fR\f3dlj -td /altdir My\&.idl\fR\&.
rgallard@8813 244 .PP
rgallard@8813 245 For the \f3My\fR interface, the bindings are emitted to \f3/altdir/My\&.java\fR, etc\&., instead of \f3\&./My\&.java\fR\&.
rgallard@8813 247 If the \f3My\&.idl\fR file includes another \f3idl\fR file, \f3MyOther\&.idl\fR, then the compiler assumes that the \f3MyOther\&.idl\fR file resides in the local directory\&. If it resides in \f3/includes\fR, for example, then you call the compiler with the following command:
rgallard@8813 248 .sp
rgallard@8813 249 .nf
rgallard@8813 250 \f3idlj \-i /includes My\&.idl\fP
rgallard@8813 251 .fi
rgallard@8813 252 .nf
rgallard@8813 253 \f3\fR
rgallard@8813 254 .fi
rgallard@8813 255 .sp
rgallard@8813 256 If \f3My\&.idl\fR also included \f3Another\&.idl\fR that resided in \f3/moreIncludes\fR, for example, then you call the compiler with the following command:
rgallard@8813 257 .sp
rgallard@8813 258 .nf
rgallard@8813 259 \f3idlj \-i /includes \-i /moreIncludes My\&.idl\fP
rgallard@8813 260 .fi
rgallard@8813 261 .nf
rgallard@8813 262 \f3\fR
rgallard@8813 263 .fi
rgallard@8813 264 .sp
rgallard@8813 265 Because this form of \f3include\fR can become long, another way to indicate to the compiler where to search for included files is provided\&. This technique is similar to the idea of an environment variable\&. Create a file named idl\&.config in a directory that is listed in your \f3CLASSPATH\fR variable\&. Inside of \f3idl\&.config\fR, provide a line with the following form:
rgallard@8813 266 .sp
rgallard@8813 267 .nf
rgallard@8813 268 \f3includes=/includes;/moreIncludes\fP
rgallard@8813 269 .fi
rgallard@8813 270 .nf
rgallard@8813 271 \f3\fR
rgallard@8813 272 .fi
rgallard@8813 273 .sp
rgallard@8813 274 The compiler will find this file and read in the includes list\&. Note that in this example the separator character between the two directories is a semicolon (;)\&. This separator character is platform dependent\&. On the Windows platform, use a semicolon, on the Unix platform, use a colon, and so on\&.
rgallard@8813 276 By default, only those interfaces, structures, and so on, that are defined in the \f3idl\fR 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 \f3idl\fR files:
rgallard@8813 277 .sp
rgallard@8813 278 .nf
rgallard@8813 279 \f3My\&.idl file:\fP
rgallard@8813 280 .fi
rgallard@8813 281 .nf
rgallard@8813 282 \f3\fR
rgallard@8813 283 .fi
rgallard@8813 284 .nf
rgallard@8813 285 \f3#include <MyOther\&.idl>\fP
rgallard@8813 286 .fi
rgallard@8813 287 .nf
rgallard@8813 288 \f3interface My\fP
rgallard@8813 289 .fi
rgallard@8813 290 .nf
rgallard@8813 291 \f3{\fP
rgallard@8813 292 .fi
rgallard@8813 293 .nf
rgallard@8813 294 \f3};\fP
rgallard@8813 295 .fi
rgallard@8813 296 .nf
rgallard@8813 297 \f3\fR
rgallard@8813 298 .fi
rgallard@8813 299 .nf
rgallard@8813 300 \f3MyOther\&.idl file:\fP
rgallard@8813 301 .fi
rgallard@8813 302 .nf
rgallard@8813 303 \f3\fR
rgallard@8813 304 .fi
rgallard@8813 305 .nf
rgallard@8813 306 \f3interface MyOther\fP
rgallard@8813 307 .fi
rgallard@8813 308 .nf
rgallard@8813 309 \f3{\fP
rgallard@8813 310 .fi
rgallard@8813 311 .nf
rgallard@8813 312 \f3};\fP
rgallard@8813 313 .fi
rgallard@8813 314 .nf
rgallard@8813 315 \f3\fR
rgallard@8813 316 .fi
rgallard@8813 317 .sp
rgallard@8813 318 There is a caveat to the default rule\&. Any \f3#include\fR statements that appear at the global scope are treated as described\&. These \f3#include\fR statements can be thought of as import statements\&. The \f3#include\fR statements that appear within an enclosed scope are treated as true \f3#include\fR statements, which means that the code within the included file is treated as though it appeared in the original file and, therefore, Java bindings are emitted for it\&. Here is an example:
rgallard@8813 319 .sp
rgallard@8813 320 .nf
rgallard@8813 321 \f3My\&.idl file:\fP
rgallard@8813 322 .fi
rgallard@8813 323 .nf
rgallard@8813 324 \f3\fR
rgallard@8813 325 .fi
rgallard@8813 326 .nf
rgallard@8813 327 \f3#include <MyOther\&.idl>\fP
rgallard@8813 328 .fi
rgallard@8813 329 .nf
rgallard@8813 330 \f3interface My\fP
rgallard@8813 331 .fi
rgallard@8813 332 .nf
rgallard@8813 333 \f3{\fP
rgallard@8813 334 .fi
rgallard@8813 335 .nf
rgallard@8813 336 \f3 #include <Embedded\&.idl>\fP
rgallard@8813 337 .fi
rgallard@8813 338 .nf
rgallard@8813 339 \f3};\fP
rgallard@8813 340 .fi
rgallard@8813 341 .nf
rgallard@8813 342 \f3\fR
rgallard@8813 343 .fi
rgallard@8813 344 .nf
rgallard@8813 345 \f3MyOther\&.idl file:\fP
rgallard@8813 346 .fi
rgallard@8813 347 .nf
rgallard@8813 348 \f3\fR
rgallard@8813 349 .fi
rgallard@8813 350 .nf
rgallard@8813 351 \f3interface MyOther\fP
rgallard@8813 352 .fi
rgallard@8813 353 .nf
rgallard@8813 354 \f3{\fP
rgallard@8813 355 .fi
rgallard@8813 356 .nf
rgallard@8813 357 \f3};\fP
rgallard@8813 358 .fi
rgallard@8813 359 .nf
rgallard@8813 360 \f3\fR
rgallard@8813 361 .fi
rgallard@8813 362 .nf
rgallard@8813 363 \f3Embedded\&.idl\fP
rgallard@8813 364 .fi
rgallard@8813 365 .nf
rgallard@8813 366 \f3\fR
rgallard@8813 367 .fi
rgallard@8813 368 .nf
rgallard@8813 369 \f3enum E {one, two, three};\fP
rgallard@8813 370 .fi
rgallard@8813 371 .nf
rgallard@8813 372 \f3\fR
rgallard@8813 373 .fi
rgallard@8813 374 .sp
rgallard@8813 375 Run\f3idlj My\&.idl\fRto generate the following list of Java files\&. Notice that \f3MyOther\&.java\fR is not generated because it is defined in an import-like \f3#include\fR\&. But \f3E\&.java\fR was generated because it was defined in a true \f3#include\fR\&. Notice that because the \f3Embedded\&.idl\fR file is included within the scope of the interface \f3My\fR, it appears within the scope of \f3My\fR (in \f3MyPackage\fR)\&. If the \f3-emitAll\fR flag had been used, then all types in all included files would have been emitted\&.
rgallard@8813 376 .sp
rgallard@8813 377 .nf
rgallard@8813 378 \f3\&./MyHolder\&.java\fP
rgallard@8813 379 .fi
rgallard@8813 380 .nf
rgallard@8813 381 \f3\&./MyHelper\&.java\fP
rgallard@8813 382 .fi
rgallard@8813 383 .nf
rgallard@8813 384 \f3\&./_MyStub\&.java\fP
rgallard@8813 385 .fi
rgallard@8813 386 .nf
rgallard@8813 387 \f3\&./MyPackage\fP
rgallard@8813 388 .fi
rgallard@8813 389 .nf
rgallard@8813 390 \f3\&./MyPackage/EHolder\&.java\fP
rgallard@8813 391 .fi
rgallard@8813 392 .nf
rgallard@8813 393 \f3\&./MyPackage/EHelper\&.java\fP
rgallard@8813 394 .fi
rgallard@8813 395 .nf
rgallard@8813 396 \f3\&./MyPackage/E\&.java\fP
rgallard@8813 397 .fi
rgallard@8813 398 .nf
rgallard@8813 399 \f3\&./My\&.java\fP
rgallard@8813 400 .fi
rgallard@8813 401 .nf
rgallard@8813 402 \f3\fR
rgallard@8813 403 .fi
rgallard@8813 404 .sp
rgallard@8813 405 .SS INSERT\ PACKAGE\ PREFIXES
rgallard@8813 406 Suppose that you work for a company named ABC that has constructed the following IDL file:
rgallard@8813 407 .sp
rgallard@8813 408 .nf
rgallard@8813 409 \f3Widgets\&.idl file:\fP
rgallard@8813 410 .fi
rgallard@8813 411 .nf
rgallard@8813 412 \f3\fR
rgallard@8813 413 .fi
rgallard@8813 414 .nf
rgallard@8813 415 \f3module Widgets\fP
rgallard@8813 416 .fi
rgallard@8813 417 .nf
rgallard@8813 418 \f3{\fP
rgallard@8813 419 .fi
rgallard@8813 420 .nf
rgallard@8813 421 \f3 interface W1 {\&.\&.\&.};\fP
rgallard@8813 422 .fi
rgallard@8813 423 .nf
rgallard@8813 424 \f3 interface W2 {\&.\&.\&.};\fP
rgallard@8813 425 .fi
rgallard@8813 426 .nf
rgallard@8813 427 \f3};\fP
rgallard@8813 428 .fi
rgallard@8813 429 .nf
rgallard@8813 430 \f3\fR
rgallard@8813 431 .fi
rgallard@8813 432 .sp
rgallard@8813 433 If you run this file through the IDL-to-Java compiler, then the Java bindings for W1 and W2 are placed within the \f3Widgets\fR package\&. There is an industry convention that states that a company\&'s packages should reside within a package named \f3com\&.<company name>\fR\&. To follow this convention, the package name should be \f3com\&.abc\&.Widgets\fR\&. To place this package prefix onto the Widgets module, execute the following:
rgallard@8813 434 .sp
rgallard@8813 435 .nf
rgallard@8813 436 \f3idlj \-pkgPrefix Widgets com\&.abc Widgets\&.idl\fP
rgallard@8813 437 .fi
rgallard@8813 438 .nf
rgallard@8813 439 \f3\fR
rgallard@8813 440 .fi
rgallard@8813 441 .sp
rgallard@8813 442 If you have an IDL file that includes Widgets\&.idl, then the \f3-pkgPrefix\fR flag must appear in that command also\&. If it does not, then your IDL file will be looking for a \f3Widgets\fR package rather than a \f3com\&.abc\&.Widgets\fR package\&.
rgallard@8813 443 .PP
rgallard@8813 444 If you have a number of these packages that require prefixes, then it might be easier to place them into the idl\&.config file described previously\&. Each package prefix line should be of the form: \f3PkgPrefix\&.<type>=<prefix>\fR\&. The line for the previous example would be \f3PkgPrefix\&.Widgets=com\&.abc\fR\&. This option does not affect the Repository ID\&.
rgallard@8813 446 You might 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 \f3idlj -d MYDEF My\&.idl\fRis equivalent to putting the line \f3#define MYDEF\fR inside My\&.idl\&.
rgallard@8813 448 If the Java binding files already exist, then the \f3-keep\fR flag keeps the compiler from overwriting them\&. The default is to generate all files without considering that they already exist\&. If you have customized those files (which you should not do unless you are very comfortable with their contents), then the \f3-keep\fR option is very useful\&. The command \f3idlj -keep My\&.idl\fR emits all client-side bindings that do not already exist\&.
rgallard@8813 450 The IDL-to-Java compiler generates status messages as it progresses through its phases of execution\&. Use the \f3-v\fR option to activate the verbose mode: \f3idlj -v My\&.idl\fR\&.
rgallard@8813 451 .PP
rgallard@8813 452 By default the compiler does not operate in verbose mode
rgallard@8813 454 To display the build version of the IDL-to-Java compiler, specify the \f3-version\fR option on the command-line: \f3idlj -version\fR\&.
rgallard@8813 455 .PP
rgallard@8813 456 Version information also appears within the bindings generated by the compiler\&. Any additional options appearing on the command-line are ignored\&.
rgallard@8813 457 .SH OPTIONS
rgallard@8813 458 .TP
rgallard@8813 459 -d \fIsymbol\fR
rgallard@8813 460 .br
rgallard@8813 461 This is equivalent to the following line in an IDL file:
rgallard@8813 462 .sp
rgallard@8813 463 .nf
rgallard@8813 464 \f3#define \fIsymbol\fR\fP
rgallard@8813 465 .fi
rgallard@8813 466 .nf
rgallard@8813 467 \f3\fR
rgallard@8813 468 .fi
rgallard@8813 469 .sp
michaelm@5116 470
rgallard@8813 471 .TP
rgallard@8813 472 -demitAll
rgallard@8813 473 .br
rgallard@8813 474 Emit all types, including those found in \f3#include\fR files\&.
rgallard@8813 475 .TP
rgallard@8813 476 -fside
rgallard@8813 477 .br
rgallard@8813 478 Defines what bindings to emit\&. The \f3side\fR parameter can be \f3client\fR, \f3server\fR, \f3serverTIE\fR, \f3all\fR, or \f3allTIE\fR\&. The \f3-fserverTIE\fR and \f3-fallTIE\fR options cause delegate model skeletons to be emitted\&. Defaults to \f3-fclient\fR when the flag is not specified\&.
rgallard@8813 479 .TP
rgallard@8813 480 -i \fIinclude-path\fR
rgallard@8813 481 .br
rgallard@8813 482 By default, the current directory is scanned for included files\&. This option adds another directory\&.
rgallard@8813 483 .TP
rgallard@8813 484 -i \fIkeep\fR
rgallard@8813 485 .br
rgallard@8813 486 If a file to be generated already exists, then do not overwrite it\&. By default it is overwritten\&.
rgallard@8813 487 .TP
rgallard@8813 488 -noWarn
rgallard@8813 489 .br
rgallard@8813 490 Suppress warning messages\&.
rgallard@8813 491 .TP
rgallard@8813 492 -oldImplBase
rgallard@8813 493 .br
rgallard@8813 494 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 earlier releases of the Java programming language by generating server-side bindings that are \f3ImplBase\fR Inheritance Model classes\&.
rgallard@8813 495 .TP
rgallard@8813 496 -pkgPrefix \fItype\fR\fIprefix\fR
rgallard@8813 497 .br
rgallard@8813 498 Wherever \f3type\fR is encountered at file scope, prefix the generated Java package name with \f3prefix\fR 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\&.
rgallard@8813 499 .TP
rgallard@8813 500 -pkgTranslate \fItype\fR\fIpackage\fR
rgallard@8813 501 .br
rgallard@8813 502 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 \f3pkgPrefix\fR changes are made first\&. The type value 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\&.
michaelm@5116 503
rgallard@8813 504 If more than one translation matches an identifier, then the longest match is chosen as shown in the following example:
michaelm@5116 505
rgallard@8813 506 \fICommand\fR:
rgallard@8813 507 .sp
rgallard@8813 508 .nf
rgallard@8813 509 \f3pkgTranslate type pkg \-pkgTranslate type2\&.baz pkg2\&.fizz\fP
rgallard@8813 510 .fi
rgallard@8813 511 .nf
rgallard@8813 512 \f3\fR
rgallard@8813 513 .fi
rgallard@8813 514 .sp
michaelm@5116 515
michaelm@5116 516
rgallard@8813 517 \fIResulting Translation\fR:
rgallard@8813 518 .sp
rgallard@8813 519 .nf
rgallard@8813 520 \f3type => pkg\fP
rgallard@8813 521 .fi
rgallard@8813 522 .nf
rgallard@8813 523 \f3type\&.ext => pkg\&.ext\fP
rgallard@8813 524 .fi
rgallard@8813 525 .nf
rgallard@8813 526 \f3type\&.baz => pkg2\&.fizz\fP
rgallard@8813 527 .fi
rgallard@8813 528 .nf
rgallard@8813 529 \f3type2\&.baz\&.pkg => pkg2\&.fizz\&.pkg\fP
rgallard@8813 530 .fi
rgallard@8813 531 .nf
rgallard@8813 532 \f3\fR
rgallard@8813 533 .fi
rgallard@8813 534 .sp
michaelm@5116 535
michaelm@5116 536
rgallard@8813 537 The following package names \f3org\fR, \f3org\fR\&.o\f3mg\fR, or any subpackages of \f3org\&.omg\fR cannot be translated\&. Any attempt to translate these packages results in uncompilable code, and the use of these packages as the first argument after \f3-pkgTranslate\fR is treated as an error\&.
rgallard@8813 538 .TP
rgallard@8813 539 -skeletonName \fIxxx%yyy\fR
michaelm@5116 540 .br
rgallard@8813 541 Use \f3xxx%yyy\fR as the pattern for naming the skeleton\&. The defaults are: \f3%POA\fR for the \f3POA\fR base class (\f3-fserver\fR or \f3-fall\fR), and \f3_%ImplBase\fR for the \f3oldImplBase\fR class (-\f3oldImplBase\fR) and (\f3-fserver\fR or \f3-fall\fR))\&.
rgallard@8813 542 .TP
rgallard@8813 543 -td \fIdir\fR
michaelm@5116 544 .br
rgallard@8813 545 Use \fIdir\fR for the output directory instead of the current directory\&.
rgallard@8813 546 .TP
rgallard@8813 547 -tieName \fIxxx%yyy\fR
rgallard@8813 548 .br
rgallard@8813 549 Use \f3xxx%yyy\fR according to the pattern\&. The defaults are: \f3%POA\fR for the \f3POA\fR base class (\f3-fserverTie or -fallTie\fR), and \f3_%Tie\fR for the \f3oldImplBase\fR tie class (-\f3oldImplBase\fR) and (\f3-fserverTie\fR or \f3-fallTie\fR))
rgallard@8813 550 .TP
rgallard@8813 551 -nowarn, -verbose
rgallard@8813 552 .br
rgallard@8813 553 Displays release information and terminates\&.
rgallard@8813 554 .TP
rgallard@8813 555 -version
rgallard@8813 556 .br
rgallard@8813 557 Displays release information and terminates\&.
rgallard@8813 558 .SH RESTRICTIONS
rgallard@8813 559 Escaped identifiers in the global scope cannot have the same spelling as IDL primitive types, \f3Object\fR, or \f3ValueBase\fR\&. This is because the symbol table is preloaded with these identifiers\&. Allowing them to be redefined would overwrite their original definitions\&. Possible permanent restriction\&.
rgallard@8813 560 .PP
rgallard@8813 561 The \f3fixed\fR IDL type is not supported\&.
rgallard@8813 562 .SH KNOWN\ PROBLEMS
rgallard@8813 563 No import is generated for global identifiers\&. If you call an unexported local \f3impl\fR object, then you do get an exception, but it seems to be due to a \f3NullPointerException\fR in the \f3ServerDelegate\fR DSI code\&.
mfang@12442 564 .RE
mfang@12442 565 .br
mfang@12442 566 'pl 8.5i
mfang@12442 567 'bp