TypeCode.java revision 608:7e06bf1dcb09
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 26package org.omg.CORBA; 27 28import org.omg.CORBA.TypeCodePackage.*; 29import 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 */ 170public 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} 534