View Javadoc
1   /*
2    * Copyright (c) 1996, 2003, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package org.omg.CORBA;
27  
28  import org.omg.CORBA.TypeCodePackage.*;
29  import org.omg.CORBA.portable.IDLEntity;
30  
31  /**
32   * A container for information about a specific CORBA data
33   * type.
34   *<P>
35   * <code>TypeCode</code> objects are used:
36   * <UL>
37   * <LI>in the Dynamic Invocation Interface -- to indicate the types
38   * of the actual arguments or the type of the return value.  <BR>
39   * <code>NamedValue</code> objects are used to represent arguments and
40   * return values.  One of their components is an <code>Any</code>
41   * object, which in turn has as one of its components a
42   * <code>TypeCode</code> object.
43   * <LI>by an Interface Repository to represent the type specifications
44   * that are part of many OMG IDL declarations
45   * </UL>
46   * <P>
47   * The representation of a <code>TypeCode</code> object is opaque,
48   * but abstractly, a <code>TypeCode</code> object consists of:
49   * <UL>
50   * <LI>a <code>kind</code> field, which is set to an instance
51   * of the class <code>TCKind</code>
52   * <LI>zero or more additional fields appropriate
53   * for the particular kind. For example, the
54   * <code>TypeCode</code> object
55   * describing the OMG IDL type <code>1ong</code> has kind
56   * <code>TCKind.tk_long</code> and no additional fields.
57   * The <code>TypeCode</code> describing OMG IDL type
58   * <code>sequence&lt;boolean, 10&gt;</code> has a <code>kind</code> field
59   * with the value
60   * <code>TCKind.tk_sequence</code> and also fields with the values
61   * <code>boolean</code> and <code>10</code> for the
62   * type of sequence elements and the length of the sequence. <p>
63   * </UL>
64   *
65   * <code>TypeCode</code> objects can be obtained in various ways:
66   * <OL>
67   * <LI>from a call to the method <code>Any.insert_X</code>, where X is
68   * a basic IDL type.  This method creates a <code>TypeCode</code> object
69   * for type X and assigns it to the <code>Any</code> object's
70   * <code>type</code> field.
71   * <LI>from invocations of methods in the ORB class
72   * <P>For example, the following creates a <code>TypeCode</code>
73   * object for a <code>string</code> with a maximum of 30 characters:
74   * <PRE>
75   *   org.omg.CORBA.TypeCode tcString = orb.create_string_tc(30);
76   * </PRE>
77   * <P> The following creates a <code>TypeCode</code>
78   * object for an <code>array</code> of five <code>string</code>s:
79   * <PRE>
80   *   org.omg.CORBA.TypeCode tcArray = orb.create_array_tc(
81   *                                       5, TCKind.tk_string);
82   * </PRE>
83   * <P> The following creates a <code>TypeCode</code>
84   * object for an interface named "Account":
85   * <PRE>
86   *   org.omg.CORBA.TypeCode tcInterface = orb.create_interface_tc(
87   *                                                 "thisId", "Account");
88   * </PRE>
89   * <LI>as the return value from the <code>_type</code> method
90   * in <code>Holder</code> classes for user-defined
91   * IDL types.  These <code>Holder</code> classes are generated
92   * by the <code>idltojava</code> compiler.
93   * <LI>from a CORBA Interface Repository
94   * </OL>
95   * <P>
96   * Most of the methods in the class <code>TypeCode</code>
97   * are accessors, and the information contained in a <code>TypeCode</code>
98   * object is specific to a particular type.  Therefore, methods
99   * must be invoked
100  * only on the kind of type codes to which they apply.  If an
101  * accessor method
102  * tries to access information from an inappropriate kind of
103  * type code, it will throw
104  * the exception <code>TypeCodePackage.BadKind</code>.  For example,
105  * if the method <code>discriminator_type</code> is called on anything
106  * other than a <code>union</code>, it will throw <code>BadKind</code>
107  * because only <code>union</code>s have a discriminator.
108  * The following list shows which methods apply to which kinds of
109  * type codes:
110  * <P>
111  * These methods may be invoked on all <code>TypeCode</code> kinds:
112  * <UL>
113  * <LI><code>equal</code>
114  * <LI><code>kind</code>
115  * </UL>
116  * <P>
117  * These methods may be invoked on <code>objref</code>, <code>struct</code>,
118  * <code>union</code>, <code>enum</code>,
119  * <code>alias</code>, <code>exception</code>, <code>value</code>,
120  * <code>value_box</code>, <code>native</code>,
121  * and <code>abstract_interface</code>:
122  * <UL>
123  * <LI><code>id</code>
124  * <LI><code>name</code>
125  * </UL>
126  * <P>
127  * These methods may be invoked on <code>struct</code>,
128  * <code>union</code>, <code>enum</code>,
129  * and <code>exception</code>:
130  * <UL>
131  * <LI><code>member_count</code>
132  * <LI><code>member_name</code>
133  * </UL>
134  * <P>
135  * These methods may be invoked on <code>struct</code>,
136  * <code>union</code>, and <code>exception</code>:
137  * <UL>
138  * <LI><code>member_type(int index)</code>
139  * </UL>
140  * <P>
141  * These methods may be invoked on <code>union</code>:
142  * <UL>
143  * <LI><code>member_label</code>
144  * <LI><code>discriminator_type</code>
145  * <LI><code>default_index</code>
146  * </UL>
147  * <P>
148  * These methods may be invoked on <code>string</code>,
149  * <code>sequence</code>, and <code>array</code>:
150  * <UL>
151  * <LI><code>length</code>
152  * </UL>
153  * <P>
154  * These methods may be invoked on <code>alias</code>,
155  * <code>sequence</code>, <code>array</code>, and <code>value_box</code>:
156  * <UL>
157  * <LI><code>content_type</code>
158  * </UL>
159  * <P>
160  * Unlike other CORBA pseudo-objects, <code>TypeCode</code>
161  * objects can be passed as general IDL parameters. <p>
162  * The methods <code>parameter</code> and <code>param_count</code>,
163  * which are deprecated, are not mapped.  <p>
164  *
165  * Java IDL extends the CORBA specification to allow all operations permitted
166  * on a <code>struct</code> <code>TypeCode</code> to be permitted
167  * on an <code>exception</code> <code>TypeCode</code> as well. <p>
168  *
169  */
170 public abstract class TypeCode implements IDLEntity {
171 
172     /**
173      * Compares this <code>TypeCode</code> object with the given one,
174      * testing for equality. <code>TypeCode</code> objects are equal if
175      * they are interchangeable and give identical results when
176      * <code>TypeCode</code> operations are applied to them.
177      *
178      * @param tc                the <code>TypeCode</code> object to compare against
179      * @return          <code>true</code> if the type codes are equal;
180      *                <code>false</code> otherwise
181      */
182 
183     public abstract boolean equal(TypeCode tc);
184 
185     /**
186          * Tests to see if the given <code>TypeCode</code> object is
187          * equivalent to this <code>TypeCode</code> object.
188          * <P>
189          *
190          *
191          * @param tc the typecode to compare with this typecode
192          *
193          * @return <code>true</code> if the given typecode is equivalent to
194          *         this typecode; <code>false</code> otherwise
195      *
196      */
197     public abstract boolean equivalent(TypeCode tc);
198 
199     /**
200      * Strips out all optional name and member name fields,
201      * but leaves all alias typecodes intact.
202          * @return a <code>TypeCode</code> object with optional name and
203          *         member name fields stripped out, except for alias typecodes,
204          *         which are left intact
205      * @see <a href="package-summary.html#unimpl"><code>CORBA</code> package
206      *      comments for unimplemented features</a>
207      */
208     public abstract TypeCode get_compact_typecode();
209 
210 
211     /**
212      * Retrieves the kind of this <code>TypeCode</code> object.
213      * The kind of a type code determines which <code>TypeCode</code>
214      * methods may legally be invoked on it.
215      * <P>
216      * The method <code>kind</code> may be invoked on any
217      * <code>TypeCode</code> object.
218      *
219      * @return  the <code>TCKind</code> instance indicating the
220      *            value of the <code>kind</code> field of this
221      *                  <code>TypeCode</code> object
222      */
223 
224     public abstract TCKind kind();
225 
226     /**
227      * Retrieves the RepositoryId globally identifying the type
228      * of this <code>TypeCode</code> object.
229      * <P>
230      * The method <code>id</code> can be invoked on object reference,
231      * structure, union, enumeration, alias, exception, valuetype,
232      * boxed valuetype, native, and abstract interface type codes.
233      * Object reference, exception, valuetype, boxed valuetype,
234      * native, and abstract interface <code>TypeCode</code> objects
235      * always have a RepositoryId.
236      * Structure, union, enumeration, and alias <code>TypeCode</code> objects
237      * obtained from the Interface Repository or the method
238      * <code>ORB.create_operation_list</code>
239      * also always have a RepositoryId. If there is no RepositoryId, the
240      * method can return an empty string.
241      *
242      * @return          the RepositoryId for this <code>TypeCode</code> object
243      *                or an empty string if there is no RepositoryID
244      * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method
245      *           is invoked on an inappropriate kind of<code>TypeCode</code>
246      *           object
247      */
248 
249     public abstract String id() throws BadKind;
250 
251     /**
252      * Retrieves the simple name identifying this <code>TypeCode</code>
253      * object within its
254      * enclosing scope. Since names are local to a Repository, the
255      * name returned from a <code>TypeCode</code> object
256      * may not match the name of the
257      * type in any particular Repository, and may even be an empty
258      * string.
259      * <P>
260      * The method <code>name</code> can be invoked on object reference,
261      * structure, union, enumeration, alias, exception, valuetype,
262      * boxed valuetype, native, and abstract interface
263      * <code>TypeCode</code> objects.
264      *
265      * @return          the name identifying this <code>TypeCode</code> object
266      *                or an empty string
267      * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method
268      *           is invoked on an inappropriate kind of<code>TypeCode</code>
269      *           object
270      */
271 
272     public abstract String name() throws BadKind;
273 
274     /**
275      * Retrieves the number of members in the type described by
276      * this <code>TypeCode</code> object.
277      * <P>
278      * The method <code>member_count</code> can be invoked on
279      * structure, union, and enumeration <code>TypeCode</code> objects.
280      * Java IDL extends the CORBA specification to allow this method to
281      * operate on exceptions as well.
282      *
283      * @return          the number of members constituting the type described
284      *                by this <code>TypeCode</code> object
285      *
286      * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method
287      *           is invoked on an inappropriate kind of <code>TypeCode</code>
288      *           object
289      */
290 
291     public abstract int member_count() throws BadKind;
292 
293     /**
294      * Retrieves the simple name of the member identified by
295      * the given index. Since names are local to a
296      * Repository, the name returned from a <code>TypeCode</code> object
297      * may not match the name of the member in any particular
298      * Repository, and may even be an empty string.
299      * <P>
300      * The  method <code>member_name</code> can be invoked on structure, union,
301      * and enumeration <code>TypeCode</code> objects.
302      * Java IDL extends the CORBA specification to allow this method to
303      * operate on exceptions as well.
304      *
305      * @param index     index of the member for which a name is being reqested
306      * @return          simple name of the member identified by the
307      *                  index or an empty string
308      * @throws org.omg.CORBA.TypeCodePackage.Bounds if the index is equal
309      *            to or greater than
310      *                  the number of members constituting the type
311      * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method
312      *           is invoked on an inappropriate kind of <code>TypeCode</code>
313      *           object
314      */
315 
316     public abstract String member_name(int index)
317         throws BadKind, org.omg.CORBA.TypeCodePackage.Bounds;
318 
319     /**
320      * Retrieves the <code>TypeCode</code> object describing the type
321      * of the member identified by the given index.
322      * <P>
323      * The method <code>member_type</code> can be invoked on structure
324      * and union <code>TypeCode</code> objects.
325      * Java IDL extends the CORBA specification to allow this method to
326      * operate on exceptions as well.
327      *
328      * @param index     index of the member for which type information
329      *                is begin requested
330      * @return          the <code>TypeCode</code> object describing the
331      *                member at the given index
332      * @throws org.omg.CORBA.TypeCodePackage.Bounds if the index is
333      *                equal to or greater than
334      *                      the number of members constituting the type
335      * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method
336      *           is invoked on an inappropriate kind of <code>TypeCode</code>
337      *           object
338      */
339 
340     public abstract TypeCode member_type(int index)
341         throws BadKind, org.omg.CORBA.TypeCodePackage.Bounds;
342 
343     /**
344      * Retrieves the label of the union member
345      * identified by the given index. For the default member,
346      * the label is the zero octet.
347      *<P>
348      * The method <code>member_label</code> can only be invoked on union
349      * <code>TypeCode</code> objects.
350      *
351      * @param index     index of the union member for which the
352      *                label is being requested
353      * @return          an <code>Any</code> object describing the label of
354      *                the requested union member or the zero octet for
355      *                the default member
356      * @throws org.omg.CORBA.TypeCodePackage.Bounds if the index is
357      *                equal to or greater than
358      *                      the number of members constituting the union
359      * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method
360      *           is invoked on a non-union <code>TypeCode</code>
361      *           object
362      */
363 
364     public abstract Any member_label(int index)
365         throws BadKind, org.omg.CORBA.TypeCodePackage.Bounds;
366 
367     /**
368      * Returns a <code>TypeCode</code> object describing
369      * all non-default member labels.
370      * The method <code>discriminator_type</code> can be invoked only
371      * on union <code>TypeCode</code> objects.
372      *
373      * @return          the <code>TypeCode</code> object describing
374      *                the non-default member labels
375      * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method
376      *           is invoked on a non-union <code>TypeCode</code>
377      *           object
378      */
379 
380     public abstract TypeCode discriminator_type()
381         throws BadKind;
382 
383     /**
384      * Returns the index of the
385      * default member, or -1 if there is no default member.
386      * <P>
387      * The method <code>default_index</code> can be invoked only on union
388      * <code>TypeCode</code> objects.
389      *
390      * @return          the index of the default member, or -1 if
391      *                  there is no default member
392      * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method
393      *           is invoked on a non-union <code>TypeCode</code>
394      *           object
395      */
396 
397     public abstract int default_index() throws BadKind;
398 
399     /**
400      * Returns the number of elements in the type described by
401      * this <code>TypeCode</code> object.
402      * For strings and sequences, it returns the
403      * bound, with zero indicating an unbounded string or sequence.
404      * For arrays, it returns the number of elements in the array.
405      * <P>
406      * The method <code>length</code> can be invoked on string, sequence, and
407      * array <code>TypeCode</code> objects.
408      *
409      * @return          the bound for strings and sequences, or the
410      *                      number of elements for arrays
411      * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method
412      *           is invoked on an inappropriate kind of <code>TypeCode</code>
413      *           object
414      */
415 
416     public abstract int length() throws BadKind;
417 
418     /**
419      * Returns the <code>TypeCode</code> object representing the
420      * IDL type for the members of the object described by this
421      * <code>TypeCode</code> object.
422      * For sequences and arrays, it returns the
423      * element type. For aliases, it returns the original type. Note
424      * that multidimensional arrays are represented by nesting
425      * <code>TypeCode</code> objects, one per dimension.
426      * For boxed valuetypes, it returns the boxed type.
427      *<P>
428      * The method <code>content_type</code> can be invoked on sequence, array,
429      * alias, and boxed valuetype <code>TypeCode</code> objects.
430      *
431      * @return  a <code>TypeCode</code> object representing
432      *            the element type for sequences and arrays, the
433      *          original type for aliases, or the
434      *            boxed type for boxed valuetypes.
435      * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method
436      *           is invoked on an inappropriate kind of <code>TypeCode</code>
437      *           object
438      */
439 
440     public abstract TypeCode content_type() throws BadKind;
441 
442 
443     /**
444          * Returns the number of digits in the fixed type described by this
445          * <code>TypeCode</code> object. For example, the typecode for
446          * the number 3000.275d could be <code>fixed<7,3></code>, where
447          * 7 is the precision and 3 is the scale.
448          *
449          * @return the total number of digits
450      * @throws org.omg.CORBA.TypeCodePackage.BadKind if this method
451      *           is invoked on an inappropriate kind of <code>TypeCode</code>
452      *           object
453          *
454      */
455     public abstract short fixed_digits() throws BadKind ;
456 
457     /**
458          * Returns the scale of the fixed type described by this
459          * <code>TypeCode</code> object. A positive number indicates the
460          * number of digits to the right of the decimal point.
461          * For example, the number 3000d could have the
462          * typecode <code>fixed<4,0></code>, where the first number is
463          * the precision and the second number is the scale.
464          * A negative number is also possible and adds zeroes to the
465          * left of the decimal point.  In this case, <code>fixed<1,-3></code>,
466          * could be the typecode for the number 3000d.
467          *
468          * @return the scale of the fixed type that this
469          *         <code>TypeCode</code> object describes
470      * @throws org.omg.CORBA.TypeCodePackage.BadKind if this method
471      *           is invoked on an inappropriate kind of <code>TypeCode</code>
472      *           object
473      */
474     public abstract short fixed_scale() throws BadKind ;
475 
476     /**
477      * Returns the constant that indicates the visibility of the member
478      * at the given index.
479      *
480      * This operation can only be invoked on non-boxed value
481      * <code>TypeCode</code> objects.
482      *
483      * @param index an <code>int</code> indicating the index into the
484      *               value
485      * @return either <code>PRIVATE_MEMBER.value</code> or
486      *          <code>PUBLIC_MEMBER.value</code>
487      * @throws org.omg.CORBA.TypeCodePackage.BadKind if this method
488      *           is invoked on a non-value type <code>TypeCode</code>
489      *           object
490      * @throws org.omg.CORBA.TypeCodePackage.Bounds
491      *           if the given index is out of bounds
492      * @see <a href="package-summary.html#unimpl"><code>CORBA</code> package
493      *      comments for unimplemented features</a>
494      */
495 
496     abstract public short member_visibility(int index)
497         throws BadKind, org.omg.CORBA.TypeCodePackage.Bounds ;
498 
499     /**
500      * Returns a constant indicating the modifier of the value type
501      * that this <code>TypeCode</code> object describes.  The constant
502      * returned must be one of the following: <code>VM_NONE.value</code>,
503      * <code>VM_ABSTRACT.value</code>, <code>VM_CUSTOM.value</code>,
504      * or <code>VM_TRUNCATABLE.value</code>,
505      *
506      * @return a constant describing the value type
507      *         that this <code>TypeCode</code> object describes
508      * @throws org.omg.CORBA.TypeCodePackage.BadKind
509      *           if this method
510      *           is invoked on a non-value type <code>TypeCode</code>
511      *           object
512      * @see <a href="package-summary.html#unimpl"><code>CORBA</code> package
513      *      comments for unimplemented features</a>
514      */
515 
516     abstract public short type_modifier() throws BadKind ;
517 
518     /**
519      * Returns the <code>TypeCode</code> object that describes the concrete base type
520      * of the value type that this <code>TypeCode</code> object describes.
521      * Returns null if it doesn't have a concrete base type.
522      *
523      * @return the <code>TypeCode</code> object that describes the
524      * concrete base type of the value type
525      * that this <code>TypeCode</code> object describes
526      * @throws org.omg.CORBA.TypeCodePackage.BadKind if this method
527      *           is invoked on a non-boxed value type <code>TypeCode</code> object
528      * @see <a href="package-summary.html#unimpl"><code>CORBA</code> package
529      *      comments for unimplemented features</a>
530      */
531 
532     abstract public TypeCode concrete_base_type() throws BadKind ;
533 }