1 <HTML> 2 <HEAD> 3 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> 4 <META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en]C-gatewaynet (WinNT; U) 5 [Netscape]"> 6 <TITLE>package</TITLE> 7 <!-- 8 /* 9 * Copyright (c) 1998, 2015, Oracle and/or its affiliates. All rights reserved. 10 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 11 * 12 * This code is free software; you can redistribute it and/or modify it 13 * under the terms of the GNU General Public License version 2 only, as 14 * published by the Free Software Foundation. Oracle designates this 15 * particular file as subject to the "Classpath" exception as provided 16 * by Oracle in the LICENSE file that accompanied this code. 17 * 18 * This code is distributed in the hope that it will be useful, but WITHOUT 19 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 20 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 21 * version 2 for more details (a copy is included in the LICENSE file that 22 * accompanied this code). 23 * 24 * You should have received a copy of the GNU General Public License version 25 * 2 along with this work; if not, write to the Free Software Foundation, 26 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 27 * 28 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 29 * or visit www.oracle.com if you need additional information or have any 30 * questions. 31 */ 32 --> 33 </HEAD> 34 <BODY BGCOLOR="#FFFFFF"> 35 Provides the mapping of the OMG CORBA APIs to the Java<SUP><FONT 36 SIZE=-2>TM</FONT></SUP> 37 programming language, including the class <TT>ORB</TT>, which is implemented 38 so that a programmer can use it as a fully-functional Object Request Broker 39 (ORB). 40 41 <P>For a precise list of supported sections of official CORBA specifications with which 42 the Java[TM] Platform, Standard Edition 6 complies, see <A 43 HREF="doc-files/compliance.html"><em>Official Specifications for CORBA support in 44 Java[TM] SE 6</em></A>. 45 46 47 <H1>General Information</H1> 48 The information in this section is information relevant to someone who 49 compiles Interface Definition Language (IDL) files and uses the 50 ORB to write clients and servers. 51 52 <P>The classes and interfaces described in this section can be put into 53 four groups: <tt>ORB classes</tt>, Exceptions, <tt>Helper</tt> classes, 54 and <tt>Holder</tt> classes. 55 56 <H2> 57 The <tt>ORB</tt> Class</H2> 58 59 <P>An ORB handles (or brokers) method invocations between a client and 60 the method's implementation on a server. Because the client and server 61 may be anywhere on a network, and because the invocation and implementation 62 may be written in different programming languages, an ORB does a great 63 deal of work behind the scenes to accomplish this communication. 64 65 <P>Most of what an ORB does is completely transparent to the user, and a major 66 portion of the <TT>CORBA</TT> package consists of classes used by the ORB 67 behind the scenes. The result is that most programmers will use only a 68 small part of this package directly. In fact, most programmers will use 69 only a few methods from the <TT>ORB</TT> class, some exceptions, and 70 occasionally, 71 a holder class. 72 <H3> 73 <TT>ORB</TT> Methods</H3> 74 75 <P>Before an application can enter the CORBA environment, it must first: 76 <UL> 77 <LI>Be initialized into the ORB and possibly the object adapter (POA) environments. 78 <LI>Get references to ORB object (for use in future ORB operations) 79 and perhaps other objects (including the root POA or some Object Adapter objects). 80 </UL> 81 <P>The following operations are provided to initialize applications and obtain 82 the appropriate object references: 83 <UL> 84 <LI>Operations providing access to the ORB, which are discussed in this 85 section. 86 <LI>Operations providing access to Object Adapters, Interface Repository, 87 Naming Service, and other Object Services. These operations are described 88 in <a href="#adv"><em>Other Classes</em></a>. 89 </UL> 90 <P> 91 When an application requires a CORBA environment it needs a mechanism to 92 get an ORB object reference and possibly an OA object reference 93 (such as the root POA). This serves two purposes. First, it initializes 94 an application into the ORB and OA environments. Second, it returns the 95 ORB object reference and the OA object reference to the application 96 for use in future ORB and OA operations. 97 98 <P>In order to obtain an ORB object reference, applications call 99 the <tt>ORB.init</tt> operation. The parameters to the call can comprise an 100 identifier for the ORB for which the object reference is required, 101 and an arg_list, which is used to allow environment-specific data to be 102 passed into the call. 103 104 <P>These are the <TT>ORB</TT> methods 105 that provide access to the ORB: 106 <UL> 107 <LI> 108 <TT><b>init</b>()</TT> 109 110 <LI> 111 <TT><b>init</b>(String [] args, Properties props)</TT> 112 113 <LI> 114 <TT><b>init</b>(Applet app, Properties props)</TT> 115 </UL> 116 117 <P>Using the <tt>init()</tt> method without parameters initiates 118 a singleton ORB, which can only 119 give typecode creation <tt>any</tt>s needed in code generated 120 in Helper classes by <tt>idlj</tt>. 121 122 <P>Applications require a portable means by which to obtain their 123 initial object references. References are required for the root 124 POA, POA Current, Interface Repository, and various Object Services 125 instances. The functionality required by the application is similar 126 to that provided by the Naming Service. However, the OMG does not 127 want to mandate that the Naming Service be made available to all 128 applications in order that they may be portably initialized. 129 Consequently, the operations shown in this section provide a 130 simplified, local version of the Naming Service that applications 131 can use to obtain a small, defined set of object references which 132 are essential to its operation. Because only a small well-defined 133 set of objects are expected with this mechanism, the naming context 134 can be flattened to be a single-level name space. This simplification 135 results in only two operations being defined to achieve the functionality 136 required. 137 138 <P>Initial references are obtained via two operations provided in 139 the ORB object interface, providing facilities to list and 140 resolve initial object references. These are: 141 <UL> 142 <LI> 143 <TT><b>resolve_initial_references</b>(String name)</TT> 144 <LI> 145 <TT><b>list_initial_services</b>()</TT> 146 <LI> 147 <TT><b>register_initial_reference</b>(String id, 148 org.omg.CORBA.Object obj)</TT> 149 </UL> 150 151 <P>An example that uses some of these methods is <A 152 HREF="{@docRoot}/../technotes/guides/idl/GShome.html"> 153 <em>Getting Started with Java IDL</em></A>. 154 155 <H2> 156 Exceptions</H2> 157 Exceptions in Java IDL are similar to those in any code written in the 158 Java programming language. If a method is defined to throw an exception, 159 then any code using that method must have a <TT>try</TT>/<TT>catch</TT> 160 block and handle that exception when it is thrown. 161 162 <P>The documentation on <A 163 HREF="{@docRoot}/../technotes/guides/idl/jidlExceptions.html"><em>Java 164 IDL exceptions</em></A> has more information and explains the difference between 165 system exceptions and user-defined exceptions. 166 167 <P>The following is a list of the system exceptions (which are unchecked 168 exceptions inheriting through <TT><a href="SystemException.html"> 169 org.omg.CORBA.SystemException</a></TT> from 170 <TT>java.lang.RuntimeException</TT>) that are defined in the package 171 <TT>org.omg.CORBA</TT>: 172 <PRE><code> 173 BAD_CONTEXT 174 BAD_INV_ORDER 175 BAD_OPERATION 176 BAD_PARAM 177 BAD_TYPECODE 178 COMM_FAILURE 179 DATA_CONVERSION 180 FREE_MEM 181 IMP_LIMIT 182 INITIALIZE 183 INTERNAL 184 INTF_REPOS 185 INVALID_TRANSACTION 186 INV_FLAG 187 INV_IDENT 188 INV_OBJREF 189 INV_POLICY 190 MARSHAL 191 <a href="#NO_IMPLEMENT">NO_IMPLEMENT</a> 192 NO_MEMORY 193 NO_PERMISSION 194 NO_RESOURCES 195 NO_RESPONSE 196 OBJECT_NOT_EXIST 197 OBJ_ADAPTER 198 PERSIST_STORE 199 TRANSACTION_REQUIRED 200 TRANSACTION_ROLLEDBACK 201 TRANSIENT 202 UNKNOWN 203 </code></PRE> 204 <P> 205 The following is a list of user-defined exceptions defined in the package 206 <TT>org.omg.CORBA</TT>. 207 <PRE><code> 208 Bounds 209 UnknownUserException 210 WrongTransaction 211 PolicyError 212 </code></PRE> 213 214 <H2>Subpackages</H2> 215 There are some packages inside the <TT>CORBA</TT> package with 216 "Package" as part of their names. These packages are generally quite small 217 because all they do is provide exceptions or classes for use by interfaces 218 and classes in the <TT>CORBA</TT> package. 219 220 <P>For example, the package <TT><a href="TypeCodePackage/package-summary.html"> 221 org.omg.CORBA.TypeCodePackage</a></TT> contains 222 two exceptions thrown by methods in the class <TT>TypeCode</TT>. These 223 exceptions are: 224 <UL> 225 <LI> 226 <TT>BadKind</TT> 227 228 <LI> 229 <TT>Bounds</TT> 230 </UL> 231 The package <TT><a href="ORBPackage/package-summary.html"> 232 org.omg.CORBA.ORBPackage</a></TT> contains two exceptions: 233 <UL> 234 <LI> 235 <TT>InvalidName</TT> 236 237 <LI> 238 <TT>InconsistentTypeCode</TT> 239 </UL> 240 241 <P>Another package that is a subpackage of <tt>CORBA</tt> is the <tt> 242 <a href="portable/package-summary.html">portable</a></tt> package. It 243 provides a set of ORB APIs that makes it 244 possible for code generated by one vendor's IDL compiler to run 245 on another vendor's ORB. 246 247 248 249 250 <H2> 251 Holder classes</H2> 252 253 254 <P>Support for out and inout parameter passing modes requires the use of 255 additional <em><a href="doc-files/generatedfiles.html#holder">holder 256 classes</a></em>. Because the Java programming language does not support out or 257 inout parameters, holder classes are needed as a means of passing a parameter 258 that can be modified. To support portable stubs and skeletons, holder classes also implement 259 the <tt><a href="portable/Streamable.html">org.omg.CORBA.portable.Streamable</a> 260 </tt> interface. 261 262 <P>Holder classes are named by appending "Holder" to the name of the type. 263 The name of the type refers to its name in the Java programming language. For 264 example, a holder class for the interface named <tt>Account</tt> in the Java programming 265 language would be named <tt>AccountHolder</tt>. 266 267 268 <P>Holder classes are available for all of the basic IDL 269 datatypes in the <tt>org.omg.CORBA</tt> package. So, for example, 270 there are already-defined classes for <tt>LongHolder</tt>, <tt>ShortHolder</tt>, 271 <tt>FloatHolder</tt>, and so on. Classes are also generated for 272 all named user-defined IDL types except those defined by <tt>typedefs</tt>. 273 (Note that in this context user defined includes types that are 274 defined in OMG specifications such as those for the Interface 275 Repository, and other OMG services.) 276 277 278 <P>Each holder class has: 279 <UL> 280 <LI>a constructor from an instance 281 <LI>a default constructor 282 <LI>a public instance member, <tt>value</tt> which is the typed value. 283 <LI>a method for reading an input stream and assigning the contents to the 284 type's <tt>value</tt> field 285 <LI>a method for writing the value of the <tt>value</tt> field to an output stream 286 <LI>a method for getting the typecode of the type 287 </UL> 288 289 <P>The default constructor sets the value field to the default value for the 290 type as defined by the Java language: 291 <UL> 292 <LI><tt>false</tt> for boolean 293 <LI><tt>0</tt> for numeric and char types 294 <LI><tt>null</tt> for strings and object references 295 </UL> 296 297 298 299 <P> 300 As an example, if the interface <code>Account</code>, defined in OMG IDL, 301 were mapped to the Java programming language, the following holder class 302 would be generated: 303 <PRE> 304 public final class AccountHolder implements 305 org.omg.CORBA.portable.Streamable 306 { 307 // field that holds an Account object 308 public Account value = null; 309 310 // default constructor 311 public AccountHolder () 312 { 313 } 314 315 // creates a new AccountHolder from initialValue 316 public AccountHolder (Account initialValue) 317 { 318 value = initialValue; 319 } 320 321 // reads the contents of i and assigns the contents to value 322 public void _read (org.omg.CORBA.portable.InputStream i) 323 { 324 value = AccountHelper.read (i); 325 } 326 327 // writes value to o 328 public void _write (org.omg.CORBA.portable.OutputStream o) 329 { 330 AccountHelper.write (o, value); 331 } 332 333 // returns the typecode for Account 334 public org.omg.CORBA.TypeCode _type () 335 { 336 return AccountHelper.type (); 337 } 338 339 } 340 </PRE> 341 342 <P>For more information on Holder classes, see Chapter 1.4, <em>Mapping for 343 Basic Types</em> in the <a href="http://www.omg.org/cgi-bin/doc?ptc/00-01-08"> 344 <em>OMG IDL to Java Language Mapping</em></a>. The Holder classes defined 345 in the package <TT>org.omg.CORBA</TT> are: 346 <PRE> 347 <TT>AnyHolder 348 </TT> <TT>AnySeqHolder 349 </TT> <TT>BooleanHolder 350 </TT> <TT>BooleanSeqHolder 351 </TT> <TT>ByteHolder 352 </TT> <TT>CharHolder 353 </TT> <TT>CharSeqHolder 354 </TT> <TT>CurrentHolder 355 </TT> <TT>DoubleHolder 356 </TT> <TT>DoubleSeqHolder 357 </TT> <TT>FixedHolder 358 </TT> <TT>FloatHolder 359 </TT> <TT>FloatSeqHolder 360 </TT> <TT>IntHolder 361 </TT> <TT>LongHolder 362 </TT> <TT>LongLongSeqHolder 363 </TT> <TT>LongSeqHolder 364 </TT> <TT>ObjectHolder 365 </TT> <TT>OctetSeqHolder 366 </TT> <TT>ParameterModeHolder 367 </TT> <TT>PolicyErrorHolder 368 </TT> <TT>PolicyListHolder 369 </TT> <TT>PrincipalHolder 370 </TT> <TT>ServiceInformationHolder 371 </TT> <TT>ShortHolder 372 </TT> <TT>ShortSeqHolder 373 </TT> <TT>StringHolder 374 </TT> <TT>StringSeqHolder 375 </TT> <TT>TypeCodeHolder 376 </TT> <TT>ULongLongSeqHolder 377 </TT> <TT>ULongSeqHolder 378 </TT> <TT>UnknownUserExceptionHolder 379 </TT> <TT>UShortSeqHolder 380 </TT> <TT>ValueBaseHolder 381 </TT> <TT>WCharSeqHolder 382 </TT> <TT>WrongTransactionHolder 383 </TT> <TT>WStringSeqHolder</TT> 384 385 </PRE> 386 387 <h2>Helper Classes </h2> 388 <P>Helper files supply several static methods needed to manipulate the type. 389 These include: 390 <UL> 391 <LI><tt>Any</tt> insert and extract operations for the type 392 <LI>getting the repository id 393 <LI>getting the typecode 394 <LI>reading and writing the type from and to a stream 395 <LI>implement the <code>ValueHelper</code> interface (if it is a user-defined 396 value type) 397 </UL> 398 399 <P>The helper class for a mapped IDL interface or abstract interface 400 also include narrow operation(s). The static narrow method allows 401 an <tt>org.omg.CORBA.Object</tt> to be narrowed to the object reference 402 of a more specific type. The IDL exception <tt>CORBA.BAD_PARAM</tt> 403 is thrown if the narrow fails because the object reference does not 404 support the requested type. A different system exception is raised 405 to indicate other kinds of errors. Trying to narrow a <tt>null</tt> will always 406 succeed with a return value of <tt>null</tt>. Generally, the only helper method an application programmer uses is 407 the <code>narrow</code> method. The other methods are normally used behind 408 the scenes and are transparent to the programmer. 409 410 <P>Helper classes 411 fall into two broad categories, <a href="#value">helpers for value types</a> and 412 <a href="#basic">helpers for non value types</a>. Because all of the helper 413 classes in one category 414 provide the same methods, one generic explanation of each 415 category of helper classes is presented here. 416 417 <P> 418 When OMG IDL is mapped to the Java programming language, 419 a "helper" class is generated for each user-defined type. 420 This generated class will have the name of the user-defined type with 421 the suffix <code>Helper</code> appended. For example, if the 422 interface <code>Account</code> is defined in OMG IDL, the 423 <code>idlj</code> compiler will automatically generate a class named 424 <code>AccountHelper</code>. The <code>AccountHelper</code> class 425 will contain the static methods needed for manipulating instances of the type, 426 in this case, <code>Account</code> objects. 427 428 429 <a name="narrow"></a> 430 <h3>The <code>narrow</code> Method</h3> 431 When an object is the return value for a method, it is returned in the 432 form of a generic object, either an <code>org.omg.CORBA.Object</code> object 433 or a <code>java.lang.Object</code> object. This object must be cast to its 434 more specific type before it can be operated on. For example, an 435 <code>Account</code> object will be returned as a generic object and must 436 be narrowed to an <code>Account</code> object so that <code>Account</code> 437 methods may be called on it. 438 <P> 439 The <code>narrow</code> method has two forms, one that takes an 440 <code>org.omg.CORBA.Object</code> object and one that takes a 441 <code>java.lang.Object</code> object. Whether the interface is abstract or 442 not determines which <code>narrow</code> method its helper class will provide. 443 The helper class for an interface 444 that is not abstract will have a <code>narrow</code> method that takes a CORBA 445 object, whereas the <code>narrow</code> method for an interface that is abstract 446 will 447 take an object in the Java programming language. The helper class for a 448 non-abstract interface that has at least one abstract base interface will provide 449 both versions of the <code>narrow</code> method. 450 <P>The <A HREF="{@docRoot}/../technotes/guides/idl/jidlExample.html"><em>Hello World</em></A> 451 tutorial uses a <tt>narrow</tt> method that looks 452 like this: 453 <PRE> 454 // create and initialize the ORB 455 ORB orb = ORB.init(args, null); 456 457 // get the root naming context 458 org.omg.CORBA.Object objRef = 459 orb.resolve_initial_references("NameService"); 460 // Use NamingContextExt instead of NamingContext. This is 461 // part of latest Inter-Operable naming Service. 462 NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef); 463 464 // resolve the Object Reference in Naming 465 String name = "Hello"; 466 helloImpl = HelloHelper.narrow(ncRef.resolve_str(name)); 467 </PRE> 468 469 <a name="basic"></a> 470 <h3>Example of a Basic Helper Class</h3> 471 A basic helper class, for purposes of this explanation, is one with 472 the methods that are provided by every helper class, plus a <code>narrow</code> 473 method if the type defined in OMG IDL maps to an interface in the Java 474 programming language. Types that are not value types will have a basic 475 helper class generated for them. 476 <P> 477 For example, assuming that the interface <code>Account</code> is not a 478 value type IDL type and is also not an abstract interface and has no 479 abstract base interfaces, its <code>AccountHelper</code> class will look 480 like this: 481 <PRE> 482 abstract public class AccountHelper 483 { 484 private static String _id = "IDL:Account:1.0"; 485 486 // inserts an Account object into an Any object 487 public static void insert (org.omg.CORBA.Any a, Account that) 488 { 489 org.omg.CORBA.portable.OutputStream out = a.create_output_stream (); 490 a.type (type ()); 491 write (out, that); 492 a.read_value (out.create_input_stream (), type ()); 493 } 494 495 // extracts an Account object from an Any object 496 public static Account extract (org.omg.CORBA.Any a) 497 { 498 return read (a.create_input_stream ()); 499 } 500 501 502 private static org.omg.CORBA.TypeCode __typeCode = null; 503 // gets the typecode for this type 504 synchronized public static org.omg.CORBA.TypeCode type () 505 { 506 if (__typeCode == null) 507 { 508 __typeCode = org.omg.CORBA.ORB.init ().create_interface_tc (AccountHelper.id (), "Account"); 509 } 510 return __typeCode; 511 } 512 513 // gets the repository id for this type 514 public static String id () 515 { 516 return _id; 517 } 518 519 // reads an Account object from an input stream 520 public static Account read (org.omg.CORBA.portable.InputStream istream) 521 { 522 return narrow (istream.read_Object (_AccountStub.class)); 523 } 524 525 // writes an Account object to an outputstream 526 public static void write (org.omg.CORBA.portable.OutputStream ostream, Account value) 527 { 528 ostream.write_Object ((org.omg.CORBA.Object) value); 529 } 530 531 // converts (narrows) an Object to an Account object 532 public static Account narrow (org.omg.CORBA.Object obj) 533 { 534 if (obj == null) 535 return null; 536 else if (obj instanceof Account) 537 return (Account)obj; 538 else if (!obj._is_a (id ())) 539 throw new org.omg.CORBA.BAD_PARAM (); 540 else 541 { 542 org.omg.CORBA.portable.Delegate delegate = ((org.omg.CORBA.portable.ObjectImpl)obj)._get_delegate (); 543 _AccountStub stub = new _AccountStub (); 544 stub._set_delegate(delegate); 545 return stub; 546 } 547 } 548 549 } 550 </PRE> 551 552 <h3>Value Type Helper Classes</h3> 553 A helper class for a value type includes different renderings of 554 the same methods generated for non-value type methods. The main difference 555 is that value types are types that can be 556 passed by value as parameters or return values of a method, which means that 557 they must be serializable. 558 <P>Assuming that <code>Address</code> is a value type, the 559 <code>AddressHelper</code> class will look like this: 560 <pre> 561 abstract public class AddressHelper 562 { 563 private static String _id = "IDL:Address:1.0"; 564 565 // same as for non-value type 566 public static void insert (org.omg.CORBA.Any a, Address that) 567 { 568 org.omg.CORBA.portable.OutputStream out = a.create_output_stream (); 569 a.type (type ()); 570 write (out, that); 571 a.read_value (out.create_input_stream (), type ()); 572 } 573 574 // same as for non-value type 575 public static Address extract (org.omg.CORBA.Any a) 576 { 577 return read (a.create_input_stream ()); 578 } 579 580 private static org.omg.CORBA.TypeCode __typeCode = null; 581 private static boolean __active = false; 582 583 // getting the typecode for the type 584 synchronized public static org.omg.CORBA.TypeCode type () 585 { 586 if (__typeCode == null) 587 { 588 synchronized (org.omg.CORBA.TypeCode.class) 589 { 590 if (__typeCode == null) 591 { 592 if (__active) 593 { 594 return org.omg.CORBA.ORB.init().create_recursive_tc ( _id ); 595 } 596 __active = true; 597 org.omg.CORBA.ValueMember[] _members0 = new org.omg.CORBA.ValueMember[0]; 598 org.omg.CORBA.TypeCode _tcOf_members0 = null; 599 __typeCode = org.omg.CORBA.ORB.init ().create_value_tc (_id, "Address", org.omg.CORBA.VM_NONE.value, null, _members0); 600 __active = false; 601 } 602 } 603 } 604 return __typeCode; 605 } 606 607 // same as for non-value type 608 public static String id () 609 { 610 return _id; 611 } 612 613 // reads a serializable instance of Address from the given input stream 614 public static Address read (org.omg.CORBA.portable.InputStream istream) 615 { 616 return (Address)((org.omg.CORBA_2_3.portable.InputStream) istream).read_value (id ()); 617 } 618 619 // writes a serializable instance of Address to the given output stream 620 public static void write (org.omg.CORBA.portable.OutputStream ostream, Address value) 621 { 622 ((org.omg.CORBA_2_3.portable.OutputStream) ostream).write_value (value, id ()); 623 } 624 625 626 } 627 </pre> 628 629 <P>The Helper classes defined in the package <TT>org.omg.CORBA</TT> are: 630 <PRE><code> 631 <TT>AnySeqHelper 632 </TT> <TT>BooleanSeqHelper 633 </TT> <TT>CharSeqHelper 634 </TT> <TT>CompletionStatusHelper 635 </TT> <TT>CurrentHelper 636 </TT> <TT>DefinitionKindHelper 637 </TT> <TT>DoubleSeqHelper 638 </TT> <TT>FieldNameHelper 639 </TT> <TT>FloatSeqHelper 640 </TT> <TT>IdentifierHelper 641 </TT> <TT>IDLTypeHelper 642 </TT> <TT>LongLongSeqHelper 643 </TT> <TT>LongSeqHelper 644 </TT> <TT>NameValuePairHelper 645 </TT> <TT>ObjectHelper 646 </TT> <TT>OctetSeqHelper 647 </TT> <TT>ParameterModeHelper 648 </TT> <TT>PolicyErrorCodeHelper 649 </TT> <TT>PolicyErrorHelper 650 </TT> <TT>PolicyHelper 651 </TT> <TT>PolicyListHelper 652 </TT> <TT>PolicyTypeHelper 653 </TT> <TT>RepositoryIdHelper 654 </TT> <TT>ServiceDetailHelper 655 </TT> <TT>ServiceInformationHelper 656 </TT> <TT>SetOverrideTypeHelper 657 </TT> <TT>ShortSeqHelper 658 </TT> <TT>StringSeqHelper 659 </TT> <TT>StringValueHelper 660 </TT> <TT>StructMemberHelper 661 </TT> <TT>ULongLongSeqHelper 662 </TT> <TT>ULongSeqHelper 663 </TT> <TT>UnionMemberHelper 664 </TT> <TT>UnknownUserExceptionHelper 665 </TT> <TT>UShortSeqHelper 666 </TT> <TT>ValueBaseHelper 667 </TT> <TT>ValueMemberHelper 668 </TT> <TT>VersionSpecHelper 669 </TT> <TT>VisibilityHelper 670 </TT> <TT>WCharSeqHelper 671 </TT> <TT>WrongTransactionHelper 672 </TT> <TT>WStringSeqHelper 673 </TT> <TT>WStringValueHelper</TT> 674 675 </code></PRE> 676 <a name="adv"></a> 677 <H1> 678 Other Classes</H1> 679 The other classes and interfaces in the <TT>CORBA</TT> package, which are 680 used behind the scenes, can be put into four groups. Three of the groups 681 are used with requests in some capacity, and the fourth group, concerning 682 the Interface Repository, is a category by itself. 683 <H2> 684 Classes Created by an ORB</H2> 685 The first group contains classes that are created by an ORB and contain 686 information used in request operations. 687 <UL> 688 <LI> 689 <TT>TCKind</TT> -- indicates the kind (datatype) for a <TT>TypeCode</TT> 690 object 691 692 <LI> 693 <TT>TypeCode</TT> -- indicates a datatype and possibly other information 694 695 <LI> 696 <TT>Any</TT> -- contains a value and its typecode 697 698 <LI> 699 <TT>NamedValue</TT> -- contains a name, an <TT>Any</TT> object, and an 700 argument mode flag. <TT>NamedValue</TT> objects contain information about 701 method arguments, method return values, or a context. 702 703 <LI> 704 <TT>ContextList</TT> -- a list of strings that describe the contexts that 705 need to be resolved and sent with an invocation 706 707 <LI> 708 <TT>ExceptionList</TT> -- a list of <TT>TypeCode</TT>s for exceptions that 709 may be thrown by a method 710 711 <LI> 712 <TT>Environment</TT> -- a container for the exception thrown during a method 713 invocation 714 715 <LI> 716 <TT>Context</TT> -- a list of <TT>NamedValue</TT> objects used to pass 717 auxiliary information from client to server 718 719 <LI> 720 <TT>NVList</TT> -- a list of <TT>NamedValue</TT> objects, used to pass 721 arguments or get results 722 </UL> 723 724 <H2> 725 Classes That Deal with Requests</H2> 726 The second group of classes deals with requests: 727 <UL> 728 <LI> 729 <TT>Object</TT> -- the base class for all CORBA object references 730 731 <LI> 732 <TT>Request</TT> -- the main class in the DII, which contains methods for 733 adding arguments to the request, for accessing information about the method 734 being invoked (the method name, its arguments, exceptions it throws, and 735 so on), and for making invocations on the request 736 737 <LI> 738 <TT>DynamicImplementation</TT> -- the base class for server implementations 739 using the DSI. It has the method <TT>invoke</TT>, which is used by an 740 implementation 741 of this class to determine the state of a <TT>ServerRequest</TT> object 742 and to set its result or exception 743 744 <LI> 745 <TT>ServerRequest</TT> -- captures the explicit state of a request for 746 the Dynamic Skeleton Interface 747 </UL> 748 749 <H2> 750 Interfaces That Serve as Constants</H2> 751 The third group contains interfaces that serve as constants. The IDL-to-Java 752 mapping mandates that IDL enums are mapped to a Java class with the enumerated 753 values represented as public static final fields in that class (e.g. 754 DefinitionKind). 755 On the other hand IDL constants defined outside of an IDL interface are 756 mapped to a Java interface for each constant. 757 758 <P>This is why several interfaces in the <TT>org.omg.CORBA</TT> package 759 consist of a single field, <TT>value</TT>, which is a <TT>short</TT>. This 760 field is a constant used for such things as an error code or value modifier. 761 For example, the <TT>value</TT> field of the interface <TT>BAD_POLICY</TT> 762 is one of the possible reasons for the exception <TT>PolicyError</TT> to 763 be thrown. To specify this error code, you would use <TT>BAD_POLICY.value</TT>. 764 765 <P>The exception <TT>PolicyError</TT> uses the <TT>value</TT> field of 766 the following interfaces as its possible error codes. 767 <UL> 768 <LI> 769 <TT>BAD_POLICY</TT> 770 771 <LI> 772 <TT>BAD_POLICY_TYPE</TT> 773 774 <LI> 775 <TT>BAD_POLICY_VALUE</TT> 776 777 <LI> 778 <TT>UNSUPPORTED_POLICY</TT> 779 780 <LI> 781 <TT>UNSUPPORTED_POLICY_VALUE</TT> 782 </UL> 783 The method <TT>TypeCode.type_modifier</TT> returns the <TT>value</TT> field 784 of one of the following interfaces. The <TT>VM</TT> in the names of these 785 interfaces stands for "value modifier." 786 <UL> 787 <LI> 788 <TT>VM_NONE</TT> 789 790 <LI> 791 <TT>VM_ABSTRACT</TT> 792 793 <LI> 794 <TT>VM_CUSTOM</TT> 795 796 <LI> 797 <TT>VM_TRUNCATABLE</TT> 798 </UL> 799 The following constants are returned by a <code>ValueMember</code> object's 800 access method to denote the visibility of the <code>ValueMember</code> object. 801 <UL> 802 <LI> 803 <TT>PRIVATE_MEMBER</TT> 804 805 <LI> 806 <TT>PUBLIC_MEMBER</TT> 807 </UL> 808 These flags, used in <TT>NamedValue</TT> objects or as parameters to methods, 809 are defined in the following interfaces: 810 <UL> 811 <LI> 812 <TT>ARG_IN</TT> 813 814 <LI> 815 <TT>ARG_INOUT</TT> 816 817 <LI> 818 <TT>ARG_OUT</TT> 819 820 <LI> 821 <TT>CTX_RESTRICT_SCOPE</TT> 822 </UL> 823 824 <H2> 825 Interface Repository Interfaces and Classes</H2> 826 A fourth group contains the Interface Repository interfaces and classes, 827 which are generated by the <TT>idlj</TT> compiler from the OMG IDL 828 interface <TT>ir.idl</TT>. The purpose of the Interface Repository is to 829 identify the interfaces stored in it so that they can be accessed by an 830 ORB. Each module, type, interface, attribute, operation, parameter, exception, 831 constant, and so on is described completely by the Interface Repository 832 API. 833 834 <P>An ORB does not require that there be an interface repository, and Java 835 IDL does not include one. Even though this release does not include an 836 implementation of an interface repository, the following IR classes and 837 interfaces have been included for the purpose of creating typecodes (see 838 create_value_tc, create_struct_tc, create_union_tc and create_exception_tc 839 methods in interface org.omg.CORBA.ORB): 840 <BR> 841 <UL> 842 <LI> 843 IRObject 844 845 <LI> 846 IDLType 847 848 <LI> 849 DefinitionKind 850 851 <LI> 852 StructMember 853 854 <LI> 855 UnionMember 856 857 <LI> 858 ValueMember 859 </UL> 860 <!-- End Page Data --> 861 <HR> 862 <H1> 863 Related Documentation</H1> 864 For overviews, guides, and a tutorial, please see: 865 <UL> 866 <LI> 867 <A HREF="{@docRoot}/../technotes/guides/idl/index.html">Java IDL home page</A> 868 </UL> 869 870 871 872 873 <P><A NAME="unimpl"></A> 874 <H1> 875 CORBA Features Not Implemented in Java IDL</H1> 876 877 <P>Some of the API included in <TT>org.omg</TT> subpackages is provided for 878 conformance with the current OMG CORBA specification but is not implemented 879 in Sun's release of the JDK<SUP><FONT SIZE=-2>TM</FONT></SUP>. This enables 880 other JDK licensees to provide implementations of this API in standard 881 extensions and products. 882 883 <P><A NAME="NO_IMPLEMENT"></A> 884 <h2>Features That Throw NO_IMPLEMENT</h2> 885 886 <P>Some of the API included in <TT>org.omg</TT> subpackages throw 887 <tt>NO_IMPLEMENT</tt> exceptions for various reasons. Among these reasons 888 are: 889 <UL> 890 <LI>In some cases, for example <tt>LocalObject</tt>, the complete 891 implementation according to the specification indicates that 892 these API should throw <tt>NO_IMPLEMENT</tt>. 893 894 <LI>In most cases, for example methods in <tt>ORB.java</tt>, 895 methods that throw 896 <tt>NO_IMPLEMENT</tt> are actually implemented in subclasses 897 elsewhere in the ORB code. 898 899 <LI>In some cases, for example <tt>_get_interface_def()</tt> 900 and <tt>_get_interface</tt>, API are really not yet implemented. 901 </UL> 902 903 904 905 906 <H2> 907 General Summary of Features or API Not Implemented in This Release:</H2> 908 909 <UL> 910 <LI> 911 Interface Repository. An Interface Repository is not required for normal 912 operation of Java IDL. 913 914 <LI> 915 Java IDL does not support <TT>long double</TT>. 916 917 918 <LI> 919 Policies (<TT><a href="Policy.html">org.omg.CORBA.Policy</a></TT>) and methods for getting them are not implemented. 920 921 <LI> 922 Domain managers (<TT><a href="DomainManager.html">org.omg.CORBA.DomainManager</a></TT>) and methods for 923 getting them are not implemented. 924 925 <LI> 926 Service Information <TT><a href="ServiceInformation.html">org.omg.CORBA.ServiceInformation</a></TT> and ORB method <TT>public boolean get_service_information(short service_type, 927 ServiceInformationHolder 928 service_info)</TT> are not implemented. 929 930 <LI>ORB methods for supporting single-threading (<tt>perform_work</tt>, <tt>work_pending</tt>) are not implemented. 931 932 <LI>IDL contexts. 933 </UL> 934 935 <HR> 936 <H2> 937 Specific List of Unimplemented Features in Package <TT>org.omg.CORBA</TT></H2> 938 939 940 <H3> 941 Unimplemented Methods in package <TT>org.omg.CORBA</TT>:</H3> 942 943 <UL> 944 <LI> 945 <TT>ORB</TT> 946 947 <UL> 948 <LI> 949 <TT>public org.omg.CORBA.Policy create_policy(int type, org.omg.CORBA.Any 950 val)</TT> 951 952 953 954 <LI> 955 <TT>public void perform_work()</TT> 956 957 <LI> 958 <TT>public boolean work_pending()</TT> 959 960 <LI> 961 <TT>public org.omg.CORBA.Current get_current()</TT> 962 963 <LI> 964 <TT>create_operation_list</TT> 965 966 <LI> 967 <TT>get_default_context</TT> 968 969 <LI> 970 <TT>get_service_information</TT> 971 972 <LI> 973 obsolete <TT>DynAnys</TT> (deprecated in favor of <tt>DynamicAny</tt> package) 974 975 976 </UL> 977 978 979 980 </UL> 981 @since JDK1.2 982 @serial exclude 983 </BODY> 984 </HTML>