1. /*
  2. * @(#)TypeCode.java 1.40 01/11/29
  3. *
  4. * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package org.omg.CORBA;
  8. import org.omg.CORBA.TypeCodePackage.*;
  9. import org.omg.CORBA.portable.IDLEntity;
  10. /**
  11. * A container for information about a specific CORBA data
  12. * type.
  13. *<P>
  14. * <code>TypeCode</code> objects are used:
  15. * <UL>
  16. * <LI>in the Dynamic Invocation Interface -- to indicate the types
  17. * of the actual arguments or the type of the return value. <BR>
  18. * <code>NamedValue</code> objects are used to represent arguments and
  19. * return values. One of their components is an <code>Any</code>
  20. * object, which in turn has as one of its components a
  21. * <code>TypeCode</code> object.
  22. * <LI>by an Interface Repository to represent the type specifications
  23. * that are part of many OMG IDL declarations
  24. * </UL>
  25. * <P>
  26. * The representation of a <code>TypeCode</code> object is opaque,
  27. * but abstractly, a <code>TypeCode</code> object consists of:
  28. * <UL>
  29. * <LI>a <code>kind</code> field, which is set to an instance
  30. * of the class <code>TCKind</code>
  31. * <LI>zero or more additional fields appropriate
  32. * for the particular kind. For example, the
  33. * <code>TypeCode</code> object
  34. * describing the OMG IDL type <code>1ong</code> has kind
  35. * <code>TCKind.tk_long</code> and no additional fields.
  36. * The <code>TypeCode</code> describing OMG IDL type
  37. * <code>sequence<boolean, 10></code> has a <code>kind</code> field
  38. * with the value
  39. * <code>TCKind.tk_sequence</code> and also fields with the values
  40. * <code>boolean</code> and <code>10</code> for the
  41. * type of sequence elements and the length of the sequence. <p>
  42. *
  43. * <code>TypeCode</code> objects can be obtained in various ways:
  44. * <OL>
  45. * <LI>from a call to the method <code>Any.insert_X</code>, where X is
  46. * a basic IDL type. This method creates a <code>TypeCode</code> object
  47. * for type X and assigns it to the <code>Any</code> object's
  48. * <code>type</code> field.
  49. * <LI>from invocations of methods in the ORB class
  50. * <P>For example, the following creates a <code>TypeCode</code>
  51. * object for a <code>string</code> with a maximum of 30 characters:
  52. * <PRE>
  53. * org.omg.CORBA.TypeCode tcString = orb.create_string_tc(30);
  54. * </PRE>
  55. * <P> The following creates a <code>TypeCode</code>
  56. * object for an <code>array</code> of five <code>string</code>s:
  57. * <PRE>
  58. * org.omg.CORBA.TypeCode tcArray = orb.create_array_tc(
  59. * 5, TCKind.tk_string);
  60. * </PRE>
  61. * <P> The following creates a <code>TypeCode</code>
  62. * object for an interface named "Account":
  63. * <PRE>
  64. * org.omg.CORBA.TypeCode tcInterface = orb.create_interface_tc(
  65. * "thisId", "Account");
  66. * </PRE>
  67. * <LI>as the return value from the <code>_type</code> method
  68. * in <code>Holder</code> classes for user-defined
  69. * IDL types. These <code>Holder</code> classes are generated
  70. * by the <code>idltojava</code> compiler.
  71. * <LI>from a CORBA Interface Repository
  72. * </OL>
  73. * <P>
  74. * Most of the methods in the class <code>TypeCode</code>
  75. * are accessors, and the information contained in a <code>TypeCode</code>
  76. * object is specific to a particular type. Therefore, methods
  77. * must be invoked
  78. * only on the kind of type codes to which they apply. If an
  79. * accessor method
  80. * tries to access information from an inappropriate kind of
  81. * type code, it will throw
  82. * the exception <code>TypeCodePackage.BadKind</code>. For example,
  83. * if the method <code>discriminator_type</code> is called on anything
  84. * other than a <code>union</code>, it will throw <code>BadKind</code>
  85. * because only <code>union</code>s have a discriminator.
  86. * The following list shows which methods apply to which kinds of
  87. * type codes:
  88. * <P>
  89. * These methods may be invoked on all <code>TypeCode</code> kinds:
  90. * <UL>
  91. * <LI><code>equal</code>
  92. * <LI><code>kind</code>
  93. * </UL>
  94. * <P>
  95. * These methods may be invoked on <code>objref</code>, <code>struct</code>,
  96. * <code>union</code>, <code>enum</code>,
  97. * <code>alias</code>, <code>exception</code>, <code>value</code>,
  98. * <code>value_box</code>, <code>native</code>,
  99. * and <code>abstract_interface</code>:
  100. * <UL>
  101. * <LI><code>id</code>
  102. * <LI><code>name</code>
  103. * </UL>
  104. * <P>
  105. * These methods may be invoked on <code>struct</code>,
  106. * <code>union</code>, <code>enum</code>,
  107. * and <code>exception</code>:
  108. * <UL>
  109. * <LI><code>member_count</code>
  110. * <LI><code>member_name</code>
  111. * </UL>
  112. * <P>
  113. * These methods may be invoked on <code>struct</code>,
  114. * <code>union</code>, and <code>exception</code>:
  115. * <UL>
  116. * <LI><code>member_type(int index)</code>
  117. * </UL>
  118. * <P>
  119. * These methods may be invoked on <code>union</code>:
  120. * <UL>
  121. * <LI><code>member_label</code>
  122. * <LI><code>discriminator_type</code>
  123. * <LI><code>default_index</code>
  124. * </UL>
  125. * <P>
  126. * These methods may be invoked on <code>string</code>,
  127. * <code>sequence</code>, and <code>array</code>:
  128. * <UL>
  129. * <LI><code>length</code>
  130. * </UL>
  131. * <P>
  132. * These methods may be invoked on <code>alias</code>,
  133. * <code>sequence</code>, <code>array</code>, and <code>value_box</code>:
  134. * <UL>
  135. * <LI><code>content_type</code>
  136. * </UL>
  137. * <P>
  138. * Unlike other CORBA pseudo-objects, <code>TypeCode</code>
  139. * objects can be passed as general IDL parameters. <p>
  140. * The methods <code>parameter</code> and <code>param_count</code>,
  141. * which are deprecated, are not mapped. <p>
  142. *
  143. * Java IDL extends the CORBA specification to allow all operations permitted
  144. * on a <code>struct</code> <code>TypeCode</code> to be permitted
  145. * on an <code>exception</code> <code>TypeCode</code> as well. <p>
  146. *
  147. * @version 1.25 09/09/97
  148. */
  149. public abstract class TypeCode implements IDLEntity {
  150. /**
  151. * Compares this <code>TypeCode</code> object with the given one,
  152. * testing for equality. <code>TypeCode</code> objects are equal if
  153. * they are interchangeable and give identical results when
  154. * <code>TypeCode</code> operations are applied to them.
  155. *
  156. * @param tc the <code>TypeCode</code> object to compare against
  157. * @return <code>true</code> if the type codes are equal;
  158. * <code>false</code> otherwise
  159. */
  160. public abstract boolean equal(TypeCode tc);
  161. /**
  162. * @see <a href="package-summary.html#unimpl"><code>CORBA</code> package
  163. * comments for unimplemented features</a>
  164. */
  165. public boolean equivalent(TypeCode tc) {
  166. throw new org.omg.CORBA.NO_IMPLEMENT();
  167. }
  168. /**
  169. * Strips out all optional name & member name fields,
  170. * but it leaves all alias typecodes intact.
  171. * @see <a href="package-summary.html#unimpl"><code>CORBA</code> package
  172. * comments for unimplemented features</a>
  173. */
  174. public TypeCode get_compact_typecode() {
  175. throw new org.omg.CORBA.NO_IMPLEMENT();
  176. }
  177. /**
  178. * Retrieves the kind of this <code>TypeCode</code> object.
  179. * The kind of a type code determines which <code>TypeCode</code>
  180. * methods may legally be invoked on it.
  181. * <P>
  182. * The method <code>kind</code> may be invoked on any
  183. * <code>TypeCode</code> object.
  184. *
  185. * @return the <code>TCKind</code> instance indicating the
  186. * value of the <code>kind</code> field of this
  187. * <code>TypeCode</code> object
  188. */
  189. public abstract TCKind kind();
  190. /**
  191. * Retrieves the RepositoryId globally identifying the type
  192. * of this <code>TypeCode</code> object.
  193. * <P>
  194. * The method <code>id</code> can be invoked on object reference,
  195. * structure, union, enumeration, alias, exception, valuetype,
  196. * boxed valuetype, native, and abstract interface type codes.
  197. * Object reference, exception, valuetype, boxed valuetype,
  198. * native, and abstract interface <code>TypeCode</code> objects
  199. * always have a RepositoryId.
  200. * Structure, union, enumeration, and alias <code>TypeCode</code> objects
  201. * obtained from the Interface Repository or the method
  202. * <code>ORB.create_operation_list</code>
  203. * also always have a RepositoryId. If there is no RepositoryId, the
  204. * method can return an empty string.
  205. *
  206. * @return the RepositoryId for this <code>TypeCode</code> object
  207. * or an empty string if there is no RepositoryID
  208. * @exception org.omg.CORBA.TypeCodePackage.BadKind if the method
  209. * is invoked on an inappropriate kind of<code>TypeCode</code>
  210. * object
  211. */
  212. public abstract String id() throws BadKind;
  213. /**
  214. * Retrieves the simple name identifying this <code<TypeCode</code>
  215. * object within its
  216. * enclosing scope. Since names are local to a Repository, the
  217. * name returned from a <code>TypeCode</code> object
  218. * may not match the name of the
  219. * type in any particular Repository, and may even be an empty
  220. * string.
  221. * <P>
  222. * The method <code>name</code> can be invoked on object reference,
  223. * structure, union, enumeration, alias, exception, valuetype,
  224. * boxed valuetype, native, and abstract interface
  225. * <code>TypeCode</code> objects.
  226. *
  227. * @return the name identifying this <code>TypeCode</code> object
  228. * or an empty string
  229. * @exception org.omg.CORBA.TypeCodePackage.BadKind if the method
  230. * is invoked on an inappropriate kind of<code>TypeCode</code>
  231. * object
  232. */
  233. public abstract String name() throws BadKind;
  234. /**
  235. * Retrieves the number of members in the type described by
  236. * this <code>TypeCode</code> object.
  237. * <P>
  238. * The method <code>member_count</code> can be invoked on
  239. * structure, union, and enumeration <code>TypeCode</code> objects.
  240. * Java IDL extends the CORBA specification to allow this method to
  241. * operate on exceptions as well.
  242. *
  243. * @return the number of members constituting the type described
  244. * by this <code>TypeCode</code> object
  245. *
  246. * @exception org.omg.CORBA.TypeCodePackage.BadKind if the method
  247. * is invoked on an inappropriate kind of <code>TypeCode</code>
  248. * object
  249. */
  250. public abstract int member_count() throws BadKind;
  251. /**
  252. * Retrieves the simple name of the member identified by
  253. * the given index. Since names are local to a
  254. * Repository, the name returned from a <code>TypeCode</code> object
  255. * may not match the name of the member in any particular
  256. * Repository, and may even be an empty string.
  257. * <P>
  258. * The method <code>member_name</code> can be invoked on structure, union,
  259. * and enumeration <code>TypeCode</code> objects.
  260. * Java IDL extends the CORBA specification to allow this method to
  261. * operate on exceptions as well.
  262. *
  263. * @param index index of the member for which a name is being reqested
  264. * @return simple name of the member identified by the
  265. * index or an empty string
  266. * @exception org.omg.CORBA.TypeCodePackage.Bounds if the index is equal
  267. * to or greater than
  268. * the number of members constituting the type
  269. * @exception org.omg.CORBA.TypeCodePackage.BadKind if the method
  270. * is invoked on an inappropriate kind of <code>TypeCode</code>
  271. * object
  272. */
  273. public abstract String member_name(int index)
  274. throws BadKind, org.omg.CORBA.TypeCodePackage.Bounds;
  275. /**
  276. * Retrieves the <code<TypeCode</code> object describing the type
  277. * of the member identified by the given index.
  278. * <P>
  279. * The method <code>member_type</code> can be invoked on structure
  280. * and union <code>TypeCode</code> objects.
  281. * Java IDL extends the CORBA specification to allow this method to
  282. * operate on exceptions as well.
  283. *
  284. * @param index index of the member for which type information
  285. * is begin requested
  286. * @return the <code>TypeCode</code> object describing the
  287. * member at the given index
  288. * @exception org.omg.CORBA.TypeCodePackage.Bounds if the index is
  289. * equal to or greater than
  290. * the number of members constituting the type
  291. * @exception org.omg.CORBA.TypeCodePackage.BadKind if the method
  292. * is invoked on an inappropriate kind of <code>TypeCode</code>
  293. * object
  294. */
  295. public abstract TypeCode member_type(int index)
  296. throws BadKind, org.omg.CORBA.TypeCodePackage.Bounds;
  297. /**
  298. * Retrieves the label of the union member
  299. * identified by the given index. For the default member,
  300. * the label is the zero octet.
  301. *<P>
  302. * The method <code>member_label</code> can only be invoked on union
  303. * <code>TypeCode</code> objects.
  304. *
  305. * @param index index of the union member for which the
  306. * label is being requested
  307. * @return an <code>Any</code> object describing the label of
  308. * the requested union member or the zero octet for
  309. * the default member
  310. * @exception org.omg.CORBA.TypeCodePackage.Bounds if the index is
  311. * equal to or greater than
  312. * the number of members constituting the union
  313. * @exception org.omg.CORBA.TypeCodePackage.BadKind if the method
  314. * is invoked on a non-union <code>TypeCode</code>
  315. * object
  316. */
  317. public abstract Any member_label(int index)
  318. throws BadKind, org.omg.CORBA.TypeCodePackage.Bounds;
  319. /**
  320. * Returns a <code>TypeCode</code> object describing
  321. * all non-default member labels.
  322. * The method <code>discriminator_type</code> can be invoked only
  323. * on union <code>TypeCode</code> objects.
  324. *
  325. * @return the <code>TypeCode</code> object describing
  326. * the non-default member labels
  327. * @exception org.omg.CORBA.TypeCodePackage.BadKind if the method
  328. * is invoked on a non-union <code>TypeCode</code>
  329. * object
  330. */
  331. public abstract TypeCode discriminator_type()
  332. throws BadKind;
  333. /**
  334. * Returns the index of the
  335. * default member, or -1 if there is no default member.
  336. * <P>
  337. * The method <code>default_index</code> can be invoked only on union
  338. * <code>TypeCode</code> objects.
  339. *
  340. * @return the index of the default member, or -1 if
  341. * there is no default member
  342. * @exception org.omg.CORBA.TypeCodePackage.BadKind if the method
  343. * is invoked on a non-union <code>TypeCode</code>
  344. * object
  345. */
  346. public abstract int default_index() throws BadKind;
  347. /**
  348. * Returns the number of elements in the type described by
  349. * this <code>TypeCode</code> object.
  350. * For strings and sequences, it returns the
  351. * bound, with zero indicating an unbounded string or sequence.
  352. * For arrays, it returns the number of elements in the array.
  353. * <P>
  354. * The method <code>length</code> can be invoked on string, sequence, and
  355. * array <code>TypeCode</code> objects.
  356. *
  357. * @return the bound for strings and sequences, or the
  358. * number of elements for arrays
  359. * @exception org.omg.CORBA.TypeCodePackage.BadKind if the method
  360. * is invoked on an inappropriate kind of <code>TypeCode</code>
  361. * object
  362. */
  363. public abstract int length() throws BadKind;
  364. /**
  365. * Returns the <code>TypeCode</code> object representing the
  366. * IDL type for the members of the object described by this
  367. * <code>TypeCode</code> object.
  368. * For sequences and arrays, it returns the
  369. * element type. For aliases, it returns the original type. Note
  370. * that multidimensional arrays are represented by nesting
  371. * <code>TypeCode</code> objects, one per dimension.
  372. * For boxed valuetypes, it returns the boxed type.
  373. *<P>
  374. * The method <code>content_type</code> can be invoked on sequence, array,
  375. * alias, and boxed valuetype <code>TypeCode</code> objects.
  376. *
  377. * @return a <code>TypeCode</code> object representing
  378. * the element type for sequences and arrays, the
  379. * original type for aliases, or the
  380. * boxed type for boxed valuetypes.
  381. * @exception org.omg.CORBA.TypeCodePackage.BadKind if the method
  382. * is invoked on an inappropriate kind of <code>TypeCode</code>
  383. * object
  384. */
  385. public abstract TypeCode content_type() throws BadKind;
  386. /**
  387. * @see <a href="package-summary.html#unimpl"><code>CORBA</code> package
  388. * comments for unimplemented features</a>
  389. */
  390. public short fixed_digits() throws BadKind {
  391. throw new org.omg.CORBA.NO_IMPLEMENT();
  392. }
  393. /**
  394. * @see <a href="package-summary.html#unimpl"><code>CORBA</code> package
  395. * comments for unimplemented features</a>
  396. */
  397. public short fixed_scale() throws BadKind {
  398. throw new org.omg.CORBA.NO_IMPLEMENT();
  399. }
  400. /**
  401. * Returns the constant that indicates the visibility of the member
  402. * at the given index.
  403. *
  404. * This operation can only be invoked on non-boxed value
  405. * <code>TypeCode</code> objects.
  406. *
  407. * @param index an <code>int</code> indicating the index into the
  408. * value
  409. * @return either <code>PRIVATE_MEMBER.value</code> or
  410. * <code>PUBLIC_MEMBER.value</code>
  411. * @exception org.omg.CORBA.TypeCodePackage.BadKind if this method
  412. * is invoked on a non-value type <code>TypeCode</code>
  413. * object
  414. * @exception <code>org.omg.CORBA.TypeCodePackage.Bounds</code>
  415. * if the given index is out of bounds
  416. */
  417. public short member_visibility(int index) throws BadKind, Bounds {
  418. throw new org.omg.CORBA.NO_IMPLEMENT();
  419. }
  420. /**
  421. * Returns a constant indicating the modifier of the value type
  422. * that this <code>TypeCode</code> object describes. The constant
  423. * returned must be one of the following: <code>VM_NONE.value</code>,
  424. * <code>VM_ABSTRACT.value</code>, <code>VM_CUSTOM.value</code>,
  425. * or <code>VM_TRUNCATABLE.value</code>,
  426. *
  427. * @return a constant describing the value type
  428. * that this <code>TypeCode</code> object describes
  429. * @exception <code>org.omg.CORBA.TypeCodePackage.BadKind</code>
  430. * if this method
  431. * is invoked on a non-value type <code>TypeCode</code>
  432. * object
  433. */
  434. public short type_modifier() throws BadKind {
  435. throw new org.omg.CORBA.NO_IMPLEMENT();
  436. }
  437. /**
  438. * Returns the <code>TypeCode</code> object that describes the concrete base type
  439. * of the value type that this <code>TypeCode</code> object describes.
  440. * Returns null if it doesn't have a concrete base type.
  441. *
  442. * @return the <code>TypeCode</code> object that describes the
  443. * concrete base type of the value type
  444. * that this <code>TypeCode</code> object describes
  445. * @exception <code>org.omg.CORBA.TypeCodePackage.BadKind</code> if this method
  446. * is invoked on a non-boxed value type <code>TypeCode</code> object
  447. */
  448. public TypeCode concrete_base_type() throws BadKind {
  449. throw new org.omg.CORBA.NO_IMPLEMENT();
  450. }
  451. }