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