1 /*
2 * Copyright 1996-2003 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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<boolean, 10></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 }
Save This Page