path: root/awt/javax/imageio/metadata/IIOMetadataFormat.java

/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package javax.imageio.metadata;

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

/**
 * The Interface IIOMetadataFormat is implemented by classes that 
 * describe the rules and allowed elements for a metadata document
 * tree.
 */
public interface IIOMetadataFormat {

    /** The CHILD_POLICY_EMPTY. */
    int CHILD_POLICY_EMPTY = 0;
    
    /** The CHILD_POLICY_ALL. */
    int CHILD_POLICY_ALL = 1;
    
    /** The CHILD_POLICY_SOME. */
    int CHILD_POLICY_SOME = 2;
    
    /** The CHILD_POLICY_CHOICE. */
    int CHILD_POLICY_CHOICE = 3;
    
    /** The CHILD_POLICY_SEQUENCE. */
    int CHILD_POLICY_SEQUENCE = 4;
    
    /** The CHILD_POLICY_REPEAT. */
    int CHILD_POLICY_REPEAT = 5;
    
    /** The maximum value for the child policy. */
    int CHILD_POLICY_MAX = CHILD_POLICY_REPEAT;

    /** The DATATYPE_STRING. */
    int DATATYPE_STRING = 0;
    
    /** The DATATYPE_BOOLEAN. */
    int DATATYPE_BOOLEAN = 1;
    
    /** The DATATYPE_INTEGER. */
    int DATATYPE_INTEGER = 2;
    
    /** The DATATYPE_FLOAT. */
    int DATATYPE_FLOAT = 3;
    
    /** The DATATYPE_DOUBLE. */
    int DATATYPE_DOUBLE = 4;

    /** The VALUE_NONE. */
    int VALUE_NONE = 0;
    
    /** The VALUE_ARBITRARY. */
    int VALUE_ARBITRARY = 1;
    
    /** The VALUE_RANGE. */
    int VALUE_RANGE = 2;
    
    /** The VALUE_RANGE_MIN_INCLUSIVE_MASK. */
    int VALUE_RANGE_MIN_INCLUSIVE_MASK = 4;
    
    /** The VALUE_RANGE_MAX_INCLUSIVE_MASK. */
    int VALUE_RANGE_MAX_INCLUSIVE_MASK = 8;
    
    /** The VALUE_ENUMERATION. */
    int VALUE_ENUMERATION = 16;
    
    /** The VALUE_LIST. */
    int VALUE_LIST = 32;
    
    /** The VALUE_RANGE_MIN_INCLUSIVE. */
    int VALUE_RANGE_MIN_INCLUSIVE = VALUE_RANGE | VALUE_RANGE_MIN_INCLUSIVE_MASK;
    
    /** The VALUE_RANGE_MAX_INCLUSIVE. */
    int VALUE_RANGE_MAX_INCLUSIVE = VALUE_RANGE | VALUE_RANGE_MAX_INCLUSIVE_MASK;
    
    /** The VALUE_RANGE_MIN_MAX_INCLUSIVE. */
    int VALUE_RANGE_MIN_MAX_INCLUSIVE =
            VALUE_RANGE | VALUE_RANGE_MIN_INCLUSIVE_MASK | VALUE_RANGE_MAX_INCLUSIVE_MASK;

    /**
     * Tells whether the specified element is allowed for the specified 
     * image type.
     * 
     * @param elementName the element name
     * @param imageType the image type
     * 
     * @return true, if the specified element is allowed for the specified 
     * image type
     */
    boolean canNodeAppear(String elementName, ImageTypeSpecifier imageType);

    /**
     * Gets data type of the specified attribute of the specified element.
     * 
     * @param elementName the element name
     * @param attrName the attribute name
     * 
     * @return the attribute's data type
     */
    int getAttributeDataType(String elementName, String attrName);
    
    /**
     * Gets the default value of the specified attribute of the specified element.
     * 
     * @param elementName the element name
     * @param attrName the attribute name
     * 
     * @return the attribute's default value
     */
    String getAttributeDefaultValue(String elementName, String attrName);
    
    /**
     * Gets the user-friendly description of the attribute.
     * 
     * @param elementName the element name
     * @param attrName the attribute name
     * @param locale the locale giving the desired language for the
     * description
     * 
     * @return the attribute description
     */
    String getAttributeDescription(String elementName, String attrName, Locale locale);
    
    /**
     * Gets the attribute enumerations.
     * 
     * @param elementName the element name
     * @param attrName the attribute name
     * 
     * @return the attribute enumerations
     */
    String[] getAttributeEnumerations(String elementName, String attrName);
    
    /**
     * Gets the maximum length of the attribute list.
     * 
     * @param elementName the element name
     * @param attrName the attribute name
     * 
     * @return the maximum length of the attribute list
     */
    int getAttributeListMaxLength(String elementName, String attrName);
    
    /**
     * Gets the minimum length of the attribute list.
     * 
     * @param elementName the element name
     * @param attrName the attribute name
     * 
     * @return the minimum length of the attribute list
     */
    int getAttributeListMinLength(String elementName, String attrName);
    
    /**
     * Gets the maximum value allowed for the attribute.
     * 
     * @param elementName the element name
     * @param attrName the attribute name
     * 
     * @return the maximum value allowed for the attribute
     */
    String getAttributeMaxValue(String elementName, String attrName);
    
    /**
     * Gets the minimum value allowed for the attribute.
     * 
     * @param elementName the element name
     * @param attrName the attribute name
     * 
     * @return the minimum value allowed for the attribute
     */
    String getAttributeMinValue(String elementName, String attrName);
    
    /**
     * Gets the attribute names allowed for the specified element.
     * 
     * @param elementName the element name
     * 
     * @return the attribute names
     */
    String[] getAttributeNames(String elementName);
    
    /**
     * Gets the attribute value type.
     * 
     * @param elementName the element name
     * @param attrName the attribute name
     * 
     * @return the attribute value type
     */
    int getAttributeValueType(String elementName, String attrName);
    
    /**
     * Checks whether the specified attribute is required 
     * for the specified element.
     * 
     * @param elementName the element name
     * @param attrName the attribute name
     * 
     * @return true, if the specified attribute is required for the 
     * specified element
     */
    boolean isAttributeRequired(String elementName, String attrName);

    /**
     * Gets the names of the possible child elements for the given element.
     * 
     * @param elementName the element name
     * 
     * @return the child names
     */
    String[] getChildNames(String elementName);
    
    /**
     * Gets the constant describing the element's child policy.
     * 
     * @param elementName the element name
     * 
     * @return the child policy
     */
    int getChildPolicy(String elementName);

    /**
     * Gets the user-friendly description of the element.
     * 
     * @param elementName the element name
     * @param locale the locale giving the desired language for the
     * description
     * 
     * @return the element description
     */
    String getElementDescription(String elementName, Locale locale);
    
    /**
     * Gets the maximum number of children allowed for the element.
     * 
     * @param elementName the element name
     * 
     * @return the maximum number of children allowed for the element
     */
    int getElementMaxChildren(String elementName);
    
    /**
     * Gets the minimum number of children allowed for the element.
     * 
     * @param elementName the element name
     * 
     * @return the minimum number of children allowed for the element
     */
    int getElementMinChildren(String elementName);

    /**
     * Gets the maximum object array length allowed for the element.
     * 
     * @param elementName the element name
     * 
     * @return the maximum object array length allowed for the element
     */
    int getObjectArrayMaxLength(String elementName);
    
    /**
     * Gets the minimum object array length allowed for the element.
     * 
     * @param elementName the element name
     * 
     * @return the minimum object array length allowed for the element
     */
    int getObjectArrayMinLength(String elementName);
    
    /**
     * Gets the object class corresponding to the specified element.
     * 
     * @param elementName the element name
     * 
     * @return the object class corresponding to the specified element
     */
    Class<?> getObjectClass(String elementName);
    
    /**
     * Gets the object default value for the element.
     * 
     * @param elementName the element name
     * 
     * @return the object default value for the element
     */
    Object getObjectDefaultValue(String elementName);
    
    /**
     * Gets the object enumerations.
     * 
     * @param elementName the element name
     * 
     * @return the object enumerations
     */
    Object[] getObjectEnumerations(String elementName);
    
    /**
     * Gets the maximum value allowed for the element's object.
     * 
     * @param elementName the element name
     * 
     * @return the maximum value allowed for the element's object
     */
    Comparable<?> getObjectMaxValue(String elementName);
    
    /**
     * Gets the minimum value allowed for the element's object.
     * 
     * @param elementName the element name
     * 
     * @return the minimum value allowed for the element's object
     */
    Comparable<?> getObjectMinValue(String elementName);
    
    /**
     * Gets the constant that indicates the type of the element's value.
     * 
     * @param elementName the element name
     * 
     * @return the constant that indicates the type of the element's value
     */
    int getObjectValueType(String elementName);

    /**
     * Gets the name of the root element.
     * 
     * @return the name of the root element
     */
    String getRootName();
}