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