awt/javax/imageio/metadata/IIOMetadata.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 java.util.ArrayList;

import org.apache.harmony.x.imageio.metadata.IIOMetadataUtils;
import org.w3c.dom.Node;

/**
 * The Class IIOMetadata represents the metadata (bundled with an image)
 * as a Dom-type tree.
 */
public abstract class IIOMetadata {

    /** Whether the standard metadata format is supported. */
    protected boolean standardFormatSupported;
    
    /** The native metadata format name. */
    protected String nativeMetadataFormatName;
    
    /** The native metadata format class name. */
    protected String nativeMetadataFormatClassName;
    
    /** The extra metadata format names. */
    protected String[] extraMetadataFormatNames;
    
    /** The extra metadata format class names. */
    protected String[] extraMetadataFormatClassNames;
    
    /** The default controller. */
    protected IIOMetadataController defaultController;
    
    /** The controller. */
    protected IIOMetadataController controller;

    /**
     * Instantiates a new IIOMetadata with no data set.
     */
    protected IIOMetadata() {}

    /**
     * Instantiates a new IIOMetadata with the specified data parameters.
     * 
     * @param standardMetadataFormatSupported whether the standard metadata format is supported
     * @param nativeMetadataFormatName the native metadata format name
     * @param nativeMetadataFormatClassName the native metadata format class name
     * @param extraMetadataFormatNames the extra metadata format names
     * @param extraMetadataFormatClassNames the extra metadata format class names
     */
    protected IIOMetadata(boolean standardMetadataFormatSupported,
                          String nativeMetadataFormatName,
                          String nativeMetadataFormatClassName,
                          String[] extraMetadataFormatNames,
                          String[] extraMetadataFormatClassNames) {
        standardFormatSupported = standardMetadataFormatSupported;
        this.nativeMetadataFormatName = nativeMetadataFormatName;
        this.nativeMetadataFormatClassName = nativeMetadataFormatClassName;
        if (extraMetadataFormatNames == null) {
            if (extraMetadataFormatClassNames != null) {
                throw new IllegalArgumentException(
                        "extraMetadataFormatNames == null && extraMetadataFormatClassNames != null!"
                );
            }
        } else {
            if (extraMetadataFormatClassNames == null) {
                throw new IllegalArgumentException(
                        "extraMetadataFormatNames != null && extraMetadataFormatClassNames == null!"
                );
            }
            if (extraMetadataFormatNames.length == 0) {
                throw new IllegalArgumentException("extraMetadataFormatNames.length == 0!");
            }
            if (extraMetadataFormatClassNames.length != extraMetadataFormatNames.length) {
                throw new IllegalArgumentException(
                        "extraMetadataFormatClassNames.length != extraMetadataFormatNames.length!"
                );
            }
            this.extraMetadataFormatNames = extraMetadataFormatNames.clone();
            this.extraMetadataFormatClassNames = extraMetadataFormatClassNames.clone();
        }
    }

    /**
     * Gets the metadata as tree-type document.
     * 
     * @param formatName the format name
     * 
     * @return the node in tree format
     */
    public abstract Node getAsTree(String formatName);
    
    /**
     * Checks if the metadata is read only.
     * 
     * @return true, if the metadata is read only.
     */
    public abstract boolean isReadOnly();
    
    /**
     * Merges the specified tree with this metadata tree.
     * 
     * @param formatName the format of the specified tree
     * @param root the root node of the metadata tree
     * 
     * @throws IIOInvalidTreeException if the specified tree
     * is incompatible with the this metadata tree.
     */
    public abstract void mergeTree(String formatName, Node root) throws IIOInvalidTreeException;
    
    /**
     * Resets the controller.
     */
    public abstract void reset();

    /**
     * Gets the controller associated with this metadata document.
     * 
     * @return the controller
     */
    public IIOMetadataController getController() {
        return controller;
    }

    /**
     * Checks whether this metadata has a controller.
     * 
     * @return true, if this metadata has a controller
     */
    public boolean hasController() {
        return getController() != null;
    }

    /**
     * Activate the controller.
     * 
     * @return true, if successful
     */
    public boolean activateController() {
        if (!hasController()) {
            throw new IllegalStateException("hasController() == false!");
        }
        return getController().activate(this);
    }

    /**
     * Gets the default controller.
     * 
     * @return the default controller
     */
    public IIOMetadataController getDefaultController() {
        return defaultController;
    }

    /**
     * Gets the extra metadata format names.
     * 
     * @return the extra metadata format names
     */
    public String[] getExtraMetadataFormatNames() {
        return extraMetadataFormatNames == null ? null : extraMetadataFormatNames.clone();
    }

    /**
     * Gets the metadata format.
     * 
     * @param formatName the format name
     * 
     * @return the metadata format
     */
    public IIOMetadataFormat getMetadataFormat(String formatName) {
        return IIOMetadataUtils.instantiateMetadataFormat(
                formatName,
                standardFormatSupported,
                nativeMetadataFormatName, nativeMetadataFormatClassName,
                extraMetadataFormatNames, extraMetadataFormatClassNames
        );
    }

    /**
     * Gets the native metadata format name.
     * 
     * @return the native metadata format name
     */
    public String getNativeMetadataFormatName() {
        return nativeMetadataFormatName;
    }

    /**
     * Checks if the standard metadata format is supported.
     * 
     * @return true, if the standard metadata format is supported
     */
    public boolean isStandardMetadataFormatSupported() {
        return standardFormatSupported;
    }

    /**
     * Gets the metadata format names.
     * 
     * @return the metadata format names
     */
    public String[] getMetadataFormatNames() {
        ArrayList<String> res = new ArrayList<String>();

        String nativeMetadataFormatName = getNativeMetadataFormatName();
        boolean standardFormatSupported = isStandardMetadataFormatSupported();
        String extraMetadataFormatNames[] = getExtraMetadataFormatNames();

        if (standardFormatSupported) {
            res.add(IIOMetadataFormatImpl.standardMetadataFormatName);
        }
        if (nativeMetadataFormatName != null) {
            res.add(nativeMetadataFormatName);
        }
        if (extraMetadataFormatNames != null) {
            for (String extraMetadataFormatName : extraMetadataFormatNames) {
                res.add(extraMetadataFormatName);
            }
        }

        return res.size() > 0 ? res.toArray(new String[0]) : null;
    }

    /**
     * Gets the standard chroma node.
     * 
     * @return the standard chroma node
     */
    protected IIOMetadataNode getStandardChromaNode() {
        return null;
    }

    /**
     * Gets the standard compression node.
     * 
     * @return the standard compression node
     */
    protected IIOMetadataNode getStandardCompressionNode() {
        return null;
    }

    /**
     * Gets the standard data node.
     * 
     * @return the standard data node
     */
    protected IIOMetadataNode getStandardDataNode() {
        return null;
    }

    /**
     * Gets the standard dimension node.
     * 
     * @return the standard dimension node
     */
    protected IIOMetadataNode getStandardDimensionNode() {
        return null;
    }

    /**
     * Gets the standard document node.
     * 
     * @return the standard document node
     */
    protected IIOMetadataNode getStandardDocumentNode() {
        return null;
    }

    /**
     * Gets the standard text node.
     * 
     * @return the standard text node
     */
    protected IIOMetadataNode getStandardTextNode() {
        return null;
    }

    /**
     * Gets the standard tile node.
     * 
     * @return the standard tile node
     */
    protected IIOMetadataNode getStandardTileNode() {
        return null;
    }

    /**
     * Gets the standard transparency node.
     * 
     * @return the standard transparency node
     */
    protected IIOMetadataNode getStandardTransparencyNode() {
        return null;
    }

    /**
     * Gets the metadata as a tree in standard format.
     * 
     * @return the metadata as a tree in standard format
     */
    protected final IIOMetadataNode getStandardTree() {
        // Create root node
        IIOMetadataNode root = new IIOMetadataNode(IIOMetadataFormatImpl.standardMetadataFormatName);

        Node node;
        if ((node = getStandardChromaNode()) != null) {
            root.appendChild(node);
        }
        if ((node = getStandardCompressionNode()) != null) {
            root.appendChild(node);
        }
        if ((node = getStandardDataNode()) != null) {
            root.appendChild(node);
        }
        if ((node = getStandardDimensionNode()) != null) {
            root.appendChild(node);
        }
        if ((node = getStandardDocumentNode()) != null) {
            root.appendChild(node);
        }
        if ((node = getStandardTextNode()) != null) {
            root.appendChild(node);
        }
        if ((node = getStandardTileNode()) != null) {
            root.appendChild(node);
        }
        if ((node = getStandardTransparencyNode()) != null) {
            root.appendChild(node);
        }
        
        return root;
    }

    /**
     * Sets the controller.
     * 
     * @param controller the new controller
     */
    public void setController(IIOMetadataController controller) {
        this.controller = controller;
    }

    /**
     * Sets the from tree.
     * 
     * @param formatName the name of the metatdata format of the from tree
     * @param root the root node of the from tree
     * 
     * @throws IIOInvalidTreeException if the tree or its format is not compatible with 
     * this metadata.
     */
    public void setFromTree(String formatName, Node root) throws IIOInvalidTreeException {
        reset();
        mergeTree(formatName, root);
    }
}