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