0N/A/*
2362N/A * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved.
0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A *
0N/A * This code is free software; you can redistribute it and/or modify it
0N/A * under the terms of the GNU General Public License version 2 only, as
2362N/A * published by the Free Software Foundation. Oracle designates this
0N/A * particular file as subject to the "Classpath" exception as provided
2362N/A * by Oracle in the LICENSE file that accompanied this code.
0N/A *
0N/A * This code is distributed in the hope that it will be useful, but WITHOUT
0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0N/A * version 2 for more details (a copy is included in the LICENSE file that
0N/A * accompanied this code).
0N/A *
0N/A * You should have received a copy of the GNU General Public License version
0N/A * 2 along with this work; if not, write to the Free Software Foundation,
0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0N/A *
2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2362N/A * or visit www.oracle.com if you need additional information or have any
2362N/A * questions.
0N/A */
0N/A
0N/Apackage javax.imageio.metadata;
0N/A
0N/Aimport java.util.Locale;
0N/Aimport javax.imageio.ImageTypeSpecifier;
0N/A
0N/A/**
0N/A * An object describing the structure of metadata documents returned
0N/A * from <code>IIOMetadata.getAsTree</code> and passed to
0N/A * <code>IIOMetadata.setFromTree</code> and <code>mergeTree</code>.
0N/A * Document structures are described by a set of constraints on the
0N/A * type and number of child elements that may belong to a given parent
0N/A * element type, the names, types, and values of attributes that may
0N/A * belong to an element, and the type and values of
0N/A * <code>Object</code> reference that may be stored at a node.
0N/A *
0N/A * <p> N.B: classes that implement this interface should contain a
0N/A * method declared as <code>public static getInstance()</code> which
0N/A * returns an instance of the class. Commonly, an implentation will
0N/A * construct only a single instance and cache it for future
0N/A * invocations of <code>getInstance</code>.
0N/A *
0N/A * <p> The structures that may be described by this class are a subset
0N/A * of those expressible using XML document type definitions (DTDs),
0N/A * with the addition of some basic information on the datatypes of
0N/A * attributes and the ability to store an <code>Object</code>
0N/A * reference within a node. In the future, XML Schemas could be used
0N/A * to represent these structures, and many others.
0N/A *
0N/A * <p> The differences between
0N/A * <code>IIOMetadataFormat</code>-described structures and DTDs are as
0N/A * follows:
0N/A *
0N/A * <ul>
0N/A * <li> Elements may not contain text or mix text with embedded
0N/A * tags.
0N/A *
0N/A * <li> The children of an element must conform to one of a few simple
0N/A * patterns, described in the documentation for the
0N/A * <code>CHILD_*</code> constants;
0N/A *
0N/A * <li> The in-memory representation of an elements may contain a
0N/A * reference to an <code>Object</code>. There is no provision for
0N/A * representing such objects textually.
0N/A * </ul>
0N/A *
0N/A */
0N/Apublic interface IIOMetadataFormat {
0N/A
0N/A // Child policies
0N/A
0N/A /**
0N/A * A constant returned by <code>getChildPolicy</code> to indicate
0N/A * that an element may not have any children. In other words, it
0N/A * is required to be a leaf node.
0N/A */
0N/A int CHILD_POLICY_EMPTY = 0;
0N/A
0N/A /**
0N/A * A constant returned by <code>getChildPolicy</code> to indicate
0N/A * that an element must have a single instance of each of its
0N/A * legal child elements, in order. In DTD terms, the contents of
0N/A * the element are defined by a sequence <code>a,b,c,d,...</code>.
0N/A */
0N/A int CHILD_POLICY_ALL = 1;
0N/A
0N/A /**
0N/A * A constant returned by <code>getChildPolicy</code> to indicate
0N/A * that an element must have zero or one instance of each of its
0N/A * legal child elements, in order. In DTD terms, the contents of
0N/A * the element are defined by a sequence
0N/A * <code>a?,b?,c?,d?,...</code>.
0N/A */
0N/A int CHILD_POLICY_SOME = 2;
0N/A
0N/A /**
0N/A * A constant returned by <code>getChildPolicy</code> to indicate
0N/A * that an element must have zero or one children, selected from
0N/A * among its legal child elements. In DTD terms, the contents of
0N/A * the element are defined by a selection
0N/A * <code>a|b|c|d|...</code>.
0N/A */
0N/A int CHILD_POLICY_CHOICE = 3;
0N/A
0N/A /**
0N/A * A constant returned by <code>getChildPolicy</code> to indicate
0N/A * that an element must have a sequence of instances of any of its
0N/A * legal child elements. In DTD terms, the contents of the
0N/A * element are defined by a sequence <code>(a|b|c|d|...)*</code>.
0N/A */
0N/A int CHILD_POLICY_SEQUENCE = 4;
0N/A
0N/A /**
0N/A * A constant returned by <code>getChildPolicy</code> to indicate
0N/A * that an element must have zero or more instances of its unique
0N/A * legal child element. In DTD terms, the contents of the element
0N/A * are defined by a starred expression <code>a*</code>.
0N/A */
0N/A int CHILD_POLICY_REPEAT = 5;
0N/A
0N/A /**
0N/A * The largest valid <code>CHILD_POLICY_*</code> constant,
0N/A * to be used for range checks.
0N/A */
0N/A int CHILD_POLICY_MAX = CHILD_POLICY_REPEAT;
0N/A
0N/A /**
0N/A * A constant returned by <code>getObjectValueType</code> to
0N/A * indicate the absence of a user object.
0N/A */
0N/A int VALUE_NONE = 0;
0N/A
0N/A /**
0N/A * A constant returned by <code>getAttributeValueType</code> and
0N/A * <code>getObjectValueType</code> to indicate that the attribute
0N/A * or user object may be set a single, arbitrary value.
0N/A */
0N/A int VALUE_ARBITRARY = 1;
0N/A
0N/A /**
0N/A * A constant returned by <code>getAttributeValueType</code> and
0N/A * <code>getObjectValueType</code> to indicate that the attribute
0N/A * or user object may be set a range of values. Both the minimum
0N/A * and maximum values of the range are exclusive. It is
0N/A * recommended that ranges of integers be inclusive on both ends,
0N/A * and that exclusive ranges be used only for floating-point data.
0N/A *
0N/A * @see #VALUE_RANGE_MIN_MAX_INCLUSIVE
0N/A */
0N/A int VALUE_RANGE = 2;
0N/A
0N/A /**
0N/A * A value that may be or'ed with <code>VALUE_RANGE</code> to
0N/A * obtain <code>VALUE_RANGE_MIN_INCLUSIVE</code>, and with
0N/A * <code>VALUE_RANGE_MAX_INCLUSIVE</code> to obtain
0N/A * <code>VALUE_RANGE_MIN_MAX_INCLUSIVE</code>.
0N/A *
0N/A * <p> Similarly, the value may be and'ed with the value of
0N/A * <code>getAttributeValueType</code>or
0N/A * <code>getObjectValueType</code> to determine if the minimum
0N/A * value of the range is inclusive.
0N/A */
0N/A int VALUE_RANGE_MIN_INCLUSIVE_MASK = 4;
0N/A
0N/A /**
0N/A * A value that may be or'ed with <code>VALUE_RANGE</code> to
0N/A * obtain <code>VALUE_RANGE_MAX_INCLUSIVE</code>, and with
0N/A * <code>VALUE_RANGE_MIN_INCLUSIVE</code> to obtain
0N/A * <code>VALUE_RANGE_MIN_MAX_INCLUSIVE</code>.
0N/A *
0N/A * <p> Similarly, the value may be and'ed with the value of
0N/A * <code>getAttributeValueType</code>or
0N/A * <code>getObjectValueType</code> to determine if the maximum
0N/A * value of the range is inclusive.
0N/A */
0N/A int VALUE_RANGE_MAX_INCLUSIVE_MASK = 8;
0N/A
0N/A /**
0N/A * A constant returned by <code>getAttributeValueType</code> and
0N/A * <code>getObjectValueType</code> to indicate that the attribute
0N/A * or user object may be set to a range of values. The minimum
0N/A * (but not the maximum) value of the range is inclusive.
0N/A */
0N/A int VALUE_RANGE_MIN_INCLUSIVE = VALUE_RANGE |
0N/A VALUE_RANGE_MIN_INCLUSIVE_MASK;
0N/A
0N/A /**
0N/A * A constant returned by <code>getAttributeValueType</code> and
0N/A * <code>getObjectValueType</code> to indicate that the attribute
0N/A * or user object may be set to a range of values. The maximum
0N/A * (but not the minimum) value of the range is inclusive.
0N/A */
0N/A int VALUE_RANGE_MAX_INCLUSIVE = VALUE_RANGE |
0N/A VALUE_RANGE_MAX_INCLUSIVE_MASK;
0N/A
0N/A /**
0N/A * A constant returned by <code>getAttributeValueType</code> and
0N/A * <code>getObjectValueType</code> to indicate that the attribute
0N/A * or user object may be set a range of values. Both the minimum
0N/A * and maximum values of the range are inclusive. It is
0N/A * recommended that ranges of integers be inclusive on both ends,
0N/A * and that exclusive ranges be used only for floating-point data.
0N/A */
0N/A int VALUE_RANGE_MIN_MAX_INCLUSIVE =
0N/A VALUE_RANGE |
0N/A VALUE_RANGE_MIN_INCLUSIVE_MASK |
0N/A VALUE_RANGE_MAX_INCLUSIVE_MASK;
0N/A
0N/A /**
0N/A * A constant returned by <code>getAttributeValueType</code> and
0N/A * <code>getObjectValueType</code> to indicate that the attribute
0N/A * or user object may be set one of a number of enumerated values.
0N/A * In the case of attributes, these values are
0N/A * <code>String</code>s; for objects, they are
0N/A * <code>Object</code>s implementing a given class or interface.
0N/A *
0N/A * <p> Attribute values of type <code>DATATYPE_BOOLEAN</code>
0N/A * should be marked as enumerations.
0N/A */
0N/A int VALUE_ENUMERATION = 16;
0N/A
0N/A /**
0N/A * A constant returned by <code>getAttributeValueType</code> and
0N/A * <code>getObjectValueType</code> to indicate that the attribute
0N/A * or user object may be set to a list or array of values. In the
0N/A * case of attributes, the list will consist of
0N/A * whitespace-separated values within a <code>String</code>; for
0N/A * objects, an array will be used.
0N/A */
0N/A int VALUE_LIST = 32;
0N/A
0N/A /**
0N/A * A constant returned by <code>getAttributeDataType</code>
0N/A * indicating that the value of an attribute is a general Unicode
0N/A * string.
0N/A */
0N/A int DATATYPE_STRING = 0;
0N/A
0N/A /**
0N/A * A constant returned by <code>getAttributeDataType</code>
983N/A * indicating that the value of an attribute is one of the boolean
983N/A * values 'true' or 'false'.
983N/A * Attribute values of type DATATYPE_BOOLEAN should be marked as
983N/A * enumerations, and the permitted values should be the string
983N/A * literal values "TRUE" or "FALSE", although a plugin may also
983N/A * recognise lower or mixed case equivalents.
0N/A */
0N/A int DATATYPE_BOOLEAN = 1;
0N/A
0N/A /**
0N/A * A constant returned by <code>getAttributeDataType</code>
0N/A * indicating that the value of an attribute is a string
0N/A * representation of an integer.
0N/A */
0N/A int DATATYPE_INTEGER = 2;
0N/A
0N/A /**
0N/A * A constant returned by <code>getAttributeDataType</code>
0N/A * indicating that the value of an attribute is a string
0N/A * representation of a decimal floating-point number.
0N/A */
0N/A int DATATYPE_FLOAT = 3;
0N/A
0N/A /**
0N/A * A constant returned by <code>getAttributeDataType</code>
0N/A * indicating that the value of an attribute is a string
0N/A * representation of a double-precision decimal floating-point
0N/A * number.
0N/A */
0N/A int DATATYPE_DOUBLE = 4;
0N/A
0N/A // Root
0N/A
0N/A /**
0N/A * Returns the name of the root element of the format.
0N/A *
0N/A * @return a <code>String</code>.
0N/A */
0N/A String getRootName();
0N/A
0N/A // Multiplicity
0N/A
0N/A /**
0N/A * Returns <code>true</code> if the element (and the subtree below
0N/A * it) is allowed to appear in a metadata document for an image of
0N/A * the given type, defined by an <code>ImageTypeSpecifier</code>.
0N/A * For example, a metadata document format might contain an
0N/A * element that describes the primary colors of the image, which
0N/A * would not be allowed when writing a grayscale image.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A * @param imageType an <code>ImageTypeSpecifier</code> indicating
0N/A * the type of the image that will be associated with the
0N/A * metadata.
0N/A *
0N/A * @return <code>true</code> if the node is meaningful for images
0N/A * of the given type.
0N/A */
0N/A boolean canNodeAppear(String elementName, ImageTypeSpecifier imageType);
0N/A
0N/A /**
0N/A * Returns the minimum number of children of the named element
0N/A * with child policy <code>CHILD_POLICY_REPEAT</code>. For
0N/A * example, an element representing color primary information
0N/A * might be required to have at least 3 children, one for each
0N/A * primay.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A *
0N/A * @return an <code>int</code>.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if the named element does
0N/A * not have a child policy of <code>CHILD_POLICY_REPEAT</code>.
0N/A */
0N/A int getElementMinChildren(String elementName);
0N/A
0N/A /**
0N/A * Returns the maximum number of children of the named element
0N/A * with child policy <code>CHILD_POLICY_REPEAT</code>. For
0N/A * example, an element representing an entry in an 8-bit color
0N/A * palette might be allowed to repeat up to 256 times. A value of
0N/A * <code>Integer.MAX_VALUE</code> may be used to specify that
0N/A * there is no upper bound.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A *
0N/A * @return an <code>int</code>.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if the named element does
0N/A * not have a child policy of <code>CHILD_POLICY_REPEAT</code>.
0N/A */
0N/A int getElementMaxChildren(String elementName);
0N/A
0N/A /**
0N/A * Returns a <code>String</code> containing a description of the
0N/A * named element, or <code>null</code>. The desciption will be
0N/A * localized for the supplied <code>Locale</code> if possible.
0N/A *
0N/A * <p> If <code>locale</code> is <code>null</code>, the current
0N/A * default <code>Locale</code> returned by <code>Locale.getLocale</code>
0N/A * will be used.
0N/A *
0N/A * @param elementName the name of the element.
0N/A * @param locale the <code>Locale</code> for which localization
0N/A * will be attempted.
0N/A *
0N/A * @return the element description.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code>, or is not a legal element name for this format.
0N/A */
0N/A String getElementDescription(String elementName, Locale locale);
0N/A
0N/A // Children
0N/A
0N/A /**
0N/A * Returns one of the constants starting with
0N/A * <code>CHILD_POLICY_</code>, indicating the legal pattern of
0N/A * children for the named element.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A *
0N/A * @return one of the <code>CHILD_POLICY_*</code> constants.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A */
0N/A int getChildPolicy(String elementName);
0N/A
0N/A /**
0N/A * Returns an array of <code>String</code>s indicating the names
0N/A * of the element which are allowed to be children of the named
0N/A * element, in the order in which they should appear. If the
0N/A * element cannot have children, <code>null</code> is returned.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A *
0N/A * @return an array of <code>String</code>s, or null.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A */
0N/A String[] getChildNames(String elementName);
0N/A
0N/A // Attributes
0N/A
0N/A /**
0N/A * Returns an array of <code>String</code>s listing the names of
0N/A * the attributes that may be associated with the named element.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A *
0N/A * @return an array of <code>String</code>s.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A */
0N/A String[] getAttributeNames(String elementName);
0N/A
0N/A /**
0N/A * Returns one of the constants starting with <code>VALUE_</code>,
0N/A * indicating whether the values of the given attribute within the
0N/A * named element are arbitrary, constrained to lie within a
0N/A * specified range, constrained to be one of a set of enumerated
0N/A * values, or are a whitespace-separated list of arbitrary values.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A * @param attrName the name of the attribute being queried.
0N/A *
0N/A * @return one of the <code>VALUE_*</code> constants.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if <code>attrName</code> is
0N/A * <code>null</code> or is not a legal attribute name for this
0N/A * element.
0N/A */
0N/A int getAttributeValueType(String elementName, String attrName);
0N/A
0N/A /**
0N/A * Returns one of the constants starting with
0N/A * <code>DATATYPE_</code>, indicating the format and
0N/A * interpretation of the value of the given attribute within th
0N/A * enamed element. If <code>getAttributeValueType</code> returns
0N/A * <code>VALUE_LIST</code>, then the legal value is a
0N/A * whitespace-spearated list of values of the returned datatype.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A * @param attrName the name of the attribute being queried.
0N/A *
0N/A * @return one of the <code>DATATYPE_*</code> constants.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if <code>attrName</code> is
0N/A * <code>null</code> or is not a legal attribute name for this
0N/A * element.
0N/A */
0N/A int getAttributeDataType(String elementName, String attrName);
0N/A
0N/A /**
0N/A * Returns <code>true</code> if the named attribute must be
0N/A * present within the named element.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A * @param attrName the name of the attribute being queried.
0N/A *
0N/A * @return <code>true</code> if the attribut must be present.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if <code>attrName</code> is
0N/A * <code>null</code> or is not a legal attribute name for this
0N/A * element.
0N/A */
0N/A boolean isAttributeRequired(String elementName, String attrName);
0N/A
0N/A /**
0N/A * Returns the default value of the named attribute, if it is not
0N/A * explictly present within the named element, as a
0N/A * <code>String</code>, or <code>null</code> if no default value
0N/A * is available.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A * @param attrName the name of the attribute being queried.
0N/A *
0N/A * @return a <code>String</code> containing the default value, or
0N/A * <code>null</code>.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if <code>attrName</code> is
0N/A * <code>null</code> or is not a legal attribute name for this
0N/A * element.
0N/A */
0N/A String getAttributeDefaultValue(String elementName, String attrName);
0N/A
0N/A /**
0N/A * Returns an array of <code>String</code>s containing the legal
0N/A * enumerated values for the given attribute within the named
0N/A * element. This method should only be called if
0N/A * <code>getAttributeValueType</code> returns
0N/A * <code>VALUE_ENUMERATION</code>.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A * @param attrName the name of the attribute being queried.
0N/A *
0N/A * @return an array of <code>String</code>s.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if <code>attrName</code> is
0N/A * <code>null</code> or is not a legal attribute name for this
0N/A * element.
0N/A * @exception IllegalArgumentException if the given attribute is
0N/A * not defined as an enumeration.
0N/A */
0N/A String[] getAttributeEnumerations(String elementName, String attrName);
0N/A
0N/A /**
0N/A * Returns the minimum legal value for the attribute. Whether
0N/A * this value is inclusive or exclusive may be determined by the
0N/A * value of <code>getAttributeValueType</code>. The value is
0N/A * returned as a <code>String</code>; its interpretation is
0N/A * dependent on the value of <code>getAttributeDataType</code>.
0N/A * This method should only be called if
0N/A * <code>getAttributeValueType</code> returns
0N/A * <code>VALUE_RANGE_*</code>.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A * @param attrName the name of the attribute being queried.
0N/A *
0N/A * @return a <code>String</code> containing the smallest legal
0N/A * value for the attribute.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if <code>attrName</code> is
0N/A * <code>null</code> or is not a legal attribute name for this
0N/A * element.
0N/A * @exception IllegalArgumentException if the given attribute is
0N/A * not defined as a range.
0N/A */
0N/A String getAttributeMinValue(String elementName, String attrName);
0N/A
0N/A /**
0N/A * Returns the maximum legal value for the attribute. Whether
0N/A * this value is inclusive or exclusive may be determined by the
0N/A * value of <code>getAttributeValueType</code>. The value is
0N/A * returned as a <code>String</code>; its interpretation is
0N/A * dependent on the value of <code>getAttributeDataType</code>.
0N/A * This method should only be called if
0N/A * <code>getAttributeValueType</code> returns
0N/A * <code>VALUE_RANGE_*</code>.
0N/A *
0N/A * @param elementName the name of the element being queried, as a
0N/A * <code>String</code>.
0N/A * @param attrName the name of the attribute being queried.
0N/A *
0N/A * @return a <code>String</code> containing the largest legal
0N/A * value for the attribute.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if <code>attrName</code> is
0N/A * <code>null</code> or is not a legal attribute name for this
0N/A * element.
0N/A * @exception IllegalArgumentException if the given attribute is
0N/A * not defined as a range.
0N/A */
0N/A String getAttributeMaxValue(String elementName, String attrName);
0N/A
0N/A /**
0N/A * Returns the minimum number of list items that may be used to
0N/A * define this attribute. The attribute itself is defined as a
0N/A * <code>String</code> containing multiple whitespace-separated
0N/A * items. This method should only be called if
0N/A * <code>getAttributeValueType</code> returns
0N/A * <code>VALUE_LIST</code>.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A * @param attrName the name of the attribute being queried.
0N/A *
0N/A * @return the smallest legal number of list items for the
0N/A * attribute.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if <code>attrName</code> is
0N/A * <code>null</code> or is not a legal attribute name for this
0N/A * element.
0N/A * @exception IllegalArgumentException if the given attribute is
0N/A * not defined as a list.
0N/A */
0N/A int getAttributeListMinLength(String elementName, String attrName);
0N/A
0N/A /**
0N/A * Returns the maximum number of list items that may be used to
0N/A * define this attribute. A value of
0N/A * <code>Integer.MAX_VALUE</code> may be used to specify that
0N/A * there is no upper bound. The attribute itself is defined as a
0N/A * <code>String</code> containing multiple whitespace-separated
0N/A * items. This method should only be called if
0N/A * <code>getAttributeValueType</code> returns
0N/A * <code>VALUE_LIST</code>.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A * @param attrName the name of the attribute being queried.
0N/A *
0N/A * @return the largest legal number of list items for the
0N/A * attribute.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if <code>attrName</code> is
0N/A * <code>null</code> or is not a legal attribute name for this
0N/A * element.
0N/A * @exception IllegalArgumentException if the given attribute is
0N/A * not defined as a list.
0N/A */
0N/A int getAttributeListMaxLength(String elementName, String attrName);
0N/A
0N/A /**
0N/A * Returns a <code>String</code> containing a description of the
0N/A * named attribute, or <code>null</code>. The desciption will be
0N/A * localized for the supplied <code>Locale</code> if possible.
0N/A *
0N/A * <p> If <code>locale</code> is <code>null</code>, the current
0N/A * default <code>Locale</code> returned by <code>Locale.getLocale</code>
0N/A * will be used.
0N/A *
0N/A * @param elementName the name of the element.
0N/A * @param attrName the name of the attribute.
0N/A * @param locale the <code>Locale</code> for which localization
0N/A * will be attempted.
0N/A *
0N/A * @return the attribute description.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code>, or is not a legal element name for this format.
0N/A * @exception IllegalArgumentException if <code>attrName</code> is
0N/A * <code>null</code> or is not a legal attribute name for this
0N/A * element.
0N/A */
0N/A String getAttributeDescription(String elementName, String attrName,
0N/A Locale locale);
0N/A
0N/A // Object value
0N/A
0N/A /**
0N/A * Returns one of the enumerated values starting with
0N/A * <code>VALUE_</code>, indicating the type of values
0N/A * (enumeration, range, or array) that are allowed for the
0N/A * <code>Object</code> reference. If no object value can be
0N/A * stored within the given element, the result of this method will
0N/A * be <code>VALUE_NONE</code>.
0N/A *
0N/A * <p> <code>Object</code> references whose legal values are
0N/A * defined as a range must implement the <code>Comparable</code>
0N/A * interface.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A *
0N/A * @return one of the <code>VALUE_*</code> constants.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A *
0N/A * @see Comparable
0N/A */
0N/A int getObjectValueType(String elementName);
0N/A
0N/A /**
0N/A * Returns the <code>Class</code> type of the <code>Object</code>
0N/A * reference stored within the element. If this element may not
0N/A * contain an <code>Object</code> reference, an
0N/A * <code>IllegalArgumentException</code> will be thrown. If the
0N/A * class type is an array, this field indicates the underlying
0N/A * class type (<i>e.g</i>, for an array of <code>int</code>s, this
0N/A * method would return <code>int.class</code>).
0N/A *
0N/A * <p> <code>Object</code> references whose legal values are
0N/A * defined as a range must implement the <code>Comparable</code>
0N/A * interface.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A *
0N/A * @return a <code>Class</code> object.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if the named element cannot
0N/A * contain an object value (<i>i.e.</i>, if
0N/A * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
0N/A */
0N/A Class<?> getObjectClass(String elementName);
0N/A
0N/A /**
0N/A * Returns an <code>Object</code>s containing the default
0N/A * value for the <code>Object</code> reference within
0N/A * the named element.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A *
0N/A * @return an <code>Object</code>.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if the named element cannot
0N/A * contain an object value (<i>i.e.</i>, if
0N/A * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
0N/A */
0N/A Object getObjectDefaultValue(String elementName);
0N/A
0N/A /**
0N/A * Returns an array of <code>Object</code>s containing the legal
0N/A * enumerated values for the <code>Object</code> reference within
0N/A * the named element. This method should only be called if
0N/A * <code>getObjectValueType</code> returns
0N/A * <code>VALUE_ENUMERATION</code>.
0N/A *
0N/A * <p> The <code>Object</code> associated with a node that accepts
0N/A * emuerated values must be equal to one of the values returned by
0N/A * this method, as defined by the <code>==</code> operator (as
0N/A * opposed to the <code>Object.equals</code> method).
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A *
0N/A * @return an array of <code>Object</code>s.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if the named element cannot
0N/A * contain an object value (<i>i.e.</i>, if
0N/A * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
0N/A * @exception IllegalArgumentException if the <code>Object</code>
0N/A * is not defined as an enumeration.
0N/A */
0N/A Object[] getObjectEnumerations(String elementName);
0N/A
0N/A /**
0N/A * Returns the minimum legal value for the <code>Object</code>
0N/A * reference within the named element. Whether this value is
0N/A * inclusive or exclusive may be determined by the value of
0N/A * <code>getObjectValueType</code>. This method should only be
0N/A * called if <code>getObjectValueType</code> returns one of the
0N/A * constants starting with <code>VALUE_RANGE</code>.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A *
0N/A * @return the smallest legal value for the attribute.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if the named element cannot
0N/A * contain an object value (<i>i.e.</i>, if
0N/A * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
0N/A * @exception IllegalArgumentException if the <code>Object</code>
0N/A * is not defined as a range.
0N/A */
0N/A Comparable<?> getObjectMinValue(String elementName);
0N/A
0N/A /**
0N/A * Returns the maximum legal value for the <code>Object</code>
0N/A * reference within the named element. Whether this value is
0N/A * inclusive or exclusive may be determined by the value of
0N/A * <code>getObjectValueType</code>. This method should only be
0N/A * called if <code>getObjectValueType</code> returns one of the
0N/A * constants starting with <code>VALUE_RANGE</code>.
0N/A *
0N/A * @return the smallest legal value for the attribute.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if the named element cannot
0N/A * contain an object value (<i>i.e.</i>, if
0N/A * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
0N/A * @exception IllegalArgumentException if the <code>Object</code>
0N/A * is not defined as a range.
0N/A */
0N/A Comparable<?> getObjectMaxValue(String elementName);
0N/A
0N/A /**
0N/A * Returns the minimum number of array elements that may be used
0N/A * to define the <code>Object</code> reference within the named
0N/A * element. This method should only be called if
0N/A * <code>getObjectValueType</code> returns
0N/A * <code>VALUE_LIST</code>.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A *
0N/A * @return the smallest valid array length for the
0N/A * <code>Object</code> reference.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if the named element cannot
0N/A * contain an object value (<i>i.e.</i>, if
0N/A * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
0N/A * @exception IllegalArgumentException if the <code>Object</code> is not
0N/A * an array.
0N/A */
0N/A int getObjectArrayMinLength(String elementName);
0N/A
0N/A /**
0N/A * Returns the maximum number of array elements that may be used
0N/A * to define the <code>Object</code> reference within the named
0N/A * element. A value of <code>Integer.MAX_VALUE</code> may be used
0N/A * to specify that there is no upper bound. This method should
0N/A * only be called if <code>getObjectValueType</code> returns
0N/A * <code>VALUE_LIST</code>.
0N/A *
0N/A * @param elementName the name of the element being queried.
0N/A *
0N/A * @return the largest valid array length for the
0N/A * <code>Object</code> reference.
0N/A *
0N/A * @exception IllegalArgumentException if <code>elementName</code>
0N/A * is <code>null</code> or is not a legal element name for this
0N/A * format.
0N/A * @exception IllegalArgumentException if the named element cannot
0N/A * contain an object value (<i>i.e.</i>, if
0N/A * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
0N/A * @exception IllegalArgumentException if the <code>Object</code> is not
0N/A * an array.
0N/A */
0N/A int getObjectArrayMaxLength(String elementName);
0N/A}