package.html revision 862:bd32b2b28de5
139444Smsmith<!doctype html> 239444Smsmith<HTML> 339444Smsmith<HEAD> 439444Smsmith <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> 539444Smsmith <META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en]C-gatewaynet (WinNT; U) 639444Smsmith[Netscape]"> 739444Smsmith <TITLE>package</TITLE> 839444Smsmith<!-- 939444Smsmith/* 1039444Smsmith* Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved. 1139444Smsmith* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 1239444Smsmith* 1339444Smsmith* This code is free software; you can redistribute it and/or modify it 1439444Smsmith* under the terms of the GNU General Public License version 2 only, as 1539444Smsmith* published by the Free Software Foundation. Oracle designates this 1639444Smsmith* particular file as subject to the "Classpath" exception as provided 1739444Smsmith* by Oracle in the LICENSE file that accompanied this code. 1839444Smsmith* 1939444Smsmith* This code is distributed in the hope that it will be useful, but WITHOUT 2039444Smsmith* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 2139444Smsmith* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 2239444Smsmith* version 2 for more details (a copy is included in the LICENSE file that 2339444Smsmith* accompanied this code). 2439444Smsmith* 2539444Smsmith* You should have received a copy of the GNU General Public License version 2639444Smsmith* 2 along with this work; if not, write to the Free Software Foundation, 2739444Smsmith* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2839444Smsmith* 2939444Smsmith* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 3039444Smsmith* or visit www.oracle.com if you need additional information or have any 3139444Smsmith* questions. 3239444Smsmith*/ 3339444Smsmith--> 3439444Smsmith</HEAD> 3539444Smsmith<BODY> 3639444SmsmithProvides the mapping of the OMG CORBA APIs to the Java™ 3739444Smsmithprogramming language, including the class <code>ORB</code>, which is implemented 3839444Smsmithso that a programmer can use it as a fully-functional Object Request Broker 3939444Smsmith(ORB). 4039444Smsmith 4139444Smsmith<P>For a precise list of supported sections of official CORBA specifications with which 4239444Smsmiththe Java[TM] Platform, Standard Edition 6 complies, see <A 4339444SmsmithHREF="doc-files/compliance.html"><em>Official Specifications for CORBA support in 4439444SmsmithJava[TM] SE 6</em></A>. 4539444Smsmith 4639444Smsmith 4739444Smsmith<H1>General Information</H1> 4839444SmsmithThe information in this section is information relevant to someone who 4939444Smsmithcompiles Interface Definition Language (IDL) files and uses the 5039444SmsmithORB to write clients and servers. 5139444Smsmith 5239444Smsmith<P>The classes and interfaces described in this section can be put into 5339444Smsmithfour groups: <code>ORB classes</code>, Exceptions, <code>Helper</code> classes, 5439444Smsmithand <code>Holder</code> classes. 5539444Smsmith 5639444Smsmith<H2> 5739444SmsmithThe <code>ORB</code> Class</H2> 5839444Smsmith 5939444Smsmith<P>An ORB handles (or brokers) method invocations between a client and 6039444Smsmiththe method's implementation on a server. Because the client and server 6139444Smsmithmay be anywhere on a network, and because the invocation and implementation 6239444Smsmithmay be written in different programming languages, an ORB does a great 6339444Smsmithdeal of work behind the scenes to accomplish this communication. 6439444Smsmith 6539444Smsmith<P>Most of what an ORB does is completely transparent to the user, and a major 6639444Smsmithportion of the <code>CORBA</code> package consists of classes used by the ORB 6739444Smsmithbehind the scenes. The result is that most programmers will use only a 6839444Smsmithsmall part of this package directly. In fact, most programmers will use 6939444Smsmithonly a few methods from the <code>ORB</code> class, some exceptions, and 7039444Smsmithoccasionally, 7139444Smsmitha holder class. 7239444Smsmith<H3> 7339444Smsmith<code>ORB</code> Methods</H3> 7439444Smsmith 7539444Smsmith<P>Before an application can enter the CORBA environment, it must first: 7639444Smsmith<UL> 7739444Smsmith<LI>Be initialized into the ORB and possibly the object adapter (POA) environments. 7839444Smsmith<LI>Get references to ORB object (for use in future ORB operations) 7939444Smsmithand perhaps other objects (including the root POA or some Object Adapter objects). 8039444Smsmith</UL> 8139444Smsmith<P>The following operations are provided to initialize applications and obtain 8239444Smsmith the appropriate object references: 8339444Smsmith <UL> 8439444Smsmith <LI>Operations providing access to the ORB, which are discussed in this 8539444Smsmith section. 8639444Smsmith <LI>Operations providing access to Object Adapters, Interface Repository, 8739444Smsmith Naming Service, and other Object Services. These operations are described 8839444Smsmith in <a href="#adv"><em>Other Classes</em></a>. 8939444Smsmith </UL> 9039444Smsmith <P> 9139444SmsmithWhen an application requires a CORBA environment it needs a mechanism to 9239444Smsmithget an ORB object reference and possibly an OA object reference 9339444Smsmith(such as the root POA). This serves two purposes. First, it initializes 9439444Smsmithan application into the ORB and OA environments. Second, it returns the 9539444SmsmithORB object reference and the OA object reference to the application 9639444Smsmithfor use in future ORB and OA operations. 9739444Smsmith 9839444Smsmith<P>In order to obtain an ORB object reference, applications call 9939444Smsmiththe <code>ORB.init</code> operation. The parameters to the call can comprise an 10039444Smsmithidentifier for the ORB for which the object reference is required, 10139444Smsmith and an arg_list, which is used to allow environment-specific data to be 10239444Smsmith passed into the call. 10339444Smsmith 10439444Smsmith<P>These are the <code>ORB</code> methods 10539444Smsmith that provide access to the ORB: 10639444Smsmith<UL> 10739444Smsmith<LI> 10839444Smsmith<code><b>init</b>()</code> 10939444Smsmith 11039444Smsmith<LI> 11139444Smsmith<code><b>init</b>(String [] args, Properties props)</code> 11239444Smsmith 11339444Smsmith<LI> 11439444Smsmith<code><b>init</b>(Applet app, Properties props)</code> 11539444Smsmith</UL> 11639444Smsmith 11739444Smsmith<P>Using the <code>init()</code> method without parameters initiates 11839444Smsmitha singleton ORB, which can only 11939444Smsmithgive typecode creation <code>any</code>s needed in code generated 12039444Smsmithin Helper classes by <code>idlj</code>. 12139444Smsmith 12239444Smsmith<P>Applications require a portable means by which to obtain their 12339444Smsmithinitial object references. References are required for the root 12439444SmsmithPOA, POA Current, Interface Repository, and various Object Services 12539444Smsmithinstances. The functionality required by the application is similar 12639444Smsmith to that provided by the Naming Service. However, the OMG does not 12739444Smsmith want to mandate that the Naming Service be made available to all 12839444Smsmith applications in order that they may be portably initialized. 12939444Smsmith Consequently, the operations shown in this section provide a 13039444Smsmith simplified, local version of the Naming Service that applications 13139444Smsmith can use to obtain a small, defined set of object references which 13239444Smsmith are essential to its operation. Because only a small well-defined 13339444Smsmith set of objects are expected with this mechanism, the naming context 13439444Smsmith can be flattened to be a single-level name space. This simplification 13539444Smsmith results in only two operations being defined to achieve the functionality 13639444Smsmith required. 13739444Smsmith 13839444Smsmith<P>Initial references are obtained via two operations provided in 13939444Smsmiththe ORB object interface, providing facilities to list and 14039444Smsmithresolve initial object references. These are: 14139444Smsmith<UL> 14239444Smsmith<LI> 14339444Smsmith<code><b>resolve_initial_references</b>(String name)</code> 14439444Smsmith<LI> 14539444Smsmith<code><b>list_initial_services</b>()</code> 14639444Smsmith<LI> 14739444Smsmith<code><b>register_initial_reference</b>(String id, org.omg.CORBA.Object obj)</code> 14839444Smsmith</UL> 14939444Smsmith 15039444Smsmith<P>An example that uses some of these methods is {@extLink idl_getting_started Getting Started with Java IDL}. 15139444Smsmith 15239444Smsmith<H2> 15339444SmsmithExceptions</H2> 15439444SmsmithExceptions in Java IDL are similar to those in any code written in the 15539444SmsmithJava programming language. If a method is defined to throw an exception, 15639444Smsmiththen any code using that method must have a <code>try</code>/<code>catch</code> 15739444Smsmithblock and handle that exception when it is thrown. 15839444Smsmith 15939444Smsmith<P>The documentation on {@extLink jidlexception Java IDL exceptions } 16039444Smsmithhas more information and explains the difference between 16139444Smsmithsystem exceptions and user-defined exceptions. 16239444Smsmith 16339444Smsmith<P>The following is a list of the system exceptions (which are unchecked 16439444Smsmithexceptions inheriting through <code><a href="SystemException.html"> 16539444Smsmithorg.omg.CORBA.SystemException</a></code> from 16639444Smsmith<code>java.lang.RuntimeException</code>) that are defined in the package 16739444Smsmith<code>org.omg.CORBA</code>: 16839444Smsmith<PRE><code> 16939444Smsmith BAD_CONTEXT 17039444Smsmith BAD_INV_ORDER 17139444Smsmith BAD_OPERATION 17239444Smsmith BAD_PARAM 17339444Smsmith BAD_TYPECODE 17439444Smsmith COMM_FAILURE 17539444Smsmith DATA_CONVERSION 17639444Smsmith FREE_MEM 17739444Smsmith IMP_LIMIT 17839444Smsmith INITIALIZE 17939444Smsmith INTERNAL 18039444Smsmith INTF_REPOS 18139444Smsmith INVALID_TRANSACTION 18239444Smsmith INV_FLAG 18339444Smsmith INV_IDENT 18439444Smsmith INV_OBJREF 18539444Smsmith INV_POLICY 18639444Smsmith MARSHAL 18739444Smsmith <a href="#NO_IMPLEMENT">NO_IMPLEMENT</a> 18839444Smsmith NO_MEMORY 18939444Smsmith NO_PERMISSION 19039444Smsmith NO_RESOURCES 19139444Smsmith NO_RESPONSE 19239444Smsmith OBJECT_NOT_EXIST 19339444Smsmith OBJ_ADAPTER 19439444Smsmith PERSIST_STORE 19539444Smsmith TRANSACTION_REQUIRED 19639444Smsmith TRANSACTION_ROLLEDBACK 19739444Smsmith TRANSIENT 19839444Smsmith UNKNOWN 19939444Smsmith</code></PRE> 20039444Smsmith<P> 20139444SmsmithThe following is a list of user-defined exceptions defined in the package 20239444Smsmith<code>org.omg.CORBA</code>. 20339444Smsmith<PRE><code> 20439444Smsmith Bounds 20539444Smsmith UnknownUserException 20639444Smsmith WrongTransaction 20739444Smsmith PolicyError 20839444Smsmith</code></PRE> 20939444Smsmith 21039444Smsmith <H2>Subpackages</H2> 21139444SmsmithThere are some packages inside the <code>CORBA</code> package with 21239444Smsmith"Package" as part of their names. These packages are generally quite small 21339444Smsmithbecause all they do is provide exceptions or classes for use by interfaces 21439444Smsmithand classes in the <code>CORBA</code> package. 21539444Smsmith 21639444Smsmith<P>For example, the package <code><a href="TypeCodePackage/package-summary.html"> 21739444Smsmithorg.omg.CORBA.TypeCodePackage</a></code> contains 21839444Smsmithtwo exceptions thrown by methods in the class <code>TypeCode</code>. These 21939444Smsmithexceptions are: 22039444Smsmith<UL> 22139444Smsmith<LI> 22239444Smsmith<code>BadKind</code> 22339444Smsmith 22439444Smsmith<LI> 22539444Smsmith<code>Bounds</code> 22639444Smsmith</UL> 22739444SmsmithThe package <code><a href="ORBPackage/package-summary.html"> 22839444Smsmithorg.omg.CORBA.ORBPackage</a></code> contains two exceptions: 22939444Smsmith<UL> 23039444Smsmith<LI> 23139444Smsmith<code>InvalidName</code> 23239444Smsmith 23339444Smsmith<LI> 23439444Smsmith<code>InconsistentTypeCode</code> 23539444Smsmith</UL> 23639444Smsmith 23739444Smsmith<P>Another package that is a subpackage of <code>CORBA</code> is the 23839444Smsmith<code><a href="portable/package-summary.html">portable</a></code> 23939444Smsmithpackage. It provides a set of ORB APIs that makes it 24039444Smsmithpossible for code generated by one vendor's IDL compiler to run 24139444Smsmithon another vendor's ORB. 24239444Smsmith 24339444Smsmith 24439444Smsmith 24539444Smsmith 24639444Smsmith<H2> 24739444SmsmithHolder classes</H2> 24839444Smsmith 24939444Smsmith 25039444Smsmith<P>Support for out and inout parameter passing modes requires the use of 25139444Smsmithadditional <em><a href="doc-files/generatedfiles.html#holder">holder 25239444Smsmithclasses</a></em>. Because the Java programming language does not support out or 25339444Smsmithinout parameters, holder classes are needed as a means of passing a parameter 25439444Smsmiththat can be modified. To support portable stubs and skeletons, 25539444Smsmithholder classes also implement the 25639444Smsmith<code><a href="portable/Streamable.html">org.omg.CORBA.portable.Streamable</a></code> 25739444Smsmithinterface. 25839444Smsmith 25939444Smsmith <P>Holder classes are named by appending "Holder" to the name of the type. 26039444Smsmith The name of the type refers to its name in the Java programming language. For 26139444Smsmith example, a holder class for the interface named <code>Account</code> 26239444Smsmith in the Java programming 26339444Smsmith language would be named <code>AccountHolder</code>. 26439444Smsmith 26539444Smsmith 26639444Smsmith<P>Holder classes are available for all of the basic IDL 26739444Smsmith datatypes in the <code>org.omg.CORBA</code> package. So, for example, 26839444Smsmith there are already-defined classes for <code>LongHolder</code>, <code>ShortHolder</code>, 26939444Smsmith <code>FloatHolder</code>, and so on. Classes are also generated for 27039444Smsmith all named user-defined IDL types except those defined by <code>typedefs</code>. 27139444Smsmith (Note that in this context user defined includes types that are 27239444Smsmith defined in OMG specifications such as those for the Interface 27339444Smsmith Repository, and other OMG services.) 27439444Smsmith 27539444Smsmith 27639444Smsmith<P>Each holder class has: 27739444Smsmith<UL> 27839444Smsmith<LI>a constructor from an instance 27939444Smsmith<LI>a default constructor 28039444Smsmith<LI>a public instance member, <code>value</code> which is the typed value. 28139444Smsmith<LI>a method for reading an input stream and assigning the contents to the 28239444Smsmithtype's <code>value</code> field 28339444Smsmith<LI>a method for writing the value of the <code>value</code> field to an output stream 28439444Smsmith<LI>a method for getting the typecode of the type 28539444Smsmith</UL> 28639444Smsmith 28739444Smsmith<P>The default constructor sets the value field to the default value for the 28839444Smsmithtype as defined by the Java language: 28939444Smsmith<UL> 29039444Smsmith<LI><code>false</code> for boolean 29139444Smsmith<LI><code>0</code> for numeric and char types 29239444Smsmith<LI><code>null</code> for strings and object references 29339444Smsmith</UL> 29439444Smsmith 29539444Smsmith 29639444Smsmith 29739444Smsmith<P> 29839444SmsmithAs an example, if the interface <code>Account</code>, defined in OMG IDL, 29939444Smsmithwere mapped to the Java programming language, the following holder class 30039444Smsmithwould be generated: 30139444Smsmith<PRE> 30239444Smsmithpublic final class AccountHolder implements 30339444Smsmith org.omg.CORBA.portable.Streamable 30439444Smsmith{ 30539444Smsmith // field that holds an Account object 30639444Smsmith public Account value = null; 30739444Smsmith 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