https://openjdk.java.net/ 
/*
 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.imageio.metadata;

import java.util.Locale;
import javax.imageio.ImageTypeSpecifier;


An object describing the structure of metadata documents returned
from IIOMetadata.getAsTree and passed to
IIOMetadata.setFromTree and mergeTree.
Document structures are described by a set of constraints on the
type and number of child elements that may belong to a given parent
element type, the names, types, and values of attributes that may
belong to an element, and the type and values of
Object reference that may be stored at a node.

 N.B: classes that implement this interface should contain a
method declared as public static getInstance() which
returns an instance of the class.  Commonly, an implementation will
construct only a single instance and cache it for future
invocations of getInstance.

 The structures that may be described by this class are a subset
of those expressible using XML document type definitions (DTDs),
with the addition of some basic information on the datatypes of
attributes and the ability to store an Object
reference within a node.  In the future, XML Schemas could be used
to represent these structures, and many others.

 The differences between
IIOMetadataFormat-described structures and DTDs are as
follows:

    

  •  Elements may not contain text or mix text with embedded
tags.

  •  The children of an element must conform to one of a few simple
patterns, described in the documentation for the
CHILD_* constants;

  •  The in-memory representation of an elements may contain a
reference to an Object.  There is no provision for
representing such objects textually.



/**
 * An object describing the structure of metadata documents returned
 * from <code>IIOMetadata.getAsTree</code> and passed to
 * <code>IIOMetadata.setFromTree</code> and <code>mergeTree</code>.
 * Document structures are described by a set of constraints on the
 * type and number of child elements that may belong to a given parent
 * element type, the names, types, and values of attributes that may
 * belong to an element, and the type and values of
 * <code>Object</code> reference that may be stored at a node.
 *
 * <p> N.B: classes that implement this interface should contain a
 * method declared as <code>public static getInstance()</code> which
 * returns an instance of the class.  Commonly, an implementation will
 * construct only a single instance and cache it for future
 * invocations of <code>getInstance</code>.
 *
 * <p> The structures that may be described by this class are a subset
 * of those expressible using XML document type definitions (DTDs),
 * with the addition of some basic information on the datatypes of
 * attributes and the ability to store an <code>Object</code>
 * reference within a node.  In the future, XML Schemas could be used
 * to represent these structures, and many others.
 *
 * <p> The differences between
 * <code>IIOMetadataFormat</code>-described structures and DTDs are as
 * follows:
 *
 * <ul>
 * <li> Elements may not contain text or mix text with embedded
 * tags.
 *
 * <li> The children of an element must conform to one of a few simple
 * patterns, described in the documentation for the
 * <code>CHILD_*</code> constants;
 *
 * <li> The in-memory representation of an elements may contain a
 * reference to an <code>Object</code>.  There is no provision for
 * representing such objects textually.
 * </ul>
 *
 */
public interface IIOMetadataFormat {

    // Child policies

    
A constant returned by getChildPolicy to indicate
that an element may not have any children.  In other words, it
is required to be a leaf node.

/**
     * A constant returned by <code>getChildPolicy</code> to indicate
     * that an element may not have any children.  In other words, it
     * is required to be a leaf node.
     */
    int CHILD_POLICY_EMPTY = 0;

    
A constant returned by getChildPolicy to indicate
that an element must have a single instance of each of its
legal child elements, in order.  In DTD terms, the contents of
the element are defined by a sequence a,b,c,d,....

/**
     * A constant returned by <code>getChildPolicy</code> to indicate
     * that an element must have a single instance of each of its
     * legal child elements, in order.  In DTD terms, the contents of
     * the element are defined by a sequence <code>a,b,c,d,...</code>.
     */
    int CHILD_POLICY_ALL = 1;

    
A constant returned by getChildPolicy to indicate
that an element must have zero or one instance of each of its
legal child elements, in order.  In DTD terms, the contents of
the element are defined by a sequence
a?,b?,c?,d?,....

/**
     * A constant returned by <code>getChildPolicy</code> to indicate
     * that an element must have zero or one instance of each of its
     * legal child elements, in order.  In DTD terms, the contents of
     * the element are defined by a sequence
     * <code>a?,b?,c?,d?,...</code>.
     */
    int CHILD_POLICY_SOME = 2;

    
A constant returned by getChildPolicy to indicate
that an element must have zero or one children, selected from
among its legal child elements.  In DTD terms, the contents of
the element are defined by a selection
a|b|c|d|....

/**
     * A constant returned by <code>getChildPolicy</code> to indicate
     * that an element must have zero or one children, selected from
     * among its legal child elements.  In DTD terms, the contents of
     * the element are defined by a selection
     * <code>a|b|c|d|...</code>.
     */
    int CHILD_POLICY_CHOICE = 3;

    
A constant returned by getChildPolicy to indicate
that an element must have a sequence of instances of any of its
legal child elements.  In DTD terms, the contents of the
element are defined by a sequence (a|b|c|d|...)*.

/**
     * A constant returned by <code>getChildPolicy</code> to indicate
     * that an element must have a sequence of instances of any of its
     * legal child elements.  In DTD terms, the contents of the
     * element are defined by a sequence <code>(a|b|c|d|...)*</code>.
     */
    int CHILD_POLICY_SEQUENCE = 4;

    
A constant returned by getChildPolicy to indicate
that an element must have zero or more instances of its unique
legal child element.  In DTD terms, the contents of the element
are defined by a starred expression a*.

/**
     * A constant returned by <code>getChildPolicy</code> to indicate
     * that an element must have zero or more instances of its unique
     * legal child element.  In DTD terms, the contents of the element
     * are defined by a starred expression <code>a*</code>.
     */
    int CHILD_POLICY_REPEAT = 5;

    
The largest valid CHILD_POLICY_* constant,
to be used for range checks.

/**
     * The largest valid <code>CHILD_POLICY_*</code> constant,
     * to be used for range checks.
     */
    int CHILD_POLICY_MAX = CHILD_POLICY_REPEAT;

    
A constant returned by getObjectValueType to
indicate the absence of a user object.

/**
     * A constant returned by <code>getObjectValueType</code> to
     * indicate the absence of a user object.
     */
    int VALUE_NONE = 0;

    
A constant returned by getAttributeValueType and
getObjectValueType to indicate that the attribute
or user object may be set a single, arbitrary value.

/**
     * A constant returned by <code>getAttributeValueType</code> and
     * <code>getObjectValueType</code> to indicate that the attribute
     * or user object may be set a single, arbitrary value.
     */
    int VALUE_ARBITRARY = 1;

    
A constant returned by getAttributeValueType and
getObjectValueType to indicate that the attribute
or user object may be set a range of values.  Both the minimum
and maximum values of the range are exclusive.  It is
recommended that ranges of integers be inclusive on both ends,
and that exclusive ranges be used only for floating-point data.

See Also:
  • VALUE_RANGE_MIN_MAX_INCLUSIVE
/**
     * A constant returned by <code>getAttributeValueType</code> and
     * <code>getObjectValueType</code> to indicate that the attribute
     * or user object may be set a range of values.  Both the minimum
     * and maximum values of the range are exclusive.  It is
     * recommended that ranges of integers be inclusive on both ends,
     * and that exclusive ranges be used only for floating-point data.
     *
     * @see #VALUE_RANGE_MIN_MAX_INCLUSIVE
     */
    int VALUE_RANGE = 2;

    
A value that may be or'ed with VALUE_RANGE to
obtain VALUE_RANGE_MIN_INCLUSIVE, and with
VALUE_RANGE_MAX_INCLUSIVE to obtain
VALUE_RANGE_MIN_MAX_INCLUSIVE.

 Similarly, the value may be and'ed with the value of
getAttributeValueTypeor
getObjectValueType to determine if the minimum
value of the range is inclusive.

/**
     * A value that may be or'ed with <code>VALUE_RANGE</code> to
     * obtain <code>VALUE_RANGE_MIN_INCLUSIVE</code>, and with
     * <code>VALUE_RANGE_MAX_INCLUSIVE</code> to obtain
     * <code>VALUE_RANGE_MIN_MAX_INCLUSIVE</code>.
     *
     * <p> Similarly, the value may be and'ed with the value of
     * <code>getAttributeValueType</code>or
     * <code>getObjectValueType</code> to determine if the minimum
     * value of the range is inclusive.
     */
    int VALUE_RANGE_MIN_INCLUSIVE_MASK = 4;

    
A value that may be or'ed with VALUE_RANGE to
obtain VALUE_RANGE_MAX_INCLUSIVE, and with
VALUE_RANGE_MIN_INCLUSIVE to obtain
VALUE_RANGE_MIN_MAX_INCLUSIVE.

 Similarly, the value may be and'ed with the value of
getAttributeValueTypeor
getObjectValueType to determine if the maximum
value of the range is inclusive.

/**
     * A value that may be or'ed with <code>VALUE_RANGE</code> to
     * obtain <code>VALUE_RANGE_MAX_INCLUSIVE</code>, and with
     * <code>VALUE_RANGE_MIN_INCLUSIVE</code> to obtain
     * <code>VALUE_RANGE_MIN_MAX_INCLUSIVE</code>.
     *
     * <p> Similarly, the value may be and'ed with the value of
     * <code>getAttributeValueType</code>or
     * <code>getObjectValueType</code> to determine if the maximum
     * value of the range is inclusive.
     */
    int VALUE_RANGE_MAX_INCLUSIVE_MASK = 8;

    
A constant returned by getAttributeValueType and
getObjectValueType to indicate that the attribute
or user object may be set to a range of values.  The minimum
(but not the maximum) value of the range is inclusive.

/**
     * A constant returned by <code>getAttributeValueType</code> and
     * <code>getObjectValueType</code> to indicate that the attribute
     * or user object may be set to a range of values.  The minimum
     * (but not the maximum) value of the range is inclusive.
     */
    int VALUE_RANGE_MIN_INCLUSIVE = VALUE_RANGE |
        VALUE_RANGE_MIN_INCLUSIVE_MASK;

    
A constant returned by getAttributeValueType and
getObjectValueType to indicate that the attribute
or user object may be set to a range of values.  The maximum
(but not the minimum) value of the range is inclusive.

/**
     * A constant returned by <code>getAttributeValueType</code> and
     * <code>getObjectValueType</code> to indicate that the attribute
     * or user object may be set to a range of values.  The maximum
     * (but not the minimum) value of the range is inclusive.
     */
    int VALUE_RANGE_MAX_INCLUSIVE = VALUE_RANGE |
        VALUE_RANGE_MAX_INCLUSIVE_MASK;

    
A constant returned by getAttributeValueType and
getObjectValueType to indicate that the attribute
or user object may be set a range of values.  Both the minimum
and maximum values of the range are inclusive.  It is
recommended that ranges of integers be inclusive on both ends,
and that exclusive ranges be used only for floating-point data.

/**
     * A constant returned by <code>getAttributeValueType</code> and
     * <code>getObjectValueType</code> to indicate that the attribute
     * or user object may be set a range of values.  Both the minimum
     * and maximum values of the range are inclusive.  It is
     * recommended that ranges of integers be inclusive on both ends,
     * and that exclusive ranges be used only for floating-point data.
     */
    int VALUE_RANGE_MIN_MAX_INCLUSIVE =
        VALUE_RANGE |
        VALUE_RANGE_MIN_INCLUSIVE_MASK |
        VALUE_RANGE_MAX_INCLUSIVE_MASK;

    
A constant returned by getAttributeValueType and
getObjectValueType to indicate that the attribute
or user object may be set one of a number of enumerated values.
In the case of attributes, these values are
Strings; for objects, they are
Objects implementing a given class or interface.

 Attribute values of type DATATYPE_BOOLEAN
should be marked as enumerations.

/**
     * A constant returned by <code>getAttributeValueType</code> and
     * <code>getObjectValueType</code> to indicate that the attribute
     * or user object may be set one of a number of enumerated values.
     * In the case of attributes, these values are
     * <code>String</code>s; for objects, they are
     * <code>Object</code>s implementing a given class or interface.
     *
     * <p> Attribute values of type <code>DATATYPE_BOOLEAN</code>
     * should be marked as enumerations.
     */
    int VALUE_ENUMERATION = 16;

    
A constant returned by getAttributeValueType and
getObjectValueType to indicate that the attribute
or user object may be set to a list or array of values.  In the
case of attributes, the list will consist of
whitespace-separated values within a String; for
objects, an array will be used.

/**
     * A constant returned by <code>getAttributeValueType</code> and
     * <code>getObjectValueType</code> to indicate that the attribute
     * or user object may be set to a list or array of values.  In the
     * case of attributes, the list will consist of
     * whitespace-separated values within a <code>String</code>; for
     * objects, an array will be used.
     */
    int VALUE_LIST = 32;

    
A constant returned by getAttributeDataType
indicating that the value of an attribute is a general Unicode
string.

/**
     * A constant returned by <code>getAttributeDataType</code>
     * indicating that the value of an attribute is a general Unicode
     * string.
     */
    int DATATYPE_STRING = 0;

    
A constant returned by getAttributeDataType
indicating that the value of an attribute is one of the boolean
values 'true' or 'false'.
Attribute values of type DATATYPE_BOOLEAN should be marked as
enumerations, and the permitted values should be the string
literal values "TRUE" or "FALSE", although a plugin may also
recognise lower or mixed case equivalents.

/**
     * A constant returned by <code>getAttributeDataType</code>
     * indicating that the value of an attribute is one of the boolean
     * values 'true' or 'false'.
     * Attribute values of type DATATYPE_BOOLEAN should be marked as
     * enumerations, and the permitted values should be the string
     * literal values "TRUE" or "FALSE", although a plugin may also
     * recognise lower or mixed case equivalents.
     */
    int DATATYPE_BOOLEAN = 1;

    
A constant returned by getAttributeDataType
indicating that the value of an attribute is a string
representation of an integer.

/**
     * A constant returned by <code>getAttributeDataType</code>
     * indicating that the value of an attribute is a string
     * representation of an integer.
     */
    int DATATYPE_INTEGER = 2;

    
A constant returned by getAttributeDataType
indicating that the value of an attribute is a string
representation of a decimal floating-point number.

/**
     * A constant returned by <code>getAttributeDataType</code>
     * indicating that the value of an attribute is a string
     * representation of a decimal floating-point number.
     */
    int DATATYPE_FLOAT = 3;

    
A constant returned by getAttributeDataType
indicating that the value of an attribute is a string
representation of a double-precision decimal floating-point
number.

/**
     * A constant returned by <code>getAttributeDataType</code>
     * indicating that the value of an attribute is a string
     * representation of a double-precision decimal floating-point
     * number.
     */
    int DATATYPE_DOUBLE = 4;

    // Root

    
Returns the name of the root element of the format.

Returns:a String.
/**
     * Returns the name of the root element of the format.
     *
     * @return a <code>String</code>.
     */
    String getRootName();

    // Multiplicity

    
Returns true if the element (and the subtree below
it) is allowed to appear in a metadata document for an image of
the given type, defined by an ImageTypeSpecifier.
For example, a metadata document format might contain an
element that describes the primary colors of the image, which
would not be allowed when writing a grayscale image.

Params:
  • elementName – the name of the element being queried.
  • imageType – an ImageTypeSpecifier indicating
the type of the image that will be associated with the
metadata.
Returns:true if the node is meaningful for images
of the given type.
/**
     * Returns <code>true</code> if the element (and the subtree below
     * it) is allowed to appear in a metadata document for an image of
     * the given type, defined by an <code>ImageTypeSpecifier</code>.
     * For example, a metadata document format might contain an
     * element that describes the primary colors of the image, which
     * would not be allowed when writing a grayscale image.
     *
     * @param elementName the name of the element being queried.
     * @param imageType an <code>ImageTypeSpecifier</code> indicating
     * the type of the image that will be associated with the
     * metadata.
     *
     * @return <code>true</code> if the node is meaningful for images
     * of the given type.
     */
    boolean canNodeAppear(String elementName, ImageTypeSpecifier imageType);

    
Returns the minimum number of children of the named element
with child policy CHILD_POLICY_REPEAT.  For
example, an element representing color primary information
might be required to have at least 3 children, one for each
primary.

Params:
  • elementName – the name of the element being queried.
Throws:
Returns:an int.
/**
     * Returns the minimum number of children of the named element
     * with child policy <code>CHILD_POLICY_REPEAT</code>.  For
     * example, an element representing color primary information
     * might be required to have at least 3 children, one for each
     * primary.
     *
     * @param elementName the name of the element being queried.
     *
     * @return an <code>int</code>.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if the named element does
     * not have a child policy of <code>CHILD_POLICY_REPEAT</code>.
     */
    int getElementMinChildren(String elementName);

    
Returns the maximum number of children of the named element
with child policy CHILD_POLICY_REPEAT.  For
example, an element representing an entry in an 8-bit color
palette might be allowed to repeat up to 256 times.  A value of
Integer.MAX_VALUE may be used to specify that
there is no upper bound.

Params:
  • elementName – the name of the element being queried.
Throws:
Returns:an int.
/**
     * Returns the maximum number of children of the named element
     * with child policy <code>CHILD_POLICY_REPEAT</code>.  For
     * example, an element representing an entry in an 8-bit color
     * palette might be allowed to repeat up to 256 times.  A value of
     * <code>Integer.MAX_VALUE</code> may be used to specify that
     * there is no upper bound.
     *
     * @param elementName the name of the element being queried.
     *
     * @return an <code>int</code>.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if the named element does
     * not have a child policy of <code>CHILD_POLICY_REPEAT</code>.
     */
    int getElementMaxChildren(String elementName);

    
Returns a String containing a description of the
named element, or null.  The description will be
localized for the supplied Locale if possible.

 If locale is null, the current
default Locale returned by Locale.getLocale
will be used.

Params:
  • elementName – the name of the element.
  • locale – the Locale for which localization
will be attempted.
Throws:
Returns:the element description.
/**
     * Returns a <code>String</code> containing a description of the
     * named element, or <code>null</code>.  The description will be
     * localized for the supplied <code>Locale</code> if possible.
     *
     * <p> If <code>locale</code> is <code>null</code>, the current
     * default <code>Locale</code> returned by <code>Locale.getLocale</code>
     * will be used.
     *
     * @param elementName the name of the element.
     * @param locale the <code>Locale</code> for which localization
     * will be attempted.
     *
     * @return the element description.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code>, or is not a legal element name for this format.
     */
    String getElementDescription(String elementName, Locale locale);

    // Children

    
Returns one of the constants starting with
CHILD_POLICY_, indicating the legal pattern of
children for the named element.

Params:
  • elementName – the name of the element being queried.
Throws:
Returns:one of the CHILD_POLICY_* constants.
/**
     * Returns one of the constants starting with
     * <code>CHILD_POLICY_</code>, indicating the legal pattern of
     * children for the named element.
     *
     * @param elementName the name of the element being queried.
     *
     * @return one of the <code>CHILD_POLICY_*</code> constants.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     */
    int getChildPolicy(String elementName);

    
Returns an array of Strings indicating the names
of the element which are allowed to be children of the named
element, in the order in which they should appear.  If the
element cannot have children, null is returned.

Params:
  • elementName – the name of the element being queried.
Throws:
Returns:an array of Strings, or null.
/**
     * Returns an array of <code>String</code>s indicating the names
     * of the element which are allowed to be children of the named
     * element, in the order in which they should appear.  If the
     * element cannot have children, <code>null</code> is returned.
     *
     * @param elementName the name of the element being queried.
     *
     * @return an array of <code>String</code>s, or null.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     */
    String[] getChildNames(String elementName);

    // Attributes

    
Returns an array of Strings listing the names of
the attributes that may be associated with the named element.

Params:
  • elementName – the name of the element being queried.
Throws:
Returns:an array of Strings.
/**
     * Returns an array of <code>String</code>s listing the names of
     * the attributes that may be associated with the named element.
     *
     * @param elementName the name of the element being queried.
     *
     * @return an array of <code>String</code>s.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     */
    String[] getAttributeNames(String elementName);

    
Returns one of the constants starting with VALUE_,
indicating whether the values of the given attribute within the
named element are arbitrary, constrained to lie within a
specified range, constrained to be one of a set of enumerated
values, or are a whitespace-separated list of arbitrary values.

Params:
  • elementName – the name of the element being queried.
  • attrName – the name of the attribute being queried.
Throws:
Returns:one of the VALUE_* constants.
/**
     * Returns one of the constants starting with <code>VALUE_</code>,
     * indicating whether the values of the given attribute within the
     * named element are arbitrary, constrained to lie within a
     * specified range, constrained to be one of a set of enumerated
     * values, or are a whitespace-separated list of arbitrary values.
     *
     * @param elementName the name of the element being queried.
     * @param attrName the name of the attribute being queried.
     *
     * @return one of the <code>VALUE_*</code> constants.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if <code>attrName</code> is
     * <code>null</code> or is not a legal attribute name for this
     * element.
     */
    int getAttributeValueType(String elementName, String attrName);

    
Returns one of the constants starting with
DATATYPE_, indicating the format and
interpretation of the value of the given attribute within the
named element.  If getAttributeValueType returns
VALUE_LIST, then the legal value is a
whitespace-spearated list of values of the returned datatype.

Params:
  • elementName – the name of the element being queried.
  • attrName – the name of the attribute being queried.
Throws:
Returns:one of the DATATYPE_* constants.
/**
     * Returns one of the constants starting with
     * <code>DATATYPE_</code>, indicating the format and
     * interpretation of the value of the given attribute within the
     * named element.  If <code>getAttributeValueType</code> returns
     * <code>VALUE_LIST</code>, then the legal value is a
     * whitespace-spearated list of values of the returned datatype.
     *
     * @param elementName the name of the element being queried.
     * @param attrName the name of the attribute being queried.
     *
     * @return one of the <code>DATATYPE_*</code> constants.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if <code>attrName</code> is
     * <code>null</code> or is not a legal attribute name for this
     * element.
     */
    int getAttributeDataType(String elementName, String attrName);

    
Returns true if the named attribute must be
present within the named element.

Params:
  • elementName – the name of the element being queried.
  • attrName – the name of the attribute being queried.
Throws:
Returns:true if the attribute must be present.
/**
     * Returns <code>true</code> if the named attribute must be
     * present within the named element.
     *
     * @param elementName the name of the element being queried.
     * @param attrName the name of the attribute being queried.
     *
     * @return <code>true</code> if the attribute must be present.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if <code>attrName</code> is
     * <code>null</code> or is not a legal attribute name for this
     * element.
     */
    boolean isAttributeRequired(String elementName, String attrName);

    
Returns the default value of the named attribute, if it is not
explicitly present within the named element, as a
String, or null if no default value
is available.

Params:
  • elementName – the name of the element being queried.
  • attrName – the name of the attribute being queried.
Throws:
Returns:a String containing the default value, or
null.
/**
     * Returns the default value of the named attribute, if it is not
     * explicitly present within the named element, as a
     * <code>String</code>, or <code>null</code> if no default value
     * is available.
     *
     * @param elementName the name of the element being queried.
     * @param attrName the name of the attribute being queried.
     *
     * @return a <code>String</code> containing the default value, or
     * <code>null</code>.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if <code>attrName</code> is
     * <code>null</code> or is not a legal attribute name for this
     * element.
     */
    String getAttributeDefaultValue(String elementName, String attrName);

    
Returns an array of Strings containing the legal
enumerated values for the given attribute within the named
element.  This method should only be called if
getAttributeValueType returns
VALUE_ENUMERATION.

Params:
  • elementName – the name of the element being queried.
  • attrName – the name of the attribute being queried.
Throws:
Returns:an array of Strings.
/**
     * Returns an array of <code>String</code>s containing the legal
     * enumerated values for the given attribute within the named
     * element.  This method should only be called if
     * <code>getAttributeValueType</code> returns
     * <code>VALUE_ENUMERATION</code>.
     *
     * @param elementName the name of the element being queried.
     * @param attrName the name of the attribute being queried.
     *
     * @return an array of <code>String</code>s.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if <code>attrName</code> is
     * <code>null</code> or is not a legal attribute name for this
     * element.
     * @exception IllegalArgumentException if the given attribute is
     * not defined as an enumeration.
     */
    String[] getAttributeEnumerations(String elementName, String attrName);

    
Returns the minimum legal value for the attribute.  Whether
this value is inclusive or exclusive may be determined by the
value of getAttributeValueType.  The value is
returned as a String; its interpretation is
dependent on the value of getAttributeDataType.
This method should only be called if
getAttributeValueType returns
VALUE_RANGE_*.

Params:
  • elementName – the name of the element being queried.
  • attrName – the name of the attribute being queried.
Throws:
Returns:a String containing the smallest legal
value for the attribute.
/**
     * Returns the minimum legal value for the attribute.  Whether
     * this value is inclusive or exclusive may be determined by the
     * value of <code>getAttributeValueType</code>.  The value is
     * returned as a <code>String</code>; its interpretation is
     * dependent on the value of <code>getAttributeDataType</code>.
     * This method should only be called if
     * <code>getAttributeValueType</code> returns
     * <code>VALUE_RANGE_*</code>.
     *
     * @param elementName the name of the element being queried.
     * @param attrName the name of the attribute being queried.
     *
     * @return a <code>String</code> containing the smallest legal
     * value for the attribute.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if <code>attrName</code> is
     * <code>null</code> or is not a legal attribute name for this
     * element.
     * @exception IllegalArgumentException if the given attribute is
     * not defined as a range.
     */
    String getAttributeMinValue(String elementName, String attrName);

    
Returns the maximum legal value for the attribute.  Whether
this value is inclusive or exclusive may be determined by the
value of getAttributeValueType.  The value is
returned as a String; its interpretation is
dependent on the value of getAttributeDataType.
This method should only be called if
getAttributeValueType returns
VALUE_RANGE_*.

Params:
  • elementName – the name of the element being queried, as a
String.
  • attrName – the name of the attribute being queried.
Throws:
Returns:a String containing the largest legal
value for the attribute.
/**
     * Returns the maximum legal value for the attribute.  Whether
     * this value is inclusive or exclusive may be determined by the
     * value of <code>getAttributeValueType</code>.  The value is
     * returned as a <code>String</code>; its interpretation is
     * dependent on the value of <code>getAttributeDataType</code>.
     * This method should only be called if
     * <code>getAttributeValueType</code> returns
     * <code>VALUE_RANGE_*</code>.
     *
     * @param elementName the name of the element being queried, as a
     * <code>String</code>.
     * @param attrName the name of the attribute being queried.
     *
     * @return a <code>String</code> containing the largest legal
     * value for the attribute.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if <code>attrName</code> is
     * <code>null</code> or is not a legal attribute name for this
     * element.
     * @exception IllegalArgumentException if the given attribute is
     * not defined as a range.
     */
    String getAttributeMaxValue(String elementName, String attrName);

    
Returns the minimum number of list items that may be used to
define this attribute.  The attribute itself is defined as a
String containing multiple whitespace-separated
items.  This method should only be called if
getAttributeValueType returns
VALUE_LIST.

Params:
  • elementName – the name of the element being queried.
  • attrName – the name of the attribute being queried.
Throws:
Returns:the smallest legal number of list items for the
attribute.
/**
     * Returns the minimum number of list items that may be used to
     * define this attribute.  The attribute itself is defined as a
     * <code>String</code> containing multiple whitespace-separated
     * items.  This method should only be called if
     * <code>getAttributeValueType</code> returns
     * <code>VALUE_LIST</code>.
     *
     * @param elementName the name of the element being queried.
     * @param attrName the name of the attribute being queried.
     *
     * @return the smallest legal number of list items for the
     * attribute.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if <code>attrName</code> is
     * <code>null</code> or is not a legal attribute name for this
     * element.
     * @exception IllegalArgumentException if the given attribute is
     * not defined as a list.
     */
    int getAttributeListMinLength(String elementName, String attrName);

    
Returns the maximum number of list items that may be used to
define this attribute.  A value of
Integer.MAX_VALUE may be used to specify that
there is no upper bound.  The attribute itself is defined as a
String containing multiple whitespace-separated
items.  This method should only be called if
getAttributeValueType returns
VALUE_LIST.

Params:
  • elementName – the name of the element being queried.
  • attrName – the name of the attribute being queried.
Throws:
Returns:the largest legal number of list items for the
attribute.
/**
     * Returns the maximum number of list items that may be used to
     * define this attribute.  A value of
     * <code>Integer.MAX_VALUE</code> may be used to specify that
     * there is no upper bound.  The attribute itself is defined as a
     * <code>String</code> containing multiple whitespace-separated
     * items.  This method should only be called if
     * <code>getAttributeValueType</code> returns
     * <code>VALUE_LIST</code>.
     *
     * @param elementName the name of the element being queried.
     * @param attrName the name of the attribute being queried.
     *
     * @return the largest legal number of list items for the
     * attribute.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if <code>attrName</code> is
     * <code>null</code> or is not a legal attribute name for this
     * element.
     * @exception IllegalArgumentException if the given attribute is
     * not defined as a list.
     */
    int getAttributeListMaxLength(String elementName, String attrName);

    
Returns a String containing a description of the
named attribute, or null.  The description will be
localized for the supplied Locale if possible.

 If locale is null, the current
default Locale returned by Locale.getLocale
will be used.

Params:
  • elementName – the name of the element.
  • attrName – the name of the attribute.
  • locale – the Locale for which localization
will be attempted.
Throws:
Returns:the attribute description.
/**
     * Returns a <code>String</code> containing a description of the
     * named attribute, or <code>null</code>.  The description will be
     * localized for the supplied <code>Locale</code> if possible.
     *
     * <p> If <code>locale</code> is <code>null</code>, the current
     * default <code>Locale</code> returned by <code>Locale.getLocale</code>
     * will be used.
     *
     * @param elementName the name of the element.
     * @param attrName the name of the attribute.
     * @param locale the <code>Locale</code> for which localization
     * will be attempted.
     *
     * @return the attribute description.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code>, or is not a legal element name for this format.
     * @exception IllegalArgumentException if <code>attrName</code> is
     * <code>null</code> or is not a legal attribute name for this
     * element.
     */
    String getAttributeDescription(String elementName, String attrName,
                                   Locale locale);

    // Object value

    
Returns one of the enumerated values starting with
VALUE_, indicating the type of values
(enumeration, range, or array) that are allowed for the
Object reference.  If no object value can be
stored within the given element, the result of this method will
be VALUE_NONE.

 Object references whose legal values are
defined as a range must implement the Comparable
interface.

Params:
  • elementName – the name of the element being queried.
Throws:
See Also:
Returns:one of the VALUE_* constants.
/**
     * Returns one of the enumerated values starting with
     * <code>VALUE_</code>, indicating the type of values
     * (enumeration, range, or array) that are allowed for the
     * <code>Object</code> reference.  If no object value can be
     * stored within the given element, the result of this method will
     * be <code>VALUE_NONE</code>.
     *
     * <p> <code>Object</code> references whose legal values are
     * defined as a range must implement the <code>Comparable</code>
     * interface.
     *
     * @param elementName the name of the element being queried.
     *
     * @return one of the <code>VALUE_*</code> constants.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     *
     * @see Comparable
     */
    int getObjectValueType(String elementName);

    
Returns the Class type of the Object
reference stored within the element.  If this element may not
contain an Object reference, an
IllegalArgumentException will be thrown.  If the
class type is an array, this field indicates the underlying
class type (e.g, for an array of ints, this
method would return int.class).

 Object references whose legal values are
defined as a range must implement the Comparable
interface.

Params:
  • elementName – the name of the element being queried.
Throws:
Returns:a Class object.
/**
     * Returns the <code>Class</code> type of the <code>Object</code>
     * reference stored within the element.  If this element may not
     * contain an <code>Object</code> reference, an
     * <code>IllegalArgumentException</code> will be thrown.  If the
     * class type is an array, this field indicates the underlying
     * class type (<i>e.g</i>, for an array of <code>int</code>s, this
     * method would return <code>int.class</code>).
     *
     * <p> <code>Object</code> references whose legal values are
     * defined as a range must implement the <code>Comparable</code>
     * interface.
     *
     * @param elementName the name of the element being queried.
     *
     * @return a <code>Class</code> object.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if the named element cannot
     * contain an object value (<i>i.e.</i>, if
     * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
     */
    Class<?> getObjectClass(String elementName);

    
Returns an Objects containing the default
value for the Object reference within
the named element.

Params:
  • elementName – the name of the element being queried.
Throws:
Returns:an Object.
/**
     * Returns an <code>Object</code>s containing the default
     * value for the <code>Object</code> reference within
     * the named element.
     *
     * @param elementName the name of the element being queried.
     *
     * @return an <code>Object</code>.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if the named element cannot
     * contain an object value (<i>i.e.</i>, if
     * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
     */
    Object getObjectDefaultValue(String elementName);

    
Returns an array of Objects containing the legal
enumerated values for the Object reference within
the named element.  This method should only be called if
getObjectValueType returns
VALUE_ENUMERATION.

 The Object associated with a node that accepts
enumerated values must be equal to one of the values returned by
this method, as defined by the == operator (as
opposed to the Object.equals method).

Params:
  • elementName – the name of the element being queried.
Throws:
Returns:an array of Objects.
/**
     * Returns an array of <code>Object</code>s containing the legal
     * enumerated values for the <code>Object</code> reference within
     * the named element.  This method should only be called if
     * <code>getObjectValueType</code> returns
     * <code>VALUE_ENUMERATION</code>.
     *
     * <p> The <code>Object</code> associated with a node that accepts
     * enumerated values must be equal to one of the values returned by
     * this method, as defined by the <code>==</code> operator (as
     * opposed to the <code>Object.equals</code> method).
     *
     * @param elementName the name of the element being queried.
     *
     * @return an array of <code>Object</code>s.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if the named element cannot
     * contain an object value (<i>i.e.</i>, if
     * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
     * @exception IllegalArgumentException if the <code>Object</code>
     * is not defined as an enumeration.
     */
    Object[] getObjectEnumerations(String elementName);

    
Returns the minimum legal value for the Object
reference within the named element.  Whether this value is
inclusive or exclusive may be determined by the value of
getObjectValueType.  This method should only be
called if getObjectValueType returns one of the
constants starting with VALUE_RANGE.

Params:
  • elementName – the name of the element being queried.
Throws:
Returns:the smallest legal value for the attribute.
/**
     * Returns the minimum legal value for the <code>Object</code>
     * reference within the named element.  Whether this value is
     * inclusive or exclusive may be determined by the value of
     * <code>getObjectValueType</code>.  This method should only be
     * called if <code>getObjectValueType</code> returns one of the
     * constants starting with <code>VALUE_RANGE</code>.
     *
     * @param elementName the name of the element being queried.
     *
     * @return the smallest legal value for the attribute.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if the named element cannot
     * contain an object value (<i>i.e.</i>, if
     * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
     * @exception IllegalArgumentException if the <code>Object</code>
     * is not defined as a range.
     */
    Comparable<?> getObjectMinValue(String elementName);

    
Returns the maximum legal value for the Object
reference within the named element.  Whether this value is
inclusive or exclusive may be determined by the value of
getObjectValueType.  This method should only be
called if getObjectValueType returns one of the
constants starting with VALUE_RANGE.

Params:
  • elementName – the name of the element being queried.
Throws:
Returns:the smallest legal value for the attribute.
/**
     * Returns the maximum legal value for the <code>Object</code>
     * reference within the named element.  Whether this value is
     * inclusive or exclusive may be determined by the value of
     * <code>getObjectValueType</code>.  This method should only be
     * called if <code>getObjectValueType</code> returns one of the
     * constants starting with <code>VALUE_RANGE</code>.
     *
     * @return the smallest legal value for the attribute.
     *
     * @param elementName the name of the element being queried.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if the named element cannot
     * contain an object value (<i>i.e.</i>, if
     * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
     * @exception IllegalArgumentException if the <code>Object</code>
     * is not defined as a range.
     */
    Comparable<?> getObjectMaxValue(String elementName);

    
Returns the minimum number of array elements that may be used
to define the Object reference within the named
element.  This method should only be called if
getObjectValueType returns
VALUE_LIST.

Params:
  • elementName – the name of the element being queried.
Throws:
Returns:the smallest valid array length for the
Object reference.
/**
     * Returns the minimum number of array elements that may be used
     * to define the <code>Object</code> reference within the named
     * element.  This method should only be called if
     * <code>getObjectValueType</code> returns
     * <code>VALUE_LIST</code>.
     *
     * @param elementName the name of the element being queried.
     *
     * @return the smallest valid array length for the
     * <code>Object</code> reference.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if the named element cannot
     * contain an object value (<i>i.e.</i>, if
     * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
     * @exception IllegalArgumentException if the <code>Object</code> is not
     * an array.
     */
    int getObjectArrayMinLength(String elementName);

    
Returns the maximum number of array elements that may be used
to define the Object reference within the named
element.  A value of Integer.MAX_VALUE may be used
to specify that there is no upper bound.  This method should
only be called if getObjectValueType returns
VALUE_LIST.

Params:
  • elementName – the name of the element being queried.
Throws:
Returns:the largest valid array length for the
Object reference.
/**
     * Returns the maximum number of array elements that may be used
     * to define the <code>Object</code> reference within the named
     * element.  A value of <code>Integer.MAX_VALUE</code> may be used
     * to specify that there is no upper bound.  This method should
     * only be called if <code>getObjectValueType</code> returns
     * <code>VALUE_LIST</code>.
     *
     * @param elementName the name of the element being queried.
     *
     * @return the largest valid array length for the
     * <code>Object</code> reference.
     *
     * @exception IllegalArgumentException if <code>elementName</code>
     * is <code>null</code> or is not a legal element name for this
     * format.
     * @exception IllegalArgumentException if the named element cannot
     * contain an object value (<i>i.e.</i>, if
     * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
     * @exception IllegalArgumentException if the <code>Object</code> is not
     * an array.
     */
    int getObjectArrayMaxLength(String elementName);
}