package.html revision 704:3ef63dbde965
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"> 35Provides the mapping of the OMG CORBA APIs to the Java<SUP><FONT 36SIZE=-2>TM</FONT></SUP> 37programming language, including the class <code>ORB</code>, which is implemented 38so 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 42the Java[TM] Platform, Standard Edition 6 complies, see <A 43HREF="doc-files/compliance.html"><em>Official Specifications for CORBA support in 44Java[TM] SE 6</em></A>. 45 46 47<H1>General Information</H1> 48The information in this section is information relevant to someone who 49compiles Interface Definition Language (IDL) files and uses the 50ORB to write clients and servers. 51 52<P>The classes and interfaces described in this section can be put into 53four groups: <code>ORB classes</code>, Exceptions, <code>Helper</code> classes, 54and <code>Holder</code> classes. 55 56<H2> 57The <code>ORB</code> Class</H2> 58 59<P>An ORB handles (or brokers) method invocations between a client and 60the method's implementation on a server. Because the client and server 61may be anywhere on a network, and because the invocation and implementation 62may be written in different programming languages, an ORB does a great 63deal 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 66portion of the <code>CORBA</code> package consists of classes used by the ORB 67behind the scenes. The result is that most programmers will use only a 68small part of this package directly. In fact, most programmers will use 69only a few methods from the <code>ORB</code> class, some exceptions, and 70occasionally, 71a 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) 79and 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> 91When an application requires a CORBA environment it needs a mechanism to 92get an ORB object reference and possibly an OA object reference 93(such as the root POA). This serves two purposes. First, it initializes 94an application into the ORB and OA environments. Second, it returns the 95ORB object reference and the OA object reference to the application 96for use in future ORB and OA operations. 97 98<P>In order to obtain an ORB object reference, applications call 99the <code>ORB.init</code> operation. The parameters to the call can comprise an 100identifier 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 118a singleton ORB, which can only 119give typecode creation <code>any</code>s needed in code generated 120in Helper classes by <code>idlj</code>. 121 122<P>Applications require a portable means by which to obtain their 123initial object references. References are required for the root 124POA, POA Current, Interface Repository, and various Object Services 125instances. 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 139the ORB object interface, providing facilities to list and 140resolve 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 151HREF="{@docRoot}/../technotes/guides/idl/GShome.html"> 152<em>Getting Started with Java IDL</em></A>. 153 154<H2> 155Exceptions</H2> 156Exceptions in Java IDL are similar to those in any code written in the 157Java programming language. If a method is defined to throw an exception, 158then any code using that method must have a <code>try</code>/<code>catch</code> 159block and handle that exception when it is thrown. 160 161<P>The documentation on <A 162HREF="{@docRoot}/../technotes/guides/idl/jidlExceptions.html"><em>Java 163IDL exceptions</em></A> has more information and explains the difference between 164system exceptions and user-defined exceptions. 165 166<P>The following is a list of the system exceptions (which are unchecked 167exceptions inheriting through <code><a href="SystemException.html"> 168org.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> 204The 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> 214There are some packages inside the <code>CORBA</code> package with 215"Package" as part of their names. These packages are generally quite small 216because all they do is provide exceptions or classes for use by interfaces 217and classes in the <code>CORBA</code> package. 218 219<P>For example, the package <code><a href="TypeCodePackage/package-summary.html"> 220org.omg.CORBA.TypeCodePackage</a></code> contains 221two exceptions thrown by methods in the class <code>TypeCode</code>. These 222exceptions are: 223<UL> 224<LI> 225<code>BadKind</code> 226 227<LI> 228<code>Bounds</code> 229</UL> 230The package <code><a href="ORBPackage/package-summary.html"> 231org.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> 242package. It provides a set of ORB APIs that makes it 243possible for code generated by one vendor's IDL compiler to run 244on another vendor's ORB. 245 246 247 248 249<H2> 250Holder classes</H2> 251 252 253<P>Support for out and inout parameter passing modes requires the use of 254additional <em><a href="doc-files/generatedfiles.html#holder">holder 255classes</a></em>. Because the Java programming language does not support out or 256inout parameters, holder classes are needed as a means of passing a parameter 257that can be modified. To support portable stubs and skeletons, 258holder classes also implement the 259<code><a href="portable/Streamable.html">org.omg.CORBA.portable.Streamable</a></code> 260interface. 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 285type'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 291type 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> 301As an example, if the interface <code>Account</code>, defined in OMG IDL, 302were mapped to the Java programming language, the following holder class 303would be generated: 304<PRE> 305public 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 344Basic 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 346in 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 400also include narrow operation(s). The static narrow method allows 401an <code>org.omg.CORBA.Object</code> to be narrowed to the object reference 402of a more specific type. The IDL exception <code>CORBA.BAD_PARAM</code> 403is thrown if the narrow fails because the object reference does not 404support the requested type. A different system exception is raised 405to indicate other kinds of errors. Trying to narrow a <code>null</code> will always 406succeed with a return value of <code>null</code>. 407Generally, the only helper method an application programmer uses is 408the <code>narrow</code> method. The other methods are normally used behind 409the scenes and are transparent to the programmer. 410 411<P>Helper classes 412fall 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 414classes in one category 415provide the same methods, one generic explanation of each 416category of helper classes is presented here. 417 418<P> 419When OMG IDL is mapped to the Java programming language, 420a "helper" class is generated for each user-defined type. 421This generated class will have the name of the user-defined type with 422the suffix <code>Helper</code> appended. For example, if the 423interface <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 426will contain the static methods needed for manipulating instances of the type, 427in this case, <code>Account</code> objects. 428 429 430<a name="narrow"></a> 431<h3>The <code>narrow</code> Method</h3> 432When an object is the return value for a method, it is returned in the 433form of a generic object, either an <code>org.omg.CORBA.Object</code> object 434or a <code>java.lang.Object</code> object. This object must be cast to its 435more 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 437be narrowed to an <code>Account</code> object so that <code>Account</code> 438methods may be called on it. 439<P> 440The <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 443not determines which <code>narrow</code> method its helper class will provide. 444The helper class for an interface 445that is not abstract will have a <code>narrow</code> method that takes a CORBA 446object, whereas the <code>narrow</code> method for an interface that is abstract 447will take an object in the Java programming language. The helper class for a 448non-abstract interface that has at least one abstract base interface will provide 449both versions of the <code>narrow</code> method. 450<P>The <A HREF="{@docRoot}/../technotes/guides/idl/jidlExample.html"><em>Hello World</em></A> 451tutorial 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> 470A basic helper class, for purposes of this explanation, is one with 471the methods that are provided by every helper class, plus a <code>narrow</code> 472method if the type defined in OMG IDL maps to an interface in the Java 473programming language. Types that are not value types will have a basic 474helper class generated for them. 475<P> 476For example, assuming that the interface <code>Account</code> is not a 477value type IDL type and is also not an abstract interface and has no 478abstract base interfaces, its <code>AccountHelper</code> class will look 479like this: 480<PRE> 481abstract 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> 552A helper class for a value type includes different renderings of 553the same methods generated for non-value type methods. The main difference 554 is that value types are types that can be 555passed by value as parameters or return values of a method, which means that 556they 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> 560abstract 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> 676Other Classes</H1> 677The other classes and interfaces in the <code>CORBA</code> package, which are 678used behind the scenes, can be put into four groups. Three of the groups 679are used with requests in some capacity, and the fourth group, concerning 680the Interface Repository, is a category by itself. 681<H2> 682Classes Created by an ORB</H2> 683The first group contains classes that are created by an ORB and contain 684information used in request operations. 685<UL> 686<LI> 687<code>TCKind</code> -- indicates the kind (datatype) for a <code>TypeCode</code> 688object 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 698argument mode flag. <code>NamedValue</code> objects contain information about 699method arguments, method return values, or a context. 700 701<LI> 702<code>ContextList</code> -- a list of strings that describe the contexts that 703need 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 707may be thrown by a method 708 709<LI> 710<code>Environment</code> -- a container for the exception thrown during a method 711invocation 712 713<LI> 714<code>Context</code> -- a list of <code>NamedValue</code> objects used to pass 715auxiliary information from client to server 716 717<LI> 718<code>NVList</code> -- a list of <code>NamedValue</code> objects, used to pass 719arguments or get results 720</UL> 721 722<H2> 723Classes That Deal with Requests</H2> 724The 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 731adding arguments to the request, for accessing information about the method 732being invoked (the method name, its arguments, exceptions it throws, and 733so on), and for making invocations on the request 734 735<LI> 736<code>DynamicImplementation</code> -- the base class for server implementations 737using the DSI. It has the method <code>invoke</code>, which is used by an 738implementation 739of this class to determine the state of a <code>ServerRequest</code> object 740and to set its result or exception 741 742<LI> 743<code>ServerRequest</code> -- captures the explicit state of a request for 744the Dynamic Skeleton Interface 745</UL> 746 747<H2> 748Interfaces That Serve as Constants</H2> 749The third group contains interfaces that serve as constants. The IDL-to-Java 750mapping mandates that IDL enums are mapped to a Java class with the enumerated 751values represented as public static final fields in that class (e.g. 752DefinitionKind). 753On the other hand IDL constants defined outside of an IDL interface are 754mapped to a Java interface for each constant. 755 756<P>This is why several interfaces in the <code>org.omg.CORBA</code> package 757consist of a single field, <code>value</code>, which is a <code>short</code>. This 758field is a constant used for such things as an error code or value modifier. 759For example, the <code>value</code> field of the interface <code>BAD_POLICY</code> 760is one of the possible reasons for the exception <code>PolicyError</code> to 761be 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 764the 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> 781The method <code>TypeCode.type_modifier</code> returns the <code>value</code> field 782of one of the following interfaces. The <code>VM</code> in the names of these 783interfaces 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> 797The following constants are returned by a <code>ValueMember</code> object's 798access 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> 806These flags, used in <code>NamedValue</code> objects or as parameters to methods, 807are 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> 823Interface Repository Interfaces and Classes</H2> 824A fourth group contains the Interface Repository interfaces and classes, 825which are generated by the <code>idlj</code> compiler from the OMG IDL 826interface <code>ir.idl</code>. The purpose of the Interface Repository is to 827identify the interfaces stored in it so that they can be accessed by an 828ORB. Each module, type, interface, attribute, operation, parameter, exception, 829constant, and so on is described completely by the Interface Repository 830API. 831 832<P>An ORB does not require that there be an interface repository, and Java 833IDL does not include one. Even though this release does not include an 834implementation of an interface repository, the following IR classes and 835interfaces have been included for the purpose of creating typecodes (see 836create_value_tc, create_struct_tc, create_union_tc and create_exception_tc 837methods in interface org.omg.CORBA.ORB): 838<BR> 839<UL> 840<LI> 841IRObject 842 843<LI> 844IDLType 845 846<LI> 847DefinitionKind 848 849<LI> 850StructMember 851 852<LI> 853UnionMember 854 855<LI> 856ValueMember 857</UL> 858<!-- End Page Data --> 859<HR> 860<H1> 861Related Documentation</H1> 862For 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> 873CORBA Features Not Implemented in Java IDL</H1> 874 875<P>Some of the API included in <code>org.omg</code> subpackages is provided for 876conformance with the current OMG CORBA specification but is not implemented 877in Sun's release of the JDK<SUP><FONT SIZE=-2>TM</FONT></SUP>. This enables 878other JDK licensees to provide implementations of this API in standard 879extensions 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 886are: 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> 905General Summary of Features or API Not Implemented in This Release:</H2> 906 907<UL> 908<LI> 909Interface Repository. An Interface Repository is not required for normal 910operation of Java IDL. 911 912<LI> 913Java IDL does not support <code>long double</code>. 914 915 916<LI> 917Policies (<code><a href="Policy.html">org.omg.CORBA.Policy</a></code>) 918and methods for getting them are not implemented. 919 920<LI> 921Domain managers (<code><a href="DomainManager.html">org.omg.CORBA.DomainManager</a></code>) and methods for 922getting them are not implemented. 923 924<LI> 925Service Information <code><a href="ServiceInformation.html">org.omg.CORBA.ServiceInformation</a></code> 926and ORB method 927<code>public boolean get_service_information(short service_type, ServiceInformationHolder service_info)</code> 928are 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> 938Specific List of Unimplemented Features in Package <code>org.omg.CORBA</code></H2> 939 940 941<H3> 942Unimplemented 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> 973obsolete <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> 985