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