1. /*
  2. * @(#)IIOMetadataFormat.java 1.24 04/05/05
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.imageio.metadata;
  8. import java.util.Locale;
  9. import javax.imageio.ImageTypeSpecifier;
  10. /**
  11. * An object describing the structure of metadata documents returned
  12. * from <code>IIOMetadata.getAsTree</code> and passed to
  13. * <code>IIOMetadata.setFromTree</code> and <code>mergeTree</code>.
  14. * Document structures are described by a set of constraints on the
  15. * type and number of child elements that may belong to a given parent
  16. * element type, the names, types, and values of attributes that may
  17. * belong to an element, and the type and values of
  18. * <code>Object</code> reference that may be stored at a node.
  19. *
  20. * <p> N.B: classes that implement this interface should contain a
  21. * method declared as <code>public static getInstance()</code> which
  22. * returns an instance of the class. Commonly, an implentation will
  23. * construct only a single instance and cache it for future
  24. * invocations of <code>getInstance</code>.
  25. *
  26. * <p> The structures that may be described by this class are a subset
  27. * of those expressible using XML document type definitions (DTDs),
  28. * with the addition of some basic information on the datatypes of
  29. * attributes and the ability to store an <code>Object</code>
  30. * reference within a node. In the future, XML Schemas could be used
  31. * to represent these structures, and many others.
  32. *
  33. * <p> The differences between
  34. * <code>IIOMetadataFormat</code>-described structures and DTDs are as
  35. * follows:
  36. *
  37. * <ul>
  38. * <li> Elements may not contain text or mix text with embedded
  39. * tags.
  40. *
  41. * <li> The children of an element must conform to one of a few simple
  42. * patterns, described in the documentation for the
  43. * <code>CHILD_*</code> constants;
  44. *
  45. * <li> The in-memory representation of an elements may contain a
  46. * reference to an <code>Object</code>. There is no provision for
  47. * representing such objects textually.
  48. * </ul>
  49. *
  50. * @version 0.5
  51. */
  52. public interface IIOMetadataFormat {
  53. // Child policies
  54. /**
  55. * A constant returned by <code>getChildPolicy</code> to indicate
  56. * that an element may not have any children. In other words, it
  57. * is required to be a leaf node.
  58. */
  59. int CHILD_POLICY_EMPTY = 0;
  60. /**
  61. * A constant returned by <code>getChildPolicy</code> to indicate
  62. * that an element must have a single instance of each of its
  63. * legal child elements, in order. In DTD terms, the contents of
  64. * the element are defined by a sequence <code>a,b,c,d,...</code>.
  65. */
  66. int CHILD_POLICY_ALL = 1;
  67. /**
  68. * A constant returned by <code>getChildPolicy</code> to indicate
  69. * that an element must have zero or one instance of each of its
  70. * legal child elements, in order. In DTD terms, the contents of
  71. * the element are defined by a sequence
  72. * <code>a?,b?,c?,d?,...</code>.
  73. */
  74. int CHILD_POLICY_SOME = 2;
  75. /**
  76. * A constant returned by <code>getChildPolicy</code> to indicate
  77. * that an element must have zero or one children, selected from
  78. * among its legal child elements. In DTD terms, the contents of
  79. * the element are defined by a selection
  80. * <code>a|b|c|d|...</code>.
  81. */
  82. int CHILD_POLICY_CHOICE = 3;
  83. /**
  84. * A constant returned by <code>getChildPolicy</code> to indicate
  85. * that an element must have a sequence of instances of any of its
  86. * legal child elements. In DTD terms, the contents of the
  87. * element are defined by a sequence <code>(a|b|c|d|...)*</code>.
  88. */
  89. int CHILD_POLICY_SEQUENCE = 4;
  90. /**
  91. * A constant returned by <code>getChildPolicy</code> to indicate
  92. * that an element must have zero or more instances of its unique
  93. * legal child element. In DTD terms, the contents of the element
  94. * are defined by a starred expression <code>a*</code>.
  95. */
  96. int CHILD_POLICY_REPEAT = 5;
  97. /**
  98. * The largest valid <code>CHILD_POLICY_*</code> constant,
  99. * to be used for range checks.
  100. */
  101. int CHILD_POLICY_MAX = CHILD_POLICY_REPEAT;
  102. /**
  103. * A constant returned by <code>getObjectValueType</code> to
  104. * indicate the absence of a user object.
  105. */
  106. int VALUE_NONE = 0;
  107. /**
  108. * A constant returned by <code>getAttributeValueType</code> and
  109. * <code>getObjectValueType</code> to indicate that the attribute
  110. * or user object may be set a single, arbitrary value.
  111. */
  112. int VALUE_ARBITRARY = 1;
  113. /**
  114. * A constant returned by <code>getAttributeValueType</code> and
  115. * <code>getObjectValueType</code> to indicate that the attribute
  116. * or user object may be set a range of values. Both the minimum
  117. * and maximum values of the range are exclusive. It is
  118. * recommended that ranges of integers be inclusive on both ends,
  119. * and that exclusive ranges be used only for floating-point data.
  120. *
  121. * @see #VALUE_RANGE_MIN_MAX_INCLUSIVE
  122. */
  123. int VALUE_RANGE = 2;
  124. /**
  125. * A value that may be or'ed with <code>VALUE_RANGE</code> to
  126. * obtain <code>VALUE_RANGE_MIN_INCLUSIVE</code>, and with
  127. * <code>VALUE_RANGE_MAX_INCLUSIVE</code> to obtain
  128. * <code>VALUE_RANGE_MIN_MAX_INCLUSIVE</code>.
  129. *
  130. * <p> Similarly, the value may be and'ed with the value of
  131. * <code>getAttributeValueType</code>or
  132. * <code>getObjectValueType</code> to determine if the minimum
  133. * value of the range is inclusive.
  134. */
  135. int VALUE_RANGE_MIN_INCLUSIVE_MASK = 4;
  136. /**
  137. * A value that may be or'ed with <code>VALUE_RANGE</code> to
  138. * obtain <code>VALUE_RANGE_MAX_INCLUSIVE</code>, and with
  139. * <code>VALUE_RANGE_MIN_INCLUSIVE</code> to obtain
  140. * <code>VALUE_RANGE_MIN_MAX_INCLUSIVE</code>.
  141. *
  142. * <p> Similarly, the value may be and'ed with the value of
  143. * <code>getAttributeValueType</code>or
  144. * <code>getObjectValueType</code> to determine if the maximum
  145. * value of the range is inclusive.
  146. */
  147. int VALUE_RANGE_MAX_INCLUSIVE_MASK = 8;
  148. /**
  149. * A constant returned by <code>getAttributeValueType</code> and
  150. * <code>getObjectValueType</code> to indicate that the attribute
  151. * or user object may be set to a range of values. The minimum
  152. * (but not the maximum) value of the range is inclusive.
  153. */
  154. int VALUE_RANGE_MIN_INCLUSIVE = VALUE_RANGE |
  155. VALUE_RANGE_MIN_INCLUSIVE_MASK;
  156. /**
  157. * A constant returned by <code>getAttributeValueType</code> and
  158. * <code>getObjectValueType</code> to indicate that the attribute
  159. * or user object may be set to a range of values. The maximum
  160. * (but not the minimum) value of the range is inclusive.
  161. */
  162. int VALUE_RANGE_MAX_INCLUSIVE = VALUE_RANGE |
  163. VALUE_RANGE_MAX_INCLUSIVE_MASK;
  164. /**
  165. * A constant returned by <code>getAttributeValueType</code> and
  166. * <code>getObjectValueType</code> to indicate that the attribute
  167. * or user object may be set a range of values. Both the minimum
  168. * and maximum values of the range are inclusive. It is
  169. * recommended that ranges of integers be inclusive on both ends,
  170. * and that exclusive ranges be used only for floating-point data.
  171. */
  172. int VALUE_RANGE_MIN_MAX_INCLUSIVE =
  173. VALUE_RANGE |
  174. VALUE_RANGE_MIN_INCLUSIVE_MASK |
  175. VALUE_RANGE_MAX_INCLUSIVE_MASK;
  176. /**
  177. * A constant returned by <code>getAttributeValueType</code> and
  178. * <code>getObjectValueType</code> to indicate that the attribute
  179. * or user object may be set one of a number of enumerated values.
  180. * In the case of attributes, these values are
  181. * <code>String</code>s; for objects, they are
  182. * <code>Object</code>s implementing a given class or interface.
  183. *
  184. * <p> Attribute values of type <code>DATATYPE_BOOLEAN</code>
  185. * should be marked as enumerations.
  186. */
  187. int VALUE_ENUMERATION = 16;
  188. /**
  189. * A constant returned by <code>getAttributeValueType</code> and
  190. * <code>getObjectValueType</code> to indicate that the attribute
  191. * or user object may be set to a list or array of values. In the
  192. * case of attributes, the list will consist of
  193. * whitespace-separated values within a <code>String</code> for
  194. * objects, an array will be used.
  195. */
  196. int VALUE_LIST = 32;
  197. /**
  198. * A constant returned by <code>getAttributeDataType</code>
  199. * indicating that the value of an attribute is a general Unicode
  200. * string.
  201. */
  202. int DATATYPE_STRING = 0;
  203. /**
  204. * A constant returned by <code>getAttributeDataType</code>
  205. * indicating that the value of an attribute is one of 'true' or
  206. * 'false'.
  207. */
  208. int DATATYPE_BOOLEAN = 1;
  209. /**
  210. * A constant returned by <code>getAttributeDataType</code>
  211. * indicating that the value of an attribute is a string
  212. * representation of an integer.
  213. */
  214. int DATATYPE_INTEGER = 2;
  215. /**
  216. * A constant returned by <code>getAttributeDataType</code>
  217. * indicating that the value of an attribute is a string
  218. * representation of a decimal floating-point number.
  219. */
  220. int DATATYPE_FLOAT = 3;
  221. /**
  222. * A constant returned by <code>getAttributeDataType</code>
  223. * indicating that the value of an attribute is a string
  224. * representation of a double-precision decimal floating-point
  225. * number.
  226. */
  227. int DATATYPE_DOUBLE = 4;
  228. // Root
  229. /**
  230. * Returns the name of the root element of the format.
  231. *
  232. * @return a <code>String</code>.
  233. */
  234. String getRootName();
  235. // Multiplicity
  236. /**
  237. * Returns <code>true</code> if the element (and the subtree below
  238. * it) is allowed to appear in a metadata document for an image of
  239. * the given type, defined by an <code>ImageTypeSpecifier</code>.
  240. * For example, a metadata document format might contain an
  241. * element that describes the primary colors of the image, which
  242. * would not be allowed when writing a grayscale image.
  243. *
  244. * @param elementName the name of the element being queried.
  245. * @param imageType an <code>ImageTypeSpecifier</code> indicating
  246. * the type of the image that will be associated with the
  247. * metadata.
  248. *
  249. * @return <code>true</code> if the node is meaningful for images
  250. * of the given type.
  251. */
  252. boolean canNodeAppear(String elementName, ImageTypeSpecifier imageType);
  253. /**
  254. * Returns the minimum number of children of the named element
  255. * with child policy <code>CHILD_POLICY_REPEAT</code>. For
  256. * example, an element representing color primary information
  257. * might be required to have at least 3 children, one for each
  258. * primay.
  259. *
  260. * @param elementName the name of the element being queried.
  261. *
  262. * @return an <code>int</code>.
  263. *
  264. * @exception IllegalArgumentException if <code>elementName</code>
  265. * is <code>null</code> or is not a legal element name for this
  266. * format.
  267. * @exception IllegalArgumentException if the named element does
  268. * not have a child policy of <code>CHILD_POLICY_REPEAT</code>.
  269. */
  270. int getElementMinChildren(String elementName);
  271. /**
  272. * Returns the maximum number of children of the named element
  273. * with child policy <code>CHILD_POLICY_REPEAT</code>. For
  274. * example, an element representing an entry in an 8-bit color
  275. * palette might be allowed to repeat up to 256 times. A value of
  276. * <code>Integer.MAX_VALUE</code> may be used to specify that
  277. * there is no upper bound.
  278. *
  279. * @param elementName the name of the element being queried.
  280. *
  281. * @return an <code>int</code>.
  282. *
  283. * @exception IllegalArgumentException if <code>elementName</code>
  284. * is <code>null</code> or is not a legal element name for this
  285. * format.
  286. * @exception IllegalArgumentException if the named element does
  287. * not have a child policy of <code>CHILD_POLICY_REPEAT</code>.
  288. */
  289. int getElementMaxChildren(String elementName);
  290. /**
  291. * Returns a <code>String</code> containing a description of the
  292. * named element, or <code>null</code>. The desciption will be
  293. * localized for the supplied <code>Locale</code> if possible.
  294. *
  295. * <p> If <code>locale</code> is <code>null</code>, the current
  296. * default <code>Locale</code> returned by <code>Locale.getLocale</code>
  297. * will be used.
  298. *
  299. * @param elementName the name of the element.
  300. * @param locale the <code>Locale</code> for which localization
  301. * will be attempted.
  302. *
  303. * @return the element description.
  304. *
  305. * @exception IllegalArgumentException if <code>elementName</code>
  306. * is <code>null</code>, or is not a legal element name for this format.
  307. */
  308. String getElementDescription(String elementName, Locale locale);
  309. // Children
  310. /**
  311. * Returns one of the constants starting with
  312. * <code>CHILD_POLICY_</code>, indicating the legal pattern of
  313. * children for the named element.
  314. *
  315. * @param elementName the name of the element being queried.
  316. *
  317. * @return one of the <code>CHILD_POLICY_*</code> constants.
  318. *
  319. * @exception IllegalArgumentException if <code>elementName</code>
  320. * is <code>null</code> or is not a legal element name for this
  321. * format.
  322. */
  323. int getChildPolicy(String elementName);
  324. /**
  325. * Returns an array of <code>String</code>s indicating the names
  326. * of the element which are allowed to be children of the named
  327. * element, in the order in which they should appear. If the
  328. * element cannot have children, <code>null</code> is returned.
  329. *
  330. * @param elementName the name of the element being queried.
  331. *
  332. * @return an array of <code>String</code>s, or null.
  333. *
  334. * @exception IllegalArgumentException if <code>elementName</code>
  335. * is <code>null</code> or is not a legal element name for this
  336. * format.
  337. */
  338. String[] getChildNames(String elementName);
  339. // Attributes
  340. /**
  341. * Returns an array of <code>String</code>s listing the names of
  342. * the attributes that may be associated with the named element.
  343. *
  344. * @param elementName the name of the element being queried.
  345. *
  346. * @return an array of <code>String</code>s.
  347. *
  348. * @exception IllegalArgumentException if <code>elementName</code>
  349. * is <code>null</code> or is not a legal element name for this
  350. * format.
  351. */
  352. String[] getAttributeNames(String elementName);
  353. /**
  354. * Returns one of the constants starting with <code>VALUE_</code>,
  355. * indicating whether the values of the given attribute within the
  356. * named element are arbitrary, constrained to lie within a
  357. * specified range, constrained to be one of a set of enumerated
  358. * values, or are a whitespace-separated list of arbitrary values.
  359. *
  360. * @param elementName the name of the element being queried.
  361. * @param attrName the name of the attribute being queried.
  362. *
  363. * @return one of the <code>VALUE_*</code> constants.
  364. *
  365. * @exception IllegalArgumentException if <code>elementName</code>
  366. * is <code>null</code> or is not a legal element name for this
  367. * format.
  368. * @exception IllegalArgumentException if <code>attrName</code> is
  369. * <code>null</code> or is not a legal attribute name for this
  370. * element.
  371. */
  372. int getAttributeValueType(String elementName, String attrName);
  373. /**
  374. * Returns one of the constants starting with
  375. * <code>DATATYPE_</code>, indicating the format and
  376. * interpretation of the value of the given attribute within th
  377. * enamed element. If <code>getAttributeValueType</code> returns
  378. * <code>VALUE_LIST</code>, then the legal value is a
  379. * whitespace-spearated list of values of the returned datatype.
  380. *
  381. * @param elementName the name of the element being queried.
  382. * @param attrName the name of the attribute being queried.
  383. *
  384. * @return one of the <code>DATATYPE_*</code> constants.
  385. *
  386. * @exception IllegalArgumentException if <code>elementName</code>
  387. * is <code>null</code> or is not a legal element name for this
  388. * format.
  389. * @exception IllegalArgumentException if <code>attrName</code> is
  390. * <code>null</code> or is not a legal attribute name for this
  391. * element.
  392. */
  393. int getAttributeDataType(String elementName, String attrName);
  394. /**
  395. * Returns <code>true</code> if the named attribute must be
  396. * present within the named element.
  397. *
  398. * @param elementName the name of the element being queried.
  399. * @param attrName the name of the attribute being queried.
  400. *
  401. * @return <code>true</code> if the attribut must be present.
  402. *
  403. * @exception IllegalArgumentException if <code>elementName</code>
  404. * is <code>null</code> or is not a legal element name for this
  405. * format.
  406. * @exception IllegalArgumentException if <code>attrName</code> is
  407. * <code>null</code> or is not a legal attribute name for this
  408. * element.
  409. */
  410. boolean isAttributeRequired(String elementName, String attrName);
  411. /**
  412. * Returns the default value of the named attribute, if it is not
  413. * explictly present within the named element, as a
  414. * <code>String</code>, or <code>null</code> if no default value
  415. * is available.
  416. *
  417. * @param elementName the name of the element being queried.
  418. * @param attrName the name of the attribute being queried.
  419. *
  420. * @return a <code>String</code> containing the default value, or
  421. * <code>null</code>.
  422. *
  423. * @exception IllegalArgumentException if <code>elementName</code>
  424. * is <code>null</code> or is not a legal element name for this
  425. * format.
  426. * @exception IllegalArgumentException if <code>attrName</code> is
  427. * <code>null</code> or is not a legal attribute name for this
  428. * element.
  429. */
  430. String getAttributeDefaultValue(String elementName, String attrName);
  431. /**
  432. * Returns an array of <code>String</code>s containing the legal
  433. * enumerated values for the given attribute within the named
  434. * element. This method should only be called if
  435. * <code>getAttributeValueType</code> returns
  436. * <code>VALUE_ENUMERATION</code>.
  437. *
  438. * @param elementName the name of the element being queried.
  439. * @param attrName the name of the attribute being queried.
  440. *
  441. * @return an array of <code>String</code>s.
  442. *
  443. * @exception IllegalArgumentException if <code>elementName</code>
  444. * is <code>null</code> or is not a legal element name for this
  445. * format.
  446. * @exception IllegalArgumentException if <code>attrName</code> is
  447. * <code>null</code> or is not a legal attribute name for this
  448. * element.
  449. * @exception IllegalArgumentException if the given attribute is
  450. * not defined as an enumeration.
  451. */
  452. String[] getAttributeEnumerations(String elementName, String attrName);
  453. /**
  454. * Returns the minimum legal value for the attribute. Whether
  455. * this value is inclusive or exclusive may be determined by the
  456. * value of <code>getAttributeValueType</code>. The value is
  457. * returned as a <code>String</code> its interpretation is
  458. * dependent on the value of <code>getAttributeDataType</code>.
  459. * This method should only be called if
  460. * <code>getAttributeValueType</code> returns
  461. * <code>VALUE_RANGE_*</code>.
  462. *
  463. * @param elementName the name of the element being queried.
  464. * @param attrName the name of the attribute being queried.
  465. *
  466. * @return a <code>String</code> containing the smallest legal
  467. * value for the attribute.
  468. *
  469. * @exception IllegalArgumentException if <code>elementName</code>
  470. * is <code>null</code> or is not a legal element name for this
  471. * format.
  472. * @exception IllegalArgumentException if <code>attrName</code> is
  473. * <code>null</code> or is not a legal attribute name for this
  474. * element.
  475. * @exception IllegalArgumentException if the given attribute is
  476. * not defined as a range.
  477. */
  478. String getAttributeMinValue(String elementName, String attrName);
  479. /**
  480. * Returns the maximum legal value for the attribute. Whether
  481. * this value is inclusive or exclusive may be determined by the
  482. * value of <code>getAttributeValueType</code>. The value is
  483. * returned as a <code>String</code> its interpretation is
  484. * dependent on the value of <code>getAttributeDataType</code>.
  485. * This method should only be called if
  486. * <code>getAttributeValueType</code> returns
  487. * <code>VALUE_RANGE_*</code>.
  488. *
  489. * @param elementName the name of the element being queried, as a
  490. * <code>String</code>.
  491. * @param attrName the name of the attribute being queried.
  492. *
  493. * @return a <code>String</code> containing the largest legal
  494. * value for the attribute.
  495. *
  496. * @exception IllegalArgumentException if <code>elementName</code>
  497. * is <code>null</code> or is not a legal element name for this
  498. * format.
  499. * @exception IllegalArgumentException if <code>attrName</code> is
  500. * <code>null</code> or is not a legal attribute name for this
  501. * element.
  502. * @exception IllegalArgumentException if the given attribute is
  503. * not defined as a range.
  504. */
  505. String getAttributeMaxValue(String elementName, String attrName);
  506. /**
  507. * Returns the minimum number of list items that may be used to
  508. * define this attribute. The attribute itself is defined as a
  509. * <code>String</code> containing multiple whitespace-separated
  510. * items. This method should only be called if
  511. * <code>getAttributeValueType</code> returns
  512. * <code>VALUE_LIST</code>.
  513. *
  514. * @param elementName the name of the element being queried.
  515. * @param attrName the name of the attribute being queried.
  516. *
  517. * @return the smallest legal number of list items for the
  518. * attribute.
  519. *
  520. * @exception IllegalArgumentException if <code>elementName</code>
  521. * is <code>null</code> or is not a legal element name for this
  522. * format.
  523. * @exception IllegalArgumentException if <code>attrName</code> is
  524. * <code>null</code> or is not a legal attribute name for this
  525. * element.
  526. * @exception IllegalArgumentException if the given attribute is
  527. * not defined as a list.
  528. */
  529. int getAttributeListMinLength(String elementName, String attrName);
  530. /**
  531. * Returns the maximum number of list items that may be used to
  532. * define this attribute. A value of
  533. * <code>Integer.MAX_VALUE</code> may be used to specify that
  534. * there is no upper bound. The attribute itself is defined as a
  535. * <code>String</code> containing multiple whitespace-separated
  536. * items. This method should only be called if
  537. * <code>getAttributeValueType</code> returns
  538. * <code>VALUE_LIST</code>.
  539. *
  540. * @param elementName the name of the element being queried.
  541. * @param attrName the name of the attribute being queried.
  542. *
  543. * @return the largest legal number of list items for the
  544. * attribute.
  545. *
  546. * @exception IllegalArgumentException if <code>elementName</code>
  547. * is <code>null</code> or is not a legal element name for this
  548. * format.
  549. * @exception IllegalArgumentException if <code>attrName</code> is
  550. * <code>null</code> or is not a legal attribute name for this
  551. * element.
  552. * @exception IllegalArgumentException if the given attribute is
  553. * not defined as a list.
  554. */
  555. int getAttributeListMaxLength(String elementName, String attrName);
  556. /**
  557. * Returns a <code>String</code> containing a description of the
  558. * named attribute, or <code>null</code>. The desciption will be
  559. * localized for the supplied <code>Locale</code> if possible.
  560. *
  561. * <p> If <code>locale</code> is <code>null</code>, the current
  562. * default <code>Locale</code> returned by <code>Locale.getLocale</code>
  563. * will be used.
  564. *
  565. * @param elementName the name of the element.
  566. * @param attrName the name of the attribute.
  567. * @param locale the <code>Locale</code> for which localization
  568. * will be attempted.
  569. *
  570. * @return the attribute description.
  571. *
  572. * @exception IllegalArgumentException if <code>elementName</code>
  573. * is <code>null</code>, or is not a legal element name for this format.
  574. * @exception IllegalArgumentException if <code>attrName</code> is
  575. * <code>null</code> or is not a legal attribute name for this
  576. * element.
  577. */
  578. String getAttributeDescription(String elementName, String attrName,
  579. Locale locale);
  580. // Object value
  581. /**
  582. * Returns one of the enumerated values starting with
  583. * <code>VALUE_</code>, indicating the type of values
  584. * (enumeration, range, or array) that are allowed for the
  585. * <code>Object</code> reference. If no object value can be
  586. * stored within the given element, the result of this method will
  587. * be <code>VALUE_NONE</code>.
  588. *
  589. * <p> <code>Object</code> references whose legal values are
  590. * defined as a range must implement the <code>Comparable</code>
  591. * interface.
  592. *
  593. * @param elementName the name of the element being queried.
  594. *
  595. * @return one of the <code>VALUE_*</code> constants.
  596. *
  597. * @exception IllegalArgumentException if <code>elementName</code>
  598. * is <code>null</code> or is not a legal element name for this
  599. * format.
  600. *
  601. * @see Comparable
  602. */
  603. int getObjectValueType(String elementName);
  604. /**
  605. * Returns the <code>Class</code> type of the <code>Object</code>
  606. * reference stored within the element. If this element may not
  607. * contain an <code>Object</code> reference, an
  608. * <code>IllegalArgumentException</code> will be thrown. If the
  609. * class type is an array, this field indicates the underlying
  610. * class type (<i>e.g</i>, for an array of <code>int</code>s, this
  611. * method would return <code>int.class</code>).
  612. *
  613. * <p> <code>Object</code> references whose legal values are
  614. * defined as a range must implement the <code>Comparable</code>
  615. * interface.
  616. *
  617. * @param elementName the name of the element being queried.
  618. *
  619. * @return a <code>Class</code> object.
  620. *
  621. * @exception IllegalArgumentException if <code>elementName</code>
  622. * is <code>null</code> or is not a legal element name for this
  623. * format.
  624. * @exception IllegalArgumentException if the named element cannot
  625. * contain an object value (<i>i.e.</i>, if
  626. * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
  627. */
  628. Class<?> getObjectClass(String elementName);
  629. /**
  630. * Returns an <code>Object</code>s containing the default
  631. * value for the <code>Object</code> reference within
  632. * the named element.
  633. *
  634. * @param elementName the name of the element being queried.
  635. *
  636. * @return an <code>Object</code>.
  637. *
  638. * @exception IllegalArgumentException if <code>elementName</code>
  639. * is <code>null</code> or is not a legal element name for this
  640. * format.
  641. * @exception IllegalArgumentException if the named element cannot
  642. * contain an object value (<i>i.e.</i>, if
  643. * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
  644. */
  645. Object getObjectDefaultValue(String elementName);
  646. /**
  647. * Returns an array of <code>Object</code>s containing the legal
  648. * enumerated values for the <code>Object</code> reference within
  649. * the named element. This method should only be called if
  650. * <code>getObjectValueType</code> returns
  651. * <code>VALUE_ENUMERATION</code>.
  652. *
  653. * <p> The <code>Object</code> associated with a node that accepts
  654. * emuerated values must be equal to one of the values returned by
  655. * this method, as defined by the <code>==</code> operator (as
  656. * opposed to the <code>Object.equals</code> method).
  657. *
  658. * @param elementName the name of the element being queried.
  659. *
  660. * @return an array of <code>Object</code>s.
  661. *
  662. * @exception IllegalArgumentException if <code>elementName</code>
  663. * is <code>null</code> or is not a legal element name for this
  664. * format.
  665. * @exception IllegalArgumentException if the named element cannot
  666. * contain an object value (<i>i.e.</i>, if
  667. * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
  668. * @exception IllegalArgumentException if the <code>Object</code>
  669. * is not defined as an enumeration.
  670. */
  671. Object[] getObjectEnumerations(String elementName);
  672. /**
  673. * Returns the minimum legal value for the <code>Object</code>
  674. * reference within the named element. Whether this value is
  675. * inclusive or exclusive may be determined by the value of
  676. * <code>getObjectValueType</code>. This method should only be
  677. * called if <code>getObjectValueType</code> returns one of the
  678. * constants starting with <code>VALUE_RANGE</code>.
  679. *
  680. * @param elementName the name of the element being queried.
  681. *
  682. * @return the smallest legal value for the attribute.
  683. *
  684. * @exception IllegalArgumentException if <code>elementName</code>
  685. * is <code>null</code> or is not a legal element name for this
  686. * format.
  687. * @exception IllegalArgumentException if the named element cannot
  688. * contain an object value (<i>i.e.</i>, if
  689. * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
  690. * @exception IllegalArgumentException if the <code>Object</code>
  691. * is not defined as a range.
  692. */
  693. Comparable<?> getObjectMinValue(String elementName);
  694. /**
  695. * Returns the maximum legal value for the <code>Object</code>
  696. * reference within the named element. Whether this value is
  697. * inclusive or exclusive may be determined by the value of
  698. * <code>getObjectValueType</code>. This method should only be
  699. * called if <code>getObjectValueType</code> returns one of the
  700. * constants starting with <code>VALUE_RANGE</code>.
  701. *
  702. * @return the smallest legal value for the attribute.
  703. *
  704. * @param elementName the name of the element being queried.
  705. *
  706. * @exception IllegalArgumentException if <code>elementName</code>
  707. * is <code>null</code> or is not a legal element name for this
  708. * format.
  709. * @exception IllegalArgumentException if the named element cannot
  710. * contain an object value (<i>i.e.</i>, if
  711. * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
  712. * @exception IllegalArgumentException if the <code>Object</code>
  713. * is not defined as a range.
  714. */
  715. Comparable<?> getObjectMaxValue(String elementName);
  716. /**
  717. * Returns the minimum number of array elements that may be used
  718. * to define the <code>Object</code> reference within the named
  719. * element. This method should only be called if
  720. * <code>getObjectValueType</code> returns
  721. * <code>VALUE_LIST</code>.
  722. *
  723. * @param elementName the name of the element being queried.
  724. *
  725. * @return the smallest valid array length for the
  726. * <code>Object</code> reference.
  727. *
  728. * @exception IllegalArgumentException if <code>elementName</code>
  729. * is <code>null</code> or is not a legal element name for this
  730. * format.
  731. * @exception IllegalArgumentException if the named element cannot
  732. * contain an object value (<i>i.e.</i>, if
  733. * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
  734. * @exception IllegalArgumentException if the <code>Object</code> is not
  735. * an array.
  736. */
  737. int getObjectArrayMinLength(String elementName);
  738. /**
  739. * Returns the maximum number of array elements that may be used
  740. * to define the <code>Object</code> reference within the named
  741. * element. A value of <code>Integer.MAX_VALUE</code> may be used
  742. * to specify that there is no upper bound. This method should
  743. * only be called if <code>getObjectValueType</code> returns
  744. * <code>VALUE_LIST</code>.
  745. *
  746. * @param elementName the name of the element being queried.
  747. *
  748. * @return the largest valid array length for the
  749. * <code>Object</code> reference.
  750. *
  751. * @exception IllegalArgumentException if <code>elementName</code>
  752. * is <code>null</code> or is not a legal element name for this
  753. * format.
  754. * @exception IllegalArgumentException if the named element cannot
  755. * contain an object value (<i>i.e.</i>, if
  756. * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
  757. * @exception IllegalArgumentException if the <code>Object</code> is not
  758. * an array.
  759. */
  760. int getObjectArrayMaxLength(String elementName);
  761. }