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