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