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 BAD_CONTEXT
176 BAD_INV_ORDER
177 BAD_OPERATION
178 BAD_PARAM
179 BAD_TYPECODE
180 COMM_FAILURE
181 DATA_CONVERSION
182 FREE_MEM
183 IMP_LIMIT
184 INITIALIZE
185 INTERNAL
186 INTF_REPOS
187 INVALID_TRANSACTION
188 INV_FLAG
189 INV_IDENT
190 INV_OBJREF
191 INV_POLICY
192 MARSHAL
193 <a href="#NO_IMPLEMENT">NO_IMPLEMENT</a>
194 NO_MEMORY
195 NO_PERMISSION
196 NO_RESOURCES
197 NO_RESPONSE
198 OBJECT_NOT_EXIST
199 OBJ_ADAPTER
200 PERSIST_STORE
201 TRANSACTION_REQUIRED
202 TRANSACTION_ROLLEDBACK
203 TRANSIENT
204 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 Bounds
211 UnknownUserException
212 WrongTransaction
213 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://www.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 <TT>AnyHolder
352 </TT> <TT>AnySeqHolder
353 </TT> <TT>BooleanHolder
354 </TT> <TT>BooleanSeqHolder
355 </TT> <TT>ByteHolder
356 </TT> <TT>CharHolder
357 </TT> <TT>CharSeqHolder
358 </TT> <TT>CurrentHolder
359 </TT> <TT>DoubleHolder
360 </TT> <TT>DoubleSeqHolder
361 </TT> <TT>FixedHolder
362 </TT> <TT>FloatHolder
363 </TT> <TT>FloatSeqHolder
364 </TT> <TT>IntHolder
365 </TT> <TT>LongHolder
366 </TT> <TT>LongLongSeqHolder
367 </TT> <TT>LongSeqHolder
368 </TT> <TT>ObjectHolder
369 </TT> <TT>OctetSeqHolder
370 </TT> <TT>ParameterModeHolder
371 </TT> <TT>PolicyErrorHolder
372 </TT> <TT>PolicyListHolder
373 </TT> <TT>PrincipalHolder
374 </TT> <TT>ServiceInformationHolder
375 </TT> <TT>ShortHolder
376 </TT> <TT>ShortSeqHolder
377 </TT> <TT>StringHolder
378 </TT> <TT>StringSeqHolder
379 </TT> <TT>TypeCodeHolder
380 </TT> <TT>ULongLongSeqHolder
381 </TT> <TT>ULongSeqHolder
382 </TT> <TT>UnknownUserExceptionHolder
383 </TT> <TT>UShortSeqHolder
384 </TT> <TT>ValueBaseHolder
385 </TT> <TT>WCharSeqHolder
386 </TT> <TT>WrongTransactionHolder
387 </TT> <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 <TT>AnySeqHelper
639 </TT> <TT>BooleanSeqHelper
640 </TT> <TT>CharSeqHelper
641 </TT> <TT>CompletionStatusHelper
642 </TT> <TT>CurrentHelper
643 </TT> <TT>DefinitionKindHelper
644 </TT> <TT>DoubleSeqHelper
645 </TT> <TT>FieldNameHelper
646 </TT> <TT>FloatSeqHelper
647 </TT> <TT>IdentifierHelper
648 </TT> <TT>IDLTypeHelper
649 </TT> <TT>LongLongSeqHelper
650 </TT> <TT>LongSeqHelper
651 </TT> <TT>NameValuePairHelper
652 </TT> <TT>ObjectHelper
653 </TT> <TT>OctetSeqHelper
654 </TT> <TT>ParameterModeHelper
655 </TT> <TT>PolicyErrorCodeHelper
656 </TT> <TT>PolicyErrorHelper
657 </TT> <TT>PolicyHelper
658 </TT> <TT>PolicyListHelper
659 </TT> <TT>PolicyTypeHelper
660 </TT> <TT>RepositoryIdHelper
661 </TT> <TT>ServiceDetailHelper
662 </TT> <TT>ServiceInformationHelper
663 </TT> <TT>SetOverrideTypeHelper
664 </TT> <TT>ShortSeqHelper
665 </TT> <TT>StringSeqHelper
666 </TT> <TT>StringValueHelper
667 </TT> <TT>StructMemberHelper
668 </TT> <TT>ULongLongSeqHelper
669 </TT> <TT>ULongSeqHelper
670 </TT> <TT>UnionMemberHelper
671 </TT> <TT>UnknownUserExceptionHelper
672 </TT> <TT>UShortSeqHelper
673 </TT> <TT>ValueBaseHelper
674 </TT> <TT>ValueMemberHelper
675 </TT> <TT>VersionSpecHelper
676 </TT> <TT>VisibilityHelper
677 </TT> <TT>WCharSeqHelper
678 </TT> <TT>WrongTransactionHelper
679 </TT> <TT>WStringSeqHelper
680 </TT> <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>