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