/*

 * 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 {@code IIOMetadata.getAsTree} and passed to

 * {@code IIOMetadata.setFromTree} and {@code 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

 * {@code Object} 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()} 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}.

 * <p> In the event that the plugin is provided as part of a named module,

 * that module must export the package containing the implementation class

 * to the <pre>java.desktop</pre> module via a qualified export.

 * An unqualified export is not recommended unless also needed for

 * some other reason. Failing to export the package will result in

 * access failure at runtime.

 *

 * <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}

 * 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}-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_*} constants;

 *

 * <li> The in-memory representation of an elements may contain a

 * reference to an {@code Object}.  There is no provision for

 * representing such objects textually.

 * </ul>

 *

 */

public interface IIOMetadataFormat {

    // Child policies

    /**

     * A constant returned by {@code getChildPolicy} 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 {@code 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 {@code a,b,c,d,...}.

     */

    int CHILD_POLICY_ALL = 1;

    /**

     * A constant returned by {@code 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

     * {@code a?,b?,c?,d?,...}.

     */

    int CHILD_POLICY_SOME = 2;

    /**

     * A constant returned by {@code 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

     * {@code a|b|c|d|...}.

     */

    int CHILD_POLICY_CHOICE = 3;

    /**

     * A constant returned by {@code 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 {@code (a|b|c|d|...)*}.

     */

    int CHILD_POLICY_SEQUENCE = 4;

    /**

     * A constant returned by {@code 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 {@code a*}.

     */

    int CHILD_POLICY_REPEAT = 5;

    /**

     * The largest valid {@code CHILD_POLICY_*} constant,

     * to be used for range checks.

     */

    int CHILD_POLICY_MAX = CHILD_POLICY_REPEAT;

    /**

     * A constant returned by {@code getObjectValueType} to

     * indicate the absence of a user object.

     */

    int VALUE_NONE = 0;

    /**

     * A constant returned by {@code getAttributeValueType} and

     * {@code getObjectValueType} to indicate that the attribute

     * or user object may be set a single, arbitrary value.

     */

    int VALUE_ARBITRARY = 1;

    /**

     * A constant returned by {@code getAttributeValueType} and

     * {@code 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 #VALUE_RANGE_MIN_MAX_INCLUSIVE

     */

    int VALUE_RANGE = 2;

    /**

     * A value that may be or'ed with {@code VALUE_RANGE} to

     * obtain {@code VALUE_RANGE_MIN_INCLUSIVE}, and with

     * {@code VALUE_RANGE_MAX_INCLUSIVE} to obtain

     * {@code VALUE_RANGE_MIN_MAX_INCLUSIVE}.

     *

     * <p> Similarly, the value may be and'ed with the value of

     * {@code getAttributeValueType} or

     * {@code getObjectValueType} 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 {@code VALUE_RANGE} to

     * obtain {@code VALUE_RANGE_MAX_INCLUSIVE}, and with

     * {@code VALUE_RANGE_MIN_INCLUSIVE} to obtain

     * {@code VALUE_RANGE_MIN_MAX_INCLUSIVE}.

     *

     * <p> Similarly, the value may be and'ed with the value of

     * {@code getAttributeValueType} or

     * {@code getObjectValueType} to determine if the maximum

     * value of the range is inclusive.

     */

    int VALUE_RANGE_MAX_INCLUSIVE_MASK = 8;

    /**

     * A constant returned by {@code getAttributeValueType} and

     * {@code 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.

     */

    int VALUE_RANGE_MIN_INCLUSIVE = VALUE_RANGE |

        VALUE_RANGE_MIN_INCLUSIVE_MASK;

    /**

     * A constant returned by {@code getAttributeValueType} and

     * {@code 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.

     */

    int VALUE_RANGE_MAX_INCLUSIVE = VALUE_RANGE |

        VALUE_RANGE_MAX_INCLUSIVE_MASK;

    /**

     * A constant returned by {@code getAttributeValueType} and

     * {@code 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.

     */

    int VALUE_RANGE_MIN_MAX_INCLUSIVE =

        VALUE_RANGE |

        VALUE_RANGE_MIN_INCLUSIVE_MASK |

        VALUE_RANGE_MAX_INCLUSIVE_MASK;

    /**

     * A constant returned by {@code getAttributeValueType} and

     * {@code 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

     * {@code String}s; for objects, they are

     * {@code Object}s implementing a given class or interface.

     *

     * <p> Attribute values of type {@code DATATYPE_BOOLEAN}

     * should be marked as enumerations.

     */

    int VALUE_ENUMERATION = 16;

    /**

     * A constant returned by {@code getAttributeValueType} and

     * {@code 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 {@code String}; for

     * objects, an array will be used.

     */

    int VALUE_LIST = 32;

    /**

     * A constant returned by {@code getAttributeDataType}

     * indicating that the value of an attribute is a general Unicode

     * string.

     */

    int DATATYPE_STRING = 0;

    /**

     * A constant returned by {@code 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.

     */

    int DATATYPE_BOOLEAN = 1;

    /**

     * A constant returned by {@code getAttributeDataType}

     * indicating that the value of an attribute is a string

     * representation of an integer.

     */

    int DATATYPE_INTEGER = 2;

    /**

     * A constant returned by {@code getAttributeDataType}

     * 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 {@code getAttributeDataType}

     * 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.

     *

     * @return a {@code String}.

     */

    String getRootName();

    // Multiplicity

    /**

     * Returns {@code 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 {@code 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.

     *

     * @param elementName the name of the element being queried.

     * @param imageType an {@code ImageTypeSpecifier} indicating

     * the type of the image that will be associated with the

     * metadata.

     *

     * @return {@code true} 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 {@code CHILD_POLICY_REPEAT}.  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}.

     *

     * @exception IllegalArgumentException if {@code elementName}

     * is {@code null} 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}.

     */

    int getElementMinChildren(String elementName);

    /**

     * Returns the maximum number of children of the named element

     * with child policy {@code 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

     * {@code Integer.MAX_VALUE} may be used to specify that

     * there is no upper bound.

     *

     * @param elementName the name of the element being queried.

     *

     * @return an {@code int}.

     *

     * @exception IllegalArgumentException if {@code elementName}

     * is {@code null} 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}.

     */

    int getElementMaxChildren(String elementName);

    /**

     * Returns a {@code String} containing a description of the

     * named element, or {@code null}.  The description will be

     * localized for the supplied {@code Locale} if possible.

     *

     * <p> If {@code locale} is {@code null}, the current

     * default {@code Locale} returned by {@code Locale.getLocale}

     * will be used.

     *

     * @param elementName the name of the element.

     * @param locale the {@code Locale} for which localization

     * will be attempted.

     *

     * @return the element description.

     *

     * @exception IllegalArgumentException if {@code elementName}

     * is {@code null}, or is not a legal element name for this format.

     */

    String getElementDescription(String elementName, Locale locale);

    // Children

    /**

     * Returns one of the constants starting with

     * {@code CHILD_POLICY_}, 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_*} constants.

     *

     * @exception IllegalArgumentException if {@code elementName}

     * is {@code null} or is not a legal element name for this

     * format.

     */

    int getChildPolicy(String elementName);

    /**

     * Returns an array of {@code String}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} is returned.

     *

     * @param elementName the name of the element being queried.

     *

     * @return an array of {@code String}s, or null.

     *

     * @exception IllegalArgumentException if {@code elementName}

     * is {@code null} or is not a legal element name for this

     * format.

     */

    String[] getChildNames(String elementName);

    // Attributes

    /**

     * Returns an array of {@code String}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}s.

     *

     * @exception IllegalArgumentException if {@code elementName}

     * is {@code null} or is not a legal element name for this

     * format.

     */

    String[] getAttributeNames(String elementName);

    /**

     * Returns one of the constants starting with {@code 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.

     *

     * @param elementName the name of the element being queried.

     * @param attrName the name of the attribute being queried.

     *

     * @return one of the {@code VALUE_*} constants.

     *

     * @exception IllegalArgumentException if {@code elementName}

     * is {@code null} or is not a legal element name for this

     * format.

     * @exception IllegalArgumentException if {@code attrName} is

     * {@code null} or is not a legal attribute name for this

     * element.

     */

    int getAttributeValueType(String elementName, String attrName);

    /**

     * Returns one of the constants starting with

     * {@code DATATYPE_}, indicating the format and

     * interpretation of the value of the given attribute within the

     * named element.  If {@code getAttributeValueType} returns

     * {@code VALUE_LIST}, 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_*} constants.

     *

     * @exception IllegalArgumentException if {@code elementName}

     * is {@code null} or is not a legal element name for this

     * format.

     * @exception IllegalArgumentException if {@code attrName} is

     * {@code null} or is not a legal attribute name for this

     * element.

     */

    int getAttributeDataType(String elementName, String attrName);

    /**

     * Returns {@code true} 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} if the attribute must be present.

     *

     * @exception IllegalArgumentException if {@code elementName}

     * is {@code null} or is not a legal element name for this

     * format.

     * @exception IllegalArgumentException if {@code attrName} is

     * {@code null} 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

     * {@code String}, or {@code null} 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} containing the default value, or

     * {@code null}.

     *

     * @exception IllegalArgumentException if {@code elementName}

     * is {@code null} or is not a legal element name for this

     * format.

     * @exception IllegalArgumentException if {@code attrName} is

     * {@code null} or is not a legal attribute name for this

     * element.

     */

    String getAttributeDefaultValue(String elementName, String attrName);

    /**

     * Returns an array of {@code String}s containing the legal

     * enumerated values for the given attribute within the named

     * element.  This method should only be called if

     * {@code getAttributeValueType} returns

     * {@code VALUE_ENUMERATION}.