TypeCode.java revision 662:753f4114e6d6
1/* 2 * Copyright (c) 1996, 2015, 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. 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. 168 */ 169public abstract class TypeCode implements IDLEntity { 170 171 /** 172 * Compares this <code>TypeCode</code> object with the given one, 173 * testing for equality. <code>TypeCode</code> objects are equal if 174 * they are interchangeable and give identical results when 175 * <code>TypeCode</code> operations are applied to them. 176 * 177 * @param tc the <code>TypeCode</code> object to compare against 178 * @return <code>true</code> if the type codes are equal; 179 * <code>false</code> otherwise 180 */ 181 public abstract boolean equal(TypeCode tc); 182 183 /** 184 * Tests to see if the given <code>TypeCode</code> object is 185 * equivalent to this <code>TypeCode</code> object. 186 * 187 * 188 * @param tc the typecode to compare with this typecode 189 * 190 * @return <code>true</code> if the given typecode is equivalent to 191 * this typecode; <code>false</code> otherwise 192 * 193 */ 194 public abstract boolean equivalent(TypeCode tc); 195 196 /** 197 * Strips out all optional name and member name fields, 198 * but leaves all alias typecodes intact. 199 * @return a <code>TypeCode</code> object with optional name and 200 * member name fields stripped out, except for alias typecodes, 201 * which are left intact 202 * @see <a href="package-summary.html#unimpl"><code>CORBA</code> package 203 * comments for unimplemented features</a> 204 */ 205 public abstract TypeCode get_compact_typecode(); 206 207 208 /** 209 * Retrieves the kind of this <code>TypeCode</code> object. 210 * The kind of a type code determines which <code>TypeCode</code> 211 * methods may legally be invoked on it. 212 * <P> 213 * The method <code>kind</code> may be invoked on any 214 * <code>TypeCode</code> object. 215 * 216 * @return the <code>TCKind</code> instance indicating the 217 * value of the <code>kind</code> field of this 218 * <code>TypeCode</code> object 219 */ 220 public abstract TCKind kind(); 221 222 /** 223 * Retrieves the RepositoryId globally identifying the type 224 * of this <code>TypeCode</code> object. 225 * <P> 226 * The method <code>id</code> can be invoked on object reference, 227 * structure, union, enumeration, alias, exception, valuetype, 228 * boxed valuetype, native, and abstract interface type codes. 229 * Object reference, exception, valuetype, boxed valuetype, 230 * native, and abstract interface <code>TypeCode</code> objects 231 * always have a RepositoryId. 232 * Structure, union, enumeration, and alias <code>TypeCode</code> objects 233 * obtained from the Interface Repository or the method 234 * <code>ORB.create_operation_list</code> 235 * also always have a RepositoryId. If there is no RepositoryId, the 236 * method can return an empty string. 237 * 238 * @return the RepositoryId for this <code>TypeCode</code> object 239 * or an empty string if there is no RepositoryID 240 * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method 241 * is invoked on an inappropriate kind of<code>TypeCode</code> 242 * object 243 */ 244 public abstract String id() throws BadKind; 245 246 /** 247 * Retrieves the simple name identifying this <code>TypeCode</code> 248 * object within its 249 * enclosing scope. Since names are local to a Repository, the 250 * name returned from a <code>TypeCode</code> object 251 * may not match the name of the 252 * type in any particular Repository, and may even be an empty 253 * string. 254 * <P> 255 * The method <code>name</code> can be invoked on object reference, 256 * structure, union, enumeration, alias, exception, valuetype, 257 * boxed valuetype, native, and abstract interface 258 * <code>TypeCode</code> objects. 259 * 260 * @return the name identifying this <code>TypeCode</code> object 261 * or an empty string 262 * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method 263 * is invoked on an inappropriate kind of<code>TypeCode</code> 264 * object 265 */ 266 public abstract String name() throws BadKind; 267 268 /** 269 * Retrieves the number of members in the type described by 270 * this <code>TypeCode</code> object. 271 * <P> 272 * The method <code>member_count</code> can be invoked on 273 * structure, union, and enumeration <code>TypeCode</code> objects. 274 * Java IDL extends the CORBA specification to allow this method to 275 * operate on exceptions as well. 276 * 277 * @return the number of members constituting the type described 278 * by this <code>TypeCode</code> object 279 * 280 * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method 281 * is invoked on an inappropriate kind of <code>TypeCode</code> 282 * object 283 */ 284 public abstract int member_count() throws BadKind; 285 286 /** 287 * Retrieves the simple name of the member identified by 288 * the given index. Since names are local to a 289 * Repository, the name returned from a <code>TypeCode</code> object 290 * may not match the name of the member in any particular 291 * Repository, and may even be an empty string. 292 * <P> 293 * The method <code>member_name</code> can be invoked on structure, union, 294 * and enumeration <code>TypeCode</code> objects. 295 * Java IDL extends the CORBA specification to allow this method to 296 * operate on exceptions as well. 297 * 298 * @param index index of the member for which a name is being reqested 299 * @return simple name of the member identified by the 300 * index or an empty string 301 * @throws org.omg.CORBA.TypeCodePackage.Bounds if the index is equal 302 * to or greater than 303 * the number of members constituting the type 304 * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method 305 * is invoked on an inappropriate kind of <code>TypeCode</code> 306 * object 307 */ 308 public abstract String member_name(int index) 309 throws BadKind, org.omg.CORBA.TypeCodePackage.Bounds; 310 311 /** 312 * Retrieves the <code>TypeCode</code> object describing the type 313 * of the member identified by the given index. 314 * <P> 315 * The method <code>member_type</code> can be invoked on structure 316 * and union <code>TypeCode</code> objects. 317 * Java IDL extends the CORBA specification to allow this method to 318 * operate on exceptions as well. 319 * 320 * @param index index of the member for which type information 321 * is begin requested 322 * @return the <code>TypeCode</code> object describing the 323 * member at the given index 324 * @throws org.omg.CORBA.TypeCodePackage.Bounds if the index is 325 * equal to or greater than 326 * the number of members constituting the type 327 * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method 328 * is invoked on an inappropriate kind of <code>TypeCode</code> 329 * object 330 */ 331 public abstract TypeCode member_type(int index) 332 throws BadKind, org.omg.CORBA.TypeCodePackage.Bounds; 333 334 /** 335 * Retrieves the label of the union member 336 * identified by the given index. For the default member, 337 * the label is the zero octet. 338 * <P> 339 * The method <code>member_label</code> can only be invoked on union 340 * <code>TypeCode</code> objects. 341 * 342 * @param index index of the union member for which the 343 * label is being requested 344 * @return an <code>Any</code> object describing the label of 345 * the requested union member or the zero octet for 346 * the default member 347 * @throws org.omg.CORBA.TypeCodePackage.Bounds if the index is 348 * equal to or greater than 349 * the number of members constituting the union 350 * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method 351 * is invoked on a non-union <code>TypeCode</code> 352 * object 353 */ 354 public abstract Any member_label(int index) 355 throws BadKind, org.omg.CORBA.TypeCodePackage.Bounds; 356 357 /** 358 * Returns a <code>TypeCode</code> object describing 359 * all non-default member labels. 360 * The method <code>discriminator_type</code> can be invoked only 361 * on union <code>TypeCode</code> objects. 362 * 363 * @return the <code>TypeCode</code> object describing 364 * the non-default member labels 365 * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method 366 * is invoked on a non-union <code>TypeCode</code> 367 * object 368 */ 369 public abstract TypeCode discriminator_type() 370 throws BadKind; 371 372 /** 373 * Returns the index of the 374 * default member, or -1 if there is no default member. 375 * <P> 376 * The method <code>default_index</code> can be invoked only on union 377 * <code>TypeCode</code> objects. 378 * 379 * @return the index of the default member, or -1 if 380 * there is no default member 381 * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method 382 * is invoked on a non-union <code>TypeCode</code> 383 * object 384 */ 385 public abstract int default_index() throws BadKind; 386 387 /** 388 * Returns the number of elements in the type described by 389 * this <code>TypeCode</code> object. 390 * For strings and sequences, it returns the 391 * bound, with zero indicating an unbounded string or sequence. 392 * For arrays, it returns the number of elements in the array. 393 * <P> 394 * The method <code>length</code> can be invoked on string, sequence, and 395 * array <code>TypeCode</code> objects. 396 * 397 * @return the bound for strings and sequences, or the 398 * number of elements for arrays 399 * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method 400 * is invoked on an inappropriate kind of <code>TypeCode</code> 401 * object 402 */ 403 public abstract int length() throws BadKind; 404 405 /** 406 * Returns the <code>TypeCode</code> object representing the 407 * IDL type for the members of the object described by this 408 * <code>TypeCode</code> object. 409 * For sequences and arrays, it returns the 410 * element type. For aliases, it returns the original type. Note 411 * that multidimensional arrays are represented by nesting 412 * <code>TypeCode</code> objects, one per dimension. 413 * For boxed valuetypes, it returns the boxed type. 414 * <P> 415 * The method <code>content_type</code> can be invoked on sequence, array, 416 * alias, and boxed valuetype <code>TypeCode</code> objects. 417 * 418 * @return a <code>TypeCode</code> object representing 419 * the element type for sequences and arrays, the 420 * original type for aliases, or the 421 * boxed type for boxed valuetypes. 422 * @throws org.omg.CORBA.TypeCodePackage.BadKind if the method 423 * is invoked on an inappropriate kind of <code>TypeCode</code> 424 * object 425 */ 426 public abstract TypeCode content_type() throws BadKind; 427 428 429 /** 430 * Returns the number of digits in the fixed type described by this 431 * <code>TypeCode</code> object. For example, the typecode for 432 * the number 3000.275d could be <code>fixed<7,3></code>, where 433 * 7 is the precision and 3 is the scale. 434 * 435 * @return the total number of digits 436 * @throws org.omg.CORBA.TypeCodePackage.BadKind if this method 437 * is invoked on an inappropriate kind of <code>TypeCode</code> 438 * object 439 * 440 */ 441 public abstract short fixed_digits() throws BadKind ; 442 443 /** 444 * Returns the scale of the fixed type described by this 445 * <code>TypeCode</code> object. A positive number indicates the 446 * number of digits to the right of the decimal point. 447 * For example, the number 3000d could have the 448 * typecode <code>fixed<4,0></code>, where the first number is 449 * the precision and the second number is the scale. 450 * A negative number is also possible and adds zeroes to the 451 * left of the decimal point. In this case, <code>fixed<1,-3></code>, 452 * could be the typecode for the number 3000d. 453 * 454 * @return the scale of the fixed type that this 455 * <code>TypeCode</code> object describes 456 * @throws org.omg.CORBA.TypeCodePackage.BadKind if this method 457 * is invoked on an inappropriate kind of <code>TypeCode</code> 458 * object 459 */ 460 public abstract short fixed_scale() throws BadKind ; 461 462 /** 463 * Returns the constant that indicates the visibility of the member 464 * at the given index. 465 * 466 * This operation can only be invoked on non-boxed value 467 * <code>TypeCode</code> objects. 468 * 469 * @param index an <code>int</code> indicating the index into the 470 * value 471 * @return either <code>PRIVATE_MEMBER.value</code> or 472 * <code>PUBLIC_MEMBER.value</code> 473 * @throws org.omg.CORBA.TypeCodePackage.BadKind if this method 474 * is invoked on a non-value type <code>TypeCode</code> 475 * object 476 * @throws org.omg.CORBA.TypeCodePackage.Bounds 477 * if the given index is out of bounds 478 * @see <a href="package-summary.html#unimpl"><code>CORBA</code> package 479 * comments for unimplemented features</a> 480 */ 481 abstract public short member_visibility(int index) 482 throws BadKind, org.omg.CORBA.TypeCodePackage.Bounds ; 483 484 /** 485 * Returns a constant indicating the modifier of the value type 486 * that this <code>TypeCode</code> object describes. The constant 487 * returned must be one of the following: <code>VM_NONE.value</code>, 488 * <code>VM_ABSTRACT.value</code>, <code>VM_CUSTOM.value</code>, 489 * or <code>VM_TRUNCATABLE.value</code>, 490 * 491 * @return a constant describing the value type 492 * that this <code>TypeCode</code> object describes 493 * @throws org.omg.CORBA.TypeCodePackage.BadKind 494 * if this method 495 * is invoked on a non-value type <code>TypeCode</code> 496 * object 497 * @see <a href="package-summary.html#unimpl"><code>CORBA</code> package 498 * comments for unimplemented features</a> 499 */ 500 abstract public short type_modifier() throws BadKind ; 501 502 /** 503 * Returns the <code>TypeCode</code> object that describes the concrete base type 504 * of the value type that this <code>TypeCode</code> object describes. 505 * Returns null if it doesn't have a concrete base type. 506 * 507 * @return the <code>TypeCode</code> object that describes the 508 * concrete base type of the value type 509 * that this <code>TypeCode</code> object describes 510 * @throws org.omg.CORBA.TypeCodePackage.BadKind if this method 511 * is invoked on a non-boxed value type <code>TypeCode</code> object 512 * @see <a href="package-summary.html#unimpl"><code>CORBA</code> package 513 * comments for unimplemented features</a> 514 */ 515 abstract public TypeCode concrete_base_type() throws BadKind ; 516} 517