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