/*

 * Copyright (c) 2000, 2004, 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.ArrayList;

import java.util.Collection;

import java.util.HashMap;

import java.util.Iterator;

import java.util.List;

import java.util.Locale;

import java.util.Map;

import java.util.MissingResourceException;

import java.util.ResourceBundle;

import javax.imageio.ImageTypeSpecifier;

import com.sun.imageio.plugins.common.StandardMetadataFormat;

/**

 * A concrete class providing a reusable implementation of the

 * <code>IIOMetadataFormat</code> interface.  In addition, a static

 * instance representing the standard, plug-in neutral

 * <code>javax_imageio_1.0</code> format is provided by the

 * <code>getStandardFormatInstance</code> method.

 *

 * <p> In order to supply localized descriptions of elements and

 * attributes, a <code>ResourceBundle</code> with a base name of

 * <code>this.getClass().getName() + "Resources"</code> should be

 * supplied via the usual mechanism used by

 * <code>ResourceBundle.getBundle</code>.  Briefly, the subclasser

 * supplies one or more additional classes according to a naming

 * convention (by default, the fully-qualified name of the subclass

 * extending <code>IIMetadataFormatImpl</code>, plus the string

 * "Resources", plus the country, language, and variant codes

 * separated by underscores).  At run time, calls to

 * <code>getElementDescription</code> or

 * <code>getAttributeDescription</code> will attempt to load such

 * classes dynamically according to the supplied locale, and will use

 * either the element name, or the element name followed by a '/'

 * character followed by the attribute name as a key.  This key will

 * be supplied to the <code>ResourceBundle</code>'s

 * <code>getString</code> method, and the resulting localized

 * description of the node or attribute is returned.

 *

 * <p> The subclass may supply a different base name for the resource

 * bundles using the <code>setResourceBaseName</code> method.

 *

 * <p> A subclass may choose its own localization mechanism, if so

 * desired, by overriding the supplied implementations of

 * <code>getElementDescription</code> and

 * <code>getAttributeDescription</code>.

 *

 * @see ResourceBundle#getBundle(String,Locale)

 *

 */

public abstract class IIOMetadataFormatImpl implements IIOMetadataFormat {

    /**

     * A <code>String</code> constant containing the standard format

     * name, <code>"javax_imageio_1.0"</code>.

     */

    public static final String standardMetadataFormatName =

        "javax_imageio_1.0";

    private static IIOMetadataFormat standardFormat = null;

    private String resourceBaseName = this.getClass().getName() + "Resources";

    private String rootName;

    // Element name (String) -> Element

    private HashMap elementMap = new HashMap();

    class Element {

        String elementName;

        int childPolicy;

        int minChildren = 0;

        int maxChildren = 0;

        // Child names (Strings)

        List childList = new ArrayList();

        // Parent names (Strings)

        List parentList = new ArrayList();

        // List of attribute names in the order they were added

        List attrList = new ArrayList();

        // Attr name (String) -> Attribute

        Map attrMap = new HashMap();

        ObjectValue objectValue;

    }

    class Attribute {

        String attrName;

        int valueType = VALUE_ARBITRARY;

        int dataType;

        boolean required;

        String defaultValue = null;

        // enumeration

        List enumeratedValues;

        // range

        String minValue;

        String maxValue;

        // list

        int listMinLength;

        int listMaxLength;

    }

    class ObjectValue {

        int valueType = VALUE_NONE;

        Class classType = null;

        Object defaultValue = null;

        // Meaningful only if valueType == VALUE_ENUMERATION

        List enumeratedValues = null;

        // Meaningful only if valueType == VALUE_RANGE

        Comparable minValue = null;

        Comparable maxValue = null;

        // Meaningful only if valueType == VALUE_LIST

        int arrayMinLength = 0;

        int arrayMaxLength = 0;

    }

    /**

     * Constructs a blank <code>IIOMetadataFormatImpl</code> instance,

     * with a given root element name and child policy (other than

     * <code>CHILD_POLICY_REPEAT</code>).  Additional elements, and

     * their attributes and <code>Object</code> reference information

     * may be added using the various <code>add</code> methods.

     *

     * @param rootName the name of the root element.

     * @param childPolicy one of the <code>CHILD_POLICY_*</code> constants,

     * other than <code>CHILD_POLICY_REPEAT</code>.

     *

     * @exception IllegalArgumentException if <code>rootName</code> is

     * <code>null</code>.

     * @exception IllegalArgumentException if <code>childPolicy</code> is

     * not one of the predefined constants.

     */

    public IIOMetadataFormatImpl(String rootName,

                                 int childPolicy) {

        if (rootName == null) {

            throw new IllegalArgumentException("rootName == null!");

        }

        if (childPolicy < CHILD_POLICY_EMPTY ||

            childPolicy > CHILD_POLICY_MAX ||

            childPolicy == CHILD_POLICY_REPEAT) {

            throw new IllegalArgumentException("Invalid value for childPolicy!");

        }

        this.rootName = rootName;

        Element root = new Element();

        root.elementName = rootName;

        root.childPolicy = childPolicy;

        elementMap.put(rootName, root);

    }

    /**

     * Constructs a blank <code>IIOMetadataFormatImpl</code> instance,

     * with a given root element name and a child policy of

     * <code>CHILD_POLICY_REPEAT</code>.  Additional elements, and

     * their attributes and <code>Object</code> reference information

     * may be added using the various <code>add</code> methods.

     *

     * @param rootName the name of the root element.

     * @param minChildren the minimum number of children of the node.

     * @param maxChildren the maximum number of children of the node.

     *

     * @exception IllegalArgumentException if <code>rootName</code> is

     * <code>null</code>.

     * @exception IllegalArgumentException if <code>minChildren</code>

     * is negative or larger than <code>maxChildren</code>.

     */

    public IIOMetadataFormatImpl(String rootName,

                                 int minChildren,

                                 int maxChildren) {

        if (rootName == null) {

            throw new IllegalArgumentException("rootName == null!");

        }

        if (minChildren < 0) {

            throw new IllegalArgumentException("minChildren < 0!");

        }

        if (minChildren > maxChildren) {

            throw new IllegalArgumentException("minChildren > maxChildren!");

        }

        Element root = new Element();

        root.elementName = rootName;

        root.childPolicy = CHILD_POLICY_REPEAT;

        root.minChildren = minChildren;

        root.maxChildren = maxChildren;

        this.rootName = rootName;

        elementMap.put(rootName, root);

    }

    /**

     * Sets a new base name for locating <code>ResourceBundle</code>s

     * containing descriptions of elements and attributes for this

     * format.

     *

     * <p> Prior to the first time this method is called, the base

     * name will be equal to <code>this.getClass().getName() +

     * "Resources"</code>.

     *

     * base name.

     *

     * @exception IllegalArgumentException if

     * <code>resourceBaseName</code> is <code>null</code>.

     *

     * @see #getResourceBaseName

     */

    protected void setResourceBaseName(String resourceBaseName) {

        if (resourceBaseName == null) {

            throw new IllegalArgumentException("resourceBaseName == null!");

        }

        this.resourceBaseName = resourceBaseName;

    }

    /**

     * Returns the currently set base name for locating

     * <code>ResourceBundle</code>s.

     *

     * @return a <code>String</code> containing the base name.

     *

     * @see #setResourceBaseName

     */

    protected String getResourceBaseName() {

        return resourceBaseName;

    }

    /**

     * Utility method for locating an element.

     *

     * @param mustAppear if <code>true</code>, throw an

     * <code>IllegalArgumentException</code> if no such node exists;

     * if <code>false</code>, just return null.

     */

    private Element getElement(String elementName, boolean mustAppear) {

        if (mustAppear && (elementName == null)) {

            throw new IllegalArgumentException("element name is null!");

        }

        Element element = (Element)elementMap.get(elementName);

        if (mustAppear && (element == null)) {

            throw new IllegalArgumentException("No such element: " +

                                               elementName);

        }

        return element;

    }

    private Element getElement(String elementName) {

        return getElement(elementName, true);

    }

    // Utility method for locating an attribute

    private Attribute getAttribute(String elementName, String attrName) {

        Element element = getElement(elementName);

        Attribute attr = (Attribute)element.attrMap.get(attrName);

        if (attr == null) {

            throw new IllegalArgumentException("No such attribute \"" +

                                               attrName + "\"!");

        }

        return attr;

    }

    // Setup

    /**

     * Adds a new element type to this metadata document format with a

     * child policy other than <code>CHILD_POLICY_REPEAT</code>.

     *

     * @param elementName the name of the new element.

     * @param parentName the name of the element that will be the

     * parent of the new element.

     * @param childPolicy one of the <code>CHILD_POLICY_*</code>

     * constants, other than <code>CHILD_POLICY_REPEAT</code>,

     * indicating the child policy of the new element.

     *

     * @exception IllegalArgumentException if <code>parentName</code>

     * is <code>null</code>, or is not a legal element name for this

     * format.

     * @exception IllegalArgumentException if <code>childPolicy</code>

     * is not one of the predefined constants.

     */

    protected void addElement(String elementName,

                              String parentName,

                              int childPolicy) {

        Element parent = getElement(parentName);

        if (childPolicy < CHILD_POLICY_EMPTY ||

            childPolicy > CHILD_POLICY_MAX ||

            childPolicy == CHILD_POLICY_REPEAT) {

            throw new IllegalArgumentException

                ("Invalid value for childPolicy!");

        }

        Element element = new Element();

        element.elementName = elementName;

        element.childPolicy = childPolicy;

        parent.childList.add(elementName);

        element.parentList.add(parentName);

        elementMap.put(elementName, element);

    }

    /**

     * Adds a new element type to this metadata document format with a

     * child policy of <code>CHILD_POLICY_REPEAT</code>.

     *

     * @param elementName the name of the new element.

     * @param parentName the name of the element that will be the

     * parent of the new element.

     * @param minChildren the minimum number of children of the node.

     * @param maxChildren the maximum number of children of the node.

     *

     * @exception IllegalArgumentException if <code>parentName</code>

     * is <code>null</code>, or is not a legal element name for this

     * format.

     * @exception IllegalArgumentException if <code>minChildren</code>

     * is negative or larger than <code>maxChildren</code>.

     */

    protected void addElement(String elementName,

                              String parentName,

                              int minChildren,

                              int maxChildren) {

        Element parent = getElement(parentName);

        if (minChildren < 0) {

            throw new IllegalArgumentException("minChildren < 0!");

        }

        if (minChildren > maxChildren) {

            throw new IllegalArgumentException("minChildren > maxChildren!");

        }

        Element element = new Element();

        element.elementName = elementName;

        element.childPolicy = CHILD_POLICY_REPEAT;

        element.minChildren = minChildren;

        element.maxChildren = maxChildren;

        parent.childList.add(elementName);

        element.parentList.add(parentName);

        elementMap.put(elementName, element);

    }

    /**

     * Adds an existing element to the list of legal children for a

     * given parent node type.

     *

     * @param parentName the name of the element that will be the

     * new parent of the element.

     * child.

     *

     * @exception IllegalArgumentException if <code>elementName</code>

     * is <code>null</code>, or is not a legal element name for this

     * format.

     * @exception IllegalArgumentException if <code>parentName</code>

     * is <code>null</code>, or is not a legal element name for this

     * format.

     */

    protected void addChildElement(String elementName, String parentName) {

        Element parent = getElement(parentName);

        Element element = getElement(elementName);

        parent.childList.add(elementName);

        element.parentList.add(parentName);

    }

    /**

     * Removes an element from the format.  If no element with the

     * given name was present, nothing happens and no exception is

     * thrown.

     *

     * @param elementName the name of the element to be removed.

     */

    protected void removeElement(String elementName) {

        Element element = getElement(elementName, false);

        if (element != null) {

            Iterator iter = element.parentList.iterator();

            while (iter.hasNext()) {

                String parentName = (String)iter.next();

                Element parent = getElement(parentName, false);

                if (parent != null) {

                    parent.childList.remove(elementName);

                }

            }

            elementMap.remove(elementName);

        }

    }

    /**

     * Adds a new attribute to a previously defined element that may

     * be set to an arbitrary value.

     *

     * @param elementName the name of the element.

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

     * @param dataType the data type (string format) of the attribute,

     * one of the <code>DATATYPE_*</code> constants.

     * @param required <code>true</code> if the attribute must be present.

     * @param defaultValue the default value for the attribute, 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>.

     * @exception IllegalArgumentException if <code>dataType</code> is

     * not one of the predefined constants.

     */

    protected void addAttribute(String elementName,

                                String attrName,

                                int dataType,

                                boolean required,

                                String defaultValue) {

        Element element = getElement(elementName);

        if (attrName == null) {

            throw new IllegalArgumentException("attrName == null!");

        }

        if (dataType < DATATYPE_STRING || dataType > DATATYPE_DOUBLE) {

            throw new IllegalArgumentException("Invalid value for dataType!");

        }

        Attribute attr = new Attribute();

        attr.attrName = attrName;

        attr.valueType = VALUE_ARBITRARY;

        attr.dataType = dataType;

        attr.required = required;

        attr.defaultValue = defaultValue;

        element.attrList.add(attrName);

        element.attrMap.put(attrName, attr);

    }

    /**

     * Adds a new attribute to a previously defined element that will

     * be defined by a set of enumerated values.

     *

     * @param elementName the name of the element.

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

     * @param dataType the data type (string format) of the attribute,

     * one of the <code>DATATYPE_*</code> constants.

     * @param required <code>true</code> if the attribute must be present.

     * @param defaultValue the default value for the attribute, or

     * <code>null</code>.

     * @param enumeratedValues a <code>List</code> of

     * <code>String</code>s containing the legal values 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>.

     * @exception IllegalArgumentException if <code>dataType</code> is

     * not one of the predefined constants.

     * @exception IllegalArgumentException if

     * <code>enumeratedValues</code> is <code>null</code>.

     * @exception IllegalArgumentException if

     * <code>enumeratedValues</code> does not contain at least one

     * entry.

     * @exception IllegalArgumentException if

     * <code>enumeratedValues</code> contains an element that is not a

     * <code>String</code> or is <code>null</code>.

     */

    protected void addAttribute(String elementName,

                                String attrName,

                                int dataType,

                                boolean required,

                                String defaultValue,

                                List<String> enumeratedValues) {

        Element element = getElement(elementName);

        if (attrName == null) {

            throw new IllegalArgumentException("attrName == null!");

        }

        if (dataType < DATATYPE_STRING || dataType > DATATYPE_DOUBLE) {

            throw new IllegalArgumentException("Invalid value for dataType!");

        }

        if (enumeratedValues == null) {

            throw new IllegalArgumentException("enumeratedValues == null!");

        }

        if (enumeratedValues.size() == 0) {

            throw new IllegalArgumentException("enumeratedValues is empty!");

        }

        Iterator iter = enumeratedValues.iterator();

        while (iter.hasNext()) {

            Object o = iter.next();

            if (o == null) {

                throw new IllegalArgumentException

                    ("enumeratedValues contains a null!");

            }

            if (!(o instanceof String)) {

                throw new IllegalArgumentException

                    ("enumeratedValues contains a non-String value!");

            }