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