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  *
  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}
  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}-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_*} constants;
  65  *
  66  * <li> The in-memory representation of an elements may contain a
  67  * reference to an {@code Object}.  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} 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} 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,...}.
  88      */
  89     int CHILD_POLICY_ALL = 1;
  90 
  91     /**
  92      * A constant returned by {@code getChildPolicy} 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?,...}.
  97      */
  98     int CHILD_POLICY_SOME = 2;
  99 
 100     /**
 101      * A constant returned by {@code getChildPolicy} 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|...}.
 106      */
 107     int CHILD_POLICY_CHOICE = 3;
 108 
 109     /**
 110      * A constant returned by {@code getChildPolicy} 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|...)*}.
 114      */
 115     int CHILD_POLICY_SEQUENCE = 4;
 116 
 117     /**
 118      * A constant returned by {@code getChildPolicy} 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*}.
 122      */
 123     int CHILD_POLICY_REPEAT = 5;
 124 
 125     /**
 126      * The largest valid {@code CHILD_POLICY_*} 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} to
 133      * indicate the absence of a user object.
 134      */
 135     int VALUE_NONE = 0;
 136 
 137     /**
 138      * A constant returned by {@code getAttributeValueType} and
 139      * {@code getObjectValueType} 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} and
 146      * {@code getObjectValueType} 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} to
 158      * obtain {@code VALUE_RANGE_MIN_INCLUSIVE}, and with
 159      * {@code VALUE_RANGE_MAX_INCLUSIVE} to obtain
 160      * {@code VALUE_RANGE_MIN_MAX_INCLUSIVE}.
 161      *
 162      * <p> Similarly, the value may be and'ed with the value of
 163      * {@code getAttributeValueType} or
 164      * {@code getObjectValueType} 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} to
 171      * obtain {@code VALUE_RANGE_MAX_INCLUSIVE}, and with
 172      * {@code VALUE_RANGE_MIN_INCLUSIVE} to obtain
 173      * {@code VALUE_RANGE_MIN_MAX_INCLUSIVE}.
 174      *
 175      * <p> Similarly, the value may be and'ed with the value of
 176      * {@code getAttributeValueType} or
 177      * {@code getObjectValueType} 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} and
 184      * {@code getObjectValueType} 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} and
 193      * {@code getObjectValueType} 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} and
 202      * {@code getObjectValueType} 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} and
 215      * {@code getObjectValueType} 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}s; for objects, they are
 219      * {@code Object}s implementing a given class or interface.
 220      *
 221      * <p> Attribute values of type {@code DATATYPE_BOOLEAN}
 222      * should be marked as enumerations.
 223      */
 224     int VALUE_ENUMERATION = 16;
 225 
 226     /**
 227      * A constant returned by {@code getAttributeValueType} and
 228      * {@code getObjectValueType} 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}; for
 232      * objects, an array will be used.
 233      */
 234     int VALUE_LIST = 32;
 235 
 236     /**
 237      * A constant returned by {@code getAttributeDataType}
 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}
 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}
 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}
 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}
 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}.
 282      */
 283     String getRootName();
 284 
 285     // Multiplicity
 286 
 287     /**
 288      * Returns {@code true} 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}.
 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} indicating
 297      * the type of the image that will be associated with the
 298      * metadata.
 299      *
 300      * @return {@code true} 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}.  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}.
 315      *
 316      * @exception IllegalArgumentException if {@code elementName}
 317      * is {@code null} 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}.
 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}.  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} 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}.
 335      *
 336      * @exception IllegalArgumentException if {@code elementName}
 337      * is {@code null} 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}.
 341      */
 342     int getElementMaxChildren(String elementName);
 343 
 344     /**
 345      * Returns a {@code String} containing a description of the
 346      * named element, or {@code null}.  The description will be
 347      * localized for the supplied {@code Locale} if possible.
 348      *
 349      * <p> If {@code locale} is {@code null}, the current
 350      * default {@code Locale} returned by {@code Locale.getLocale}
 351      * will be used.
 352      *
 353      * @param elementName the name of the element.
 354      * @param locale the {@code Locale} for which localization
 355      * will be attempted.
 356      *
 357      * @return the element description.
 358      *
 359      * @exception IllegalArgumentException if {@code elementName}
 360      * is {@code null}, 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_}, 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_*} constants.
 374      *
 375      * @exception IllegalArgumentException if {@code elementName}
 376      * is {@code null} 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}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} is returned.
 386      *
 387      * @param elementName the name of the element being queried.
 388      *
 389      * @return an array of {@code String}s, or null.
 390      *
 391      * @exception IllegalArgumentException if {@code elementName}
 392      * is {@code null} 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}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}s.
 406      *
 407      * @exception IllegalArgumentException if {@code elementName}
 408      * is {@code null} 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_},
 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_*} constants.
 424      *
 425      * @exception IllegalArgumentException if {@code elementName}
 426      * is {@code null} or is not a legal element name for this
 427      * format.
 428      * @exception IllegalArgumentException if {@code attrName} is
 429      * {@code null} 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_}, indicating the format and
 437      * interpretation of the value of the given attribute within the
 438      * named element.  If {@code getAttributeValueType} returns
 439      * {@code VALUE_LIST}, 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_*} constants.
 446      *
 447      * @exception IllegalArgumentException if {@code elementName}
 448      * is {@code null} or is not a legal element name for this
 449      * format.
 450      * @exception IllegalArgumentException if {@code attrName} is
 451      * {@code null} 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} 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} if the attribute must be present.
 464      *
 465      * @exception IllegalArgumentException if {@code elementName}
 466      * is {@code null} or is not a legal element name for this
 467      * format.
 468      * @exception IllegalArgumentException if {@code attrName} is
 469      * {@code null} 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}, or {@code null} 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} containing the default value, or
 484      * {@code null}.
 485      *
 486      * @exception IllegalArgumentException if {@code elementName}
 487      * is {@code null} or is not a legal element name for this
 488      * format.
 489      * @exception IllegalArgumentException if {@code attrName} is
 490      * {@code null} 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}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} returns
 500      * {@code VALUE_ENUMERATION}.
 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}s.
 506      *
 507      * @exception IllegalArgumentException if {@code elementName}
 508      * is {@code null} or is not a legal element name for this
 509      * format.
 510      * @exception IllegalArgumentException if {@code attrName} is
 511      * {@code null} 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}.  The value is
 522      * returned as a {@code String}; its interpretation is
 523      * dependent on the value of {@code getAttributeDataType}.
 524      * This method should only be called if
 525      * {@code getAttributeValueType} returns
 526      * {@code VALUE_RANGE_*}.
 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} containing the smallest legal
 532      * value for the attribute.
 533      *
 534      * @exception IllegalArgumentException if {@code elementName}
 535      * is {@code null} or is not a legal element name for this
 536      * format.
 537      * @exception IllegalArgumentException if {@code attrName} is
 538      * {@code null} 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}.  The value is
 549      * returned as a {@code String}; its interpretation is
 550      * dependent on the value of {@code getAttributeDataType}.
 551      * This method should only be called if
 552      * {@code getAttributeValueType} returns
 553      * {@code VALUE_RANGE_*}.
 554      *
 555      * @param elementName the name of the element being queried, as a
 556      * {@code String}.
 557      * @param attrName the name of the attribute being queried.
 558      *
 559      * @return a {@code String} containing the largest legal
 560      * value for the attribute.
 561      *
 562      * @exception IllegalArgumentException if {@code elementName}
 563      * is {@code null} or is not a legal element name for this
 564      * format.
 565      * @exception IllegalArgumentException if {@code attrName} is
 566      * {@code null} 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} containing multiple whitespace-separated
 577      * items.  This method should only be called if
 578      * {@code getAttributeValueType} returns
 579      * {@code VALUE_LIST}.
 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}
 588      * is {@code null} or is not a legal element name for this
 589      * format.
 590      * @exception IllegalArgumentException if {@code attrName} is
 591      * {@code null} 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} may be used to specify that
 602      * there is no upper bound.  The attribute itself is defined as a
 603      * {@code String} containing multiple whitespace-separated
 604      * items.  This method should only be called if
 605      * {@code getAttributeValueType} returns
 606      * {@code VALUE_LIST}.
 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}
 615      * is {@code null} or is not a legal element name for this
 616      * format.
 617      * @exception IllegalArgumentException if {@code attrName} is
 618      * {@code null} 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} containing a description of the
 627      * named attribute, or {@code null}.  The description will be
 628      * localized for the supplied {@code Locale} if possible.
 629      *
 630      * <p> If {@code locale} is {@code null}, the current
 631      * default {@code Locale} returned by {@code Locale.getLocale}
 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} for which localization
 637      * will be attempted.
 638      *
 639      * @return the attribute description.
 640      *
 641      * @exception IllegalArgumentException if {@code elementName}
 642      * is {@code null}, or is not a legal element name for this format.
 643      * @exception IllegalArgumentException if {@code attrName} is
 644      * {@code null} 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_}, indicating the type of values
 655      * (enumeration, range, or array) that are allowed for the
 656      * {@code Object} reference.  If no object value can be
 657      * stored within the given element, the result of this method will
 658      * be {@code VALUE_NONE}.
 659      *
 660      * <p> {@code Object} references whose legal values are
 661      * defined as a range must implement the {@code Comparable}
 662      * interface.
 663      *
 664      * @param elementName the name of the element being queried.
 665      *
 666      * @return one of the {@code VALUE_*} constants.
 667      *
 668      * @exception IllegalArgumentException if {@code elementName}
 669      * is {@code null} 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} type of the {@code Object}
 678      * reference stored within the element.  If this element may not
 679      * contain an {@code Object} reference, an
 680      * {@code IllegalArgumentException} 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}s, this
 683      * method would return {@code int.class}).
 684      *
 685      * <p> {@code Object} references whose legal values are
 686      * defined as a range must implement the {@code Comparable}
 687      * interface.
 688      *
 689      * @param elementName the name of the element being queried.
 690      *
 691      * @return a {@code Class} object.
 692      *
 693      * @exception IllegalArgumentException if {@code elementName}
 694      * is {@code null} 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}).
 699      */
 700     Class<?> getObjectClass(String elementName);
 701 
 702     /**
 703      * Returns an {@code Object}s containing the default
 704      * value for the {@code Object} reference within
 705      * the named element.
 706      *
 707      * @param elementName the name of the element being queried.
 708      *
 709      * @return an {@code Object}.
 710      *
 711      * @exception IllegalArgumentException if {@code elementName}
 712      * is {@code null} 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}).
 717      */
 718     Object getObjectDefaultValue(String elementName);
 719 
 720     /**
 721      * Returns an array of {@code Object}s containing the legal
 722      * enumerated values for the {@code Object} reference within
 723      * the named element.  This method should only be called if
 724      * {@code getObjectValueType} returns
 725      * {@code VALUE_ENUMERATION}.
 726      *
 727      * <p> The {@code Object} 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 ==} operator (as
 730      * opposed to the {@code Object.equals} method).
 731      *
 732      * @param elementName the name of the element being queried.
 733      *
 734      * @return an array of {@code Object}s.
 735      *
 736      * @exception IllegalArgumentException if {@code elementName}
 737      * is {@code null} 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}).
 742      * @exception IllegalArgumentException if the {@code Object}
 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}
 749      * reference within the named element.  Whether this value is
 750      * inclusive or exclusive may be determined by the value of
 751      * {@code getObjectValueType}.  This method should only be
 752      * called if {@code getObjectValueType} returns one of the
 753      * constants starting with {@code VALUE_RANGE}.
 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}
 760      * is {@code null} 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}).
 765      * @exception IllegalArgumentException if the {@code Object}
 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}
 772      * reference within the named element.  Whether this value is
 773      * inclusive or exclusive may be determined by the value of
 774      * {@code getObjectValueType}.  This method should only be
 775      * called if {@code getObjectValueType} returns one of the
 776      * constants starting with {@code VALUE_RANGE}.
 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}
 783      * is {@code null} 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}).
 788      * @exception IllegalArgumentException if the {@code Object}
 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} reference within the named
 796      * element.  This method should only be called if
 797      * {@code getObjectValueType} returns
 798      * {@code VALUE_LIST}.
 799      *
 800      * @param elementName the name of the element being queried.
 801      *
 802      * @return the smallest valid array length for the
 803      * {@code Object} reference.
 804      *
 805      * @exception IllegalArgumentException if {@code elementName}
 806      * is {@code null} 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}).
 811      * @exception IllegalArgumentException if the {@code Object} 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} reference within the named
 819      * element.  A value of {@code Integer.MAX_VALUE} may be used
 820      * to specify that there is no upper bound.  This method should
 821      * only be called if {@code getObjectValueType} returns
 822      * {@code VALUE_LIST}.
 823      *
 824      * @param elementName the name of the element being queried.
 825      *
 826      * @return the largest valid array length for the
 827      * {@code Object} reference.
 828      *
 829      * @exception IllegalArgumentException if {@code elementName}
 830      * is {@code null} 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}).
 835      * @exception IllegalArgumentException if the {@code Object} is not
 836      * an array.
 837      */
 838     int getObjectArrayMaxLength(String elementName);
 839 }