imageio/metadata/IIOMetadata.java

/*
 * Copyright (c) 2000, 2014, 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 org.w3c.dom.Node;

import java.lang.reflect.Method;
import java.security.AccessController;
import java.security.PrivilegedAction;

/**
 * An abstract class to be extended by objects that represent metadata
 * (non-image data) associated with images and streams.  Plug-ins
 * represent metadata using opaque, plug-in specific objects.  These
 * objects, however, provide the ability to access their internal
 * information as a tree of {@code IIOMetadataNode} objects that
 * support the XML DOM interfaces as well as additional interfaces for
 * storing non-textual data and retrieving information about legal
 * data values.  The format of such trees is plug-in dependent, but
 * plug-ins may choose to support a plug-in neutral format described
 * below.  A single plug-in may support multiple metadata formats,
 * whose names maybe determined by calling
 * {@code getMetadataFormatNames}.  The plug-in may also support
 * a single special format, referred to as the "native" format, which
 * is designed to encode its metadata losslessly.  This format will
 * typically be designed specifically to work with a specific file
 * format, so that images may be loaded and saved in the same format
 * with no loss of metadata, but may be less useful for transferring
 * metadata between an {@code ImageReader} and an
 * {@code ImageWriter} for different image formats.  To convert
 * between two native formats as losslessly as the image file formats
 * will allow, an {@code ImageTranscoder} object must be used.
 *
 * @see javax.imageio.ImageReader#getImageMetadata
 * @see javax.imageio.ImageReader#getStreamMetadata
 * @see javax.imageio.ImageReader#readAll
 * @see javax.imageio.ImageWriter#getDefaultStreamMetadata
 * @see javax.imageio.ImageWriter#getDefaultImageMetadata
 * @see javax.imageio.ImageWriter#write
 * @see javax.imageio.ImageWriter#convertImageMetadata
 * @see javax.imageio.ImageWriter#convertStreamMetadata
 * @see javax.imageio.IIOImage
 * @see javax.imageio.ImageTranscoder
 *
 */
public abstract class IIOMetadata {

    /**
     * A boolean indicating whether the concrete subclass supports the
     * standard metadata format, set via the constructor.
     */
    protected boolean standardFormatSupported;

    /**
     * The name of the native metadata format for this object,
     * initialized to {@code null} and set via the constructor.
     */
    protected String nativeMetadataFormatName = null;

    /**
     * The name of the class implementing {@code IIOMetadataFormat}
     * and representing the native metadata format, initialized to
     * {@code null} and set via the constructor.
     */
    protected String nativeMetadataFormatClassName = null;

    /**
     * An array of names of formats, other than the standard and
     * native formats, that are supported by this plug-in,
     * initialized to {@code null} and set via the constructor.
     */
    protected String[] extraMetadataFormatNames = null;

    /**
     * An array of names of classes implementing {@code IIOMetadataFormat}
     * and representing the metadata formats, other than the standard and
     * native formats, that are supported by this plug-in,
     * initialized to {@code null} and set via the constructor.
     */
    protected String[] extraMetadataFormatClassNames = null;

    /**
     * An {@code IIOMetadataController} that is suggested for use
     * as the controller for this {@code IIOMetadata} object.  It
     * may be retrieved via {@code getDefaultController}.  To
     * install the default controller, call
     * {@code setController(getDefaultController())}.  This
     * instance variable should be set by subclasses that choose to
     * provide their own default controller, usually a GUI, for
     * setting parameters.
     *
     * @see IIOMetadataController
     * @see #getDefaultController
     */
    protected IIOMetadataController defaultController = null;

    /**
     * The {@code IIOMetadataController} that will be
     * used to provide settings for this {@code IIOMetadata}
     * object when the {@code activateController} method
     * is called.  This value overrides any default controller,
     * even when {@code null}.
     *
     * @see IIOMetadataController
     * @see #setController(IIOMetadataController)
     * @see #hasController()
     * @see #activateController()
     */
    protected IIOMetadataController controller = null;

    /**
     * Constructs an empty {@code IIOMetadata} object.  The
     * subclass is responsible for supplying values for all protected
     * instance variables that will allow any non-overridden default
     * implementations of methods to satisfy their contracts.  For example,
     * {@code extraMetadataFormatNames} should not have length 0.
     */
    protected IIOMetadata() {}

    /**
     * Constructs an {@code IIOMetadata} object with the given
     * format names and format class names, as well as a boolean
     * indicating whether the standard format is supported.
     *
     * <p> This constructor does not attempt to check the class names
     * for validity.  Invalid class names may cause exceptions in
     * subsequent calls to {@code getMetadataFormat}.
     *
     * @param standardMetadataFormatSupported {@code true} if
     * this object can return or accept a DOM tree using the standard
     * metadata format.
     * @param nativeMetadataFormatName the name of the native metadata
     * format, as a {@code String}, or {@code null} if there
     * is no native format.
     * @param nativeMetadataFormatClassName the name of the class of
     * the native metadata format, or {@code null} if there is
     * no native format.
     * @param extraMetadataFormatNames an array of {@code String}s
     * indicating additional formats supported by this object, or
     * {@code null} if there are none.
     * @param extraMetadataFormatClassNames an array of {@code String}s
     * indicating the class names of any additional formats supported by
     * this object, or {@code null} if there are none.
     *
     * @exception IllegalArgumentException if
     * {@code extraMetadataFormatNames} has length 0.
     * @exception IllegalArgumentException if
     * {@code extraMetadataFormatNames} and
     * {@code extraMetadataFormatClassNames} are neither both
     * {@code null}, nor of the same length.
     */
    protected IIOMetadata(boolean standardMetadataFormatSupported,
                          String nativeMetadataFormatName,
                          String nativeMetadataFormatClassName,
                          String[] extraMetadataFormatNames,
                          String[] extraMetadataFormatClassNames) {
        this.standardFormatSupported = standardMetadataFormatSupported;
        this.nativeMetadataFormatName = nativeMetadataFormatName;
        this.nativeMetadataFormatClassName = nativeMetadataFormatClassName;
        if (extraMetadataFormatNames != null) {
            if (extraMetadataFormatNames.length == 0) {
                throw new IllegalArgumentException
                    ("extraMetadataFormatNames.length == 0!");
            }
            if (extraMetadataFormatClassNames == null) {
                throw new IllegalArgumentException
                    ("extraMetadataFormatNames != null && extraMetadataFormatClassNames == null!");
            }
            if (extraMetadataFormatClassNames.length !=
                extraMetadataFormatNames.length) {
                throw new IllegalArgumentException
                    ("extraMetadataFormatClassNames.length != extraMetadataFormatNames.length!");
            }
            this.extraMetadataFormatNames = extraMetadataFormatNames.clone();
            this.extraMetadataFormatClassNames = extraMetadataFormatClassNames.clone();
        } else {
            if (extraMetadataFormatClassNames != null) {
                throw new IllegalArgumentException
                    ("extraMetadataFormatNames == null && extraMetadataFormatClassNames != null!");
            }
        }
    }

    /**
     * Returns {@code true} if the standard metadata format is
     * supported by {@code getMetadataFormat},
     * {@code getAsTree}, {@code setFromTree}, and
     * {@code mergeTree}.
     *
     * <p> The default implementation returns the value of the
     * {@code standardFormatSupported} instance variable.
     *
     * @return {@code true} if the standard metadata format
     * is supported.
     *
     * @see #getAsTree
     * @see #setFromTree
     * @see #mergeTree
     * @see #getMetadataFormat
     */
    public boolean isStandardMetadataFormatSupported() {
        return standardFormatSupported;
    }

    /**
     * Returns {@code true} if this object does not support the
     * {@code mergeTree}, {@code setFromTree}, and
     * {@code reset} methods.
     *
     * @return true if this {@code IIOMetadata} object cannot be
     * modified.
     */
    public abstract boolean isReadOnly();

    /**
     * Returns the name of the "native" metadata format for this
     * plug-in, which typically allows for lossless encoding and
     * transmission of the metadata stored in the format handled by
     * this plug-in.  If no such format is supported,
     * {@code null} will be returned.
     *
     * <p> The structure and contents of the "native" metadata format
     * are defined by the plug-in that created this
     * {@code IIOMetadata} object.  Plug-ins for simple formats
     * will usually create a dummy node for the root, and then a
     * series of child nodes representing individual tags, chunks, or
     * keyword/value pairs.  A plug-in may choose whether or not to
     * document its native format.
     *
     * <p> The default implementation returns the value of the
     * {@code nativeMetadataFormatName} instance variable.
     *
     * @return the name of the native format, or {@code null}.
     *
     * @see #getExtraMetadataFormatNames
     * @see #getMetadataFormatNames
     */
    public String getNativeMetadataFormatName() {
        return nativeMetadataFormatName;
    }

    /**
     * Returns an array of {@code String}s containing the names
     * of additional metadata formats, other than the native and standard
     * formats, recognized by this plug-in's
     * {@code getAsTree}, {@code setFromTree}, and
     * {@code mergeTree} methods.  If there are no such additional
     * formats, {@code null} is returned.
     *
     * <p> The default implementation returns a clone of the
     * {@code extraMetadataFormatNames} instance variable.
     *
     * @return an array of {@code String}s with length at least
     * 1, or {@code null}.
     *
     * @see #getAsTree
     * @see #setFromTree
     * @see #mergeTree
     * @see #getNativeMetadataFormatName
     * @see #getMetadataFormatNames
     */
    public String[] getExtraMetadataFormatNames() {
        if (extraMetadataFormatNames == null) {
            return null;
        }
        return extraMetadataFormatNames.clone();
    }

    /**
     * Returns an array of {@code String}s containing the names
     * of all metadata formats, including the native and standard
     * formats, recognized by this plug-in's {@code getAsTree},
     * {@code setFromTree}, and {@code mergeTree} methods.
     * If there are no such formats, {@code null} is returned.
     *
     * <p> The default implementation calls
     * {@code getNativeMetadataFormatName},
     * {@code isStandardMetadataFormatSupported}, and
     * {@code getExtraMetadataFormatNames} and returns the
     * combined results.
     *
     * @return an array of {@code String}s.
     *
     * @see #getNativeMetadataFormatName
     * @see #isStandardMetadataFormatSupported
     * @see #getExtraMetadataFormatNames
     */
    public String[] getMetadataFormatNames() {
        String nativeName = getNativeMetadataFormatName();
        String standardName = isStandardMetadataFormatSupported() ?
            IIOMetadataFormatImpl.standardMetadataFormatName : null;
        String[] extraNames = getExtraMetadataFormatNames();

        int numFormats = 0;
        if (nativeName != null) {
            ++numFormats;
        }
        if (standardName != null) {
            ++numFormats;
        }
        if (extraNames != null) {
            numFormats += extraNames.length;
        }
        if (numFormats == 0) {
            return null;
        }

        String[] formats = new String[numFormats];
        int index = 0;
        if (nativeName != null) {
            formats[index++] = nativeName;
        }
        if (standardName != null) {
            formats[index++] = standardName;
        }
        if (extraNames != null) {
            for (int i = 0; i < extraNames.length; i++) {
                formats[index++] = extraNames[i];
            }
        }

        return formats;
    }

    /**
     * Returns an {@code IIOMetadataFormat} object describing the
     * given metadata format, or {@code null} if no description
     * is available.  The supplied name must be one of those returned
     * by {@code getMetadataFormatNames} (<i>i.e.</i>, either the
     * native format name, the standard format name, or one of those
     * returned by {@code getExtraMetadataFormatNames}).
     *
     * <p> The default implementation checks the name against the
     * global standard metadata format name, and returns that format
     * if it is supported.  Otherwise, it checks against the native
     * format names followed by any additional format names.  If a
     * match is found, it retrieves the name of the
     * {@code IIOMetadataFormat} class from
     * {@code nativeMetadataFormatClassName} or
     * {@code extraMetadataFormatClassNames} as appropriate, and
     * constructs an instance of that class using its
     * {@code getInstance} method.
     *
     * @param formatName the desired metadata format.
     *
     * @return an {@code IIOMetadataFormat} object.
     *
     * @exception IllegalArgumentException if {@code formatName}
     * is {@code null} or is not one of the names recognized by
     * the plug-in.
     * @exception IllegalStateException if the class corresponding to
     * the format name cannot be loaded.
     */
    public IIOMetadataFormat getMetadataFormat(String formatName) {
        if (formatName == null) {
            throw new IllegalArgumentException("formatName == null!");
        }
        if (standardFormatSupported
            && formatName.equals
                (IIOMetadataFormatImpl.standardMetadataFormatName)) {
            return IIOMetadataFormatImpl.getStandardFormatInstance();
        }
        String formatClassName = null;
        if (formatName.equals(nativeMetadataFormatName)) {
            formatClassName = nativeMetadataFormatClassName;
        } else if (extraMetadataFormatNames != null) {
            for (int i = 0; i < extraMetadataFormatNames.length; i++) {
                if (formatName.equals(extraMetadataFormatNames[i])) {
                    formatClassName = extraMetadataFormatClassNames[i];
                    break;  // out of for
                }
            }
        }
        if (formatClassName == null) {
            throw new IllegalArgumentException("Unsupported format name");
        }
        try {
            final String className = formatClassName;
            // Try to load from the module of the IIOMetadata implementation
            // for this plugin since the IIOMetadataImpl is part of the plugin
            PrivilegedAction<Class<?>> pa = () -> { return getMetadataFormatClass(className); };
            Class<?> cls = AccessController.doPrivileged(pa);
            Method meth = cls.getMethod("getInstance");
            return (IIOMetadataFormat) meth.invoke(null);
        } catch (Exception e) {
            RuntimeException ex =
                new IllegalStateException ("Can't obtain format");
            ex.initCause(e);
            throw ex;
        }
    }

    // If updating this method also see the same in ImageReaderWriterSpi.java
    private Class<?> getMetadataFormatClass(String formatClassName) {
        Module thisModule = IIOMetadata.class.getModule();
        Module targetModule = this.getClass().getModule();
        Class<?> c = null;
        try {
            ClassLoader cl = this.getClass().getClassLoader();
            c = Class.forName(formatClassName, false, cl);
            if (!IIOMetadataFormat.class.isAssignableFrom(c)) {
                return null;
            }
        } catch (ClassNotFoundException e) {
        }
        if (thisModule.equals(targetModule) || c == null) {
            return c;
        }
        if (targetModule.isNamed()) {
            int i = formatClassName.lastIndexOf(".");
            String pn = i > 0 ? formatClassName.substring(0, i) : "";
            if (!targetModule.isExported(pn, thisModule)) {
                throw new IllegalStateException("Class " + formatClassName +
                   " in named module must be exported to java.desktop module.");
            }
        }
        return c;
    }

    /**
     * Returns an XML DOM {@code Node} object that represents the
     * root of a tree of metadata contained within this object
     * according to the conventions defined by a given metadata
     * format.
     *
     * <p> The names of the available metadata formats may be queried
     * using the {@code getMetadataFormatNames} method.
     *
     * @param formatName the desired metadata format.
     *
     * @return an XML DOM {@code Node} object forming the
     * root of a tree.
     *
     * @exception IllegalArgumentException if {@code formatName}
     * is {@code null} or is not one of the names returned by
     * {@code getMetadataFormatNames}.
     *
     * @see #getMetadataFormatNames
     * @see #setFromTree
     * @see #mergeTree
     */
    public abstract Node getAsTree(String formatName);

    /**
     * Alters the internal state of this {@code IIOMetadata}
     * object from a tree of XML DOM {@code Node}s whose syntax
     * is defined by the given metadata format.  The previous state is
     * altered only as necessary to accommodate the nodes that are
     * present in the given tree.  If the tree structure or contents
     * are invalid, an {@code IIOInvalidTreeException} will be
     * thrown.
     *
     * <p> As the semantics of how a tree or subtree may be merged with
     * another tree are completely format-specific, plug-in authors may
     * implement this method in whatever manner is most appropriate for
     * the format, including simply replacing all existing state with the
     * contents of the given tree.
     *
     * @param formatName the desired metadata format.
     * @param root an XML DOM {@code Node} object forming the
     * root of a tree.
     *
     * @exception IllegalStateException if this object is read-only.
     * @exception IllegalArgumentException if {@code formatName}
     * is {@code null} or is not one of the names returned by
     * {@code getMetadataFormatNames}.
     * @exception IllegalArgumentException if {@code root} is
     * {@code null}.
     * @exception IIOInvalidTreeException if the tree cannot be parsed
     * successfully using the rules of the given format.
     *
     * @see #getMetadataFormatNames
     * @see #getAsTree
     * @see #setFromTree
     */
    public abstract void mergeTree(String formatName, Node root)
        throws IIOInvalidTreeException;

    /**
     * Returns an {@code IIOMetadataNode} representing the chroma
     * information of the standard {@code javax_imageio_1.0}
     * metadata format, or {@code null} if no such information is
     * available.  This method is intended to be called by the utility
     * routine {@code getStandardTree}.
     *
     * <p> The default implementation returns {@code null}.
     *
     * <p> Subclasses should override this method to produce an
     * appropriate subtree if they wish to support the standard
     * metadata format.
     *
     * @return an {@code IIOMetadataNode}, or {@code null}.
     *
     * @see #getStandardTree
     */
    protected IIOMetadataNode getStandardChromaNode() {
        return null;
    }

    /**
     * Returns an {@code IIOMetadataNode} representing the
     * compression information of the standard
     * {@code javax_imageio_1.0} metadata format, or
     * {@code null} if no such information is available.  This
     * method is intended to be called by the utility routine
     * {@code getStandardTree}.
     *
     * <p> The default implementation returns {@code null}.
     *
     * <p> Subclasses should override this method to produce an
     * appropriate subtree if they wish to support the standard
     * metadata format.
     *
     * @return an {@code IIOMetadataNode}, or {@code null}.
     *
     * @see #getStandardTree
     */
    protected IIOMetadataNode getStandardCompressionNode() {
        return null;
    }

    /**
     * Returns an {@code IIOMetadataNode} representing the data
     * format information of the standard
     * {@code javax_imageio_1.0} metadata format, or
     * {@code null} if no such information is available.  This
     * method is intended to be called by the utility routine
     * {@code getStandardTree}.
     *
     * <p> The default implementation returns {@code null}.
     *
     * <p> Subclasses should override this method to produce an
     * appropriate subtree if they wish to support the standard
     * metadata format.
     *
     * @return an {@code IIOMetadataNode}, or {@code null}.
     *
     * @see #getStandardTree
     */
    protected IIOMetadataNode getStandardDataNode() {
        return null;
    }

    /**
     * Returns an {@code IIOMetadataNode} representing the
     * dimension information of the standard
     * {@code javax_imageio_1.0} metadata format, or
     * {@code null} if no such information is available.  This
     * method is intended to be called by the utility routine
     * {@code getStandardTree}.
     *
     * <p> The default implementation returns {@code null}.
     *
     * <p> Subclasses should override this method to produce an
     * appropriate subtree if they wish to support the standard
     * metadata format.
     *
     * @return an {@code IIOMetadataNode}, or {@code null}.
     *
     * @see #getStandardTree
     */
    protected IIOMetadataNode getStandardDimensionNode() {
        return null;
    }

    /**
     * Returns an {@code IIOMetadataNode} representing the document
     * information of the standard {@code javax_imageio_1.0}
     * metadata format, or {@code null} if no such information is
     * available.  This method is intended to be called by the utility
     * routine {@code getStandardTree}.
     *
     * <p> The default implementation returns {@code null}.
     *
     * <p> Subclasses should override this method to produce an
     * appropriate subtree if they wish to support the standard
     * metadata format.
     *
     * @return an {@code IIOMetadataNode}, or {@code null}.
     *
     * @see #getStandardTree
     */
    protected IIOMetadataNode getStandardDocumentNode() {
        return null;
    }

    /**
     * Returns an {@code IIOMetadataNode} representing the textual
     * information of the standard {@code javax_imageio_1.0}
     * metadata format, or {@code null} if no such information is
     * available.  This method is intended to be called by the utility
     * routine {@code getStandardTree}.
     *
     * <p> The default implementation returns {@code null}.
     *
     * <p> Subclasses should override this method to produce an
     * appropriate subtree if they wish to support the standard
     * metadata format.
     *
     * @return an {@code IIOMetadataNode}, or {@code null}.
     *
     * @see #getStandardTree
     */
    protected IIOMetadataNode getStandardTextNode() {
        return null;
    }

    /**
     * Returns an {@code IIOMetadataNode} representing the tiling
     * information of the standard {@code javax_imageio_1.0}
     * metadata format, or {@code null} if no such information is
     * available.  This method is intended to be called by the utility
     * routine {@code getStandardTree}.
     *
     * <p> The default implementation returns {@code null}.
     *
     * <p> Subclasses should override this method to produce an
     * appropriate subtree if they wish to support the standard
     * metadata format.
     *
     * @return an {@code IIOMetadataNode}, or {@code null}.
     *
     * @see #getStandardTree
     */
    protected IIOMetadataNode getStandardTileNode() {
        return null;
    }

    /**
     * Returns an {@code IIOMetadataNode} representing the
     * transparency information of the standard
     * {@code javax_imageio_1.0} metadata format, or
     * {@code null} if no such information is available.  This
     * method is intended to be called by the utility routine
     * {@code getStandardTree}.
     *
     * <p> The default implementation returns {@code null}.
     *
     * <p> Subclasses should override this method to produce an
     * appropriate subtree if they wish to support the standard
     * metadata format.
     *
     * @return an {@code IIOMetadataNode}, or {@code null}.
     */
    protected IIOMetadataNode getStandardTransparencyNode() {
        return null;
    }

    /**
     * Appends a new node to an existing node, if the new node is
     * non-{@code null}.
     */
    private void append(IIOMetadataNode root, IIOMetadataNode node) {
        if (node != null) {
            root.appendChild(node);
        }
    }

    /**
     * A utility method to return a tree of
     * {@code IIOMetadataNode}s representing the metadata
     * contained within this object according to the conventions of
     * the standard {@code javax_imageio_1.0} metadata format.
     *
     * <p> This method calls the various {@code getStandard*Node}
     * methods to supply each of the subtrees rooted at the children
     * of the root node.  If any of those methods returns
     * {@code null}, the corresponding subtree will be omitted.
     * If all of them return {@code null}, a tree consisting of a
     * single root node will be returned.
     *
     * @return an {@code IIOMetadataNode} representing the root
     * of a metadata tree in the {@code javax_imageio_1.0}
     * format.
     *
     * @see #getStandardChromaNode
     * @see #getStandardCompressionNode
     * @see #getStandardDataNode
     * @see #getStandardDimensionNode
     * @see #getStandardDocumentNode
     * @see #getStandardTextNode
     * @see #getStandardTileNode
     * @see #getStandardTransparencyNode
     */
    protected final IIOMetadataNode getStandardTree() {
        IIOMetadataNode root = new IIOMetadataNode
                (IIOMetadataFormatImpl.standardMetadataFormatName);
        append(root, getStandardChromaNode());
        append(root, getStandardCompressionNode());
        append(root, getStandardDataNode());
        append(root, getStandardDimensionNode());
        append(root, getStandardDocumentNode());
        append(root, getStandardTextNode());
        append(root, getStandardTileNode());
        append(root, getStandardTransparencyNode());
        return root;
    }

    /**
     * Sets the internal state of this {@code IIOMetadata} object
     * from a tree of XML DOM {@code Node}s whose syntax is
     * defined by the given metadata format.  The previous state is
     * discarded.  If the tree's structure or contents are invalid, an
     * {@code IIOInvalidTreeException} will be thrown.
     *
     * <p> The default implementation calls {@code reset}
     * followed by {@code mergeTree(formatName, root)}.
     *
     * @param formatName the desired metadata format.
     * @param root an XML DOM {@code Node} object forming the
     * root of a tree.
     *
     * @exception IllegalStateException if this object is read-only.
     * @exception IllegalArgumentException if {@code formatName}
     * is {@code null} or is not one of the names returned by
     * {@code getMetadataFormatNames}.
     * @exception IllegalArgumentException if {@code root} is
     * {@code null}.
     * @exception IIOInvalidTreeException if the tree cannot be parsed
     * successfully using the rules of the given format.
     *
     * @see #getMetadataFormatNames
     * @see #getAsTree
     * @see #mergeTree
     */
    public void setFromTree(String formatName, Node root)
        throws IIOInvalidTreeException {
        reset();
        mergeTree(formatName, root);
    }

    /**
     * Resets all the data stored in this object to default values,
     * usually to the state this object was in immediately after
     * construction, though the precise semantics are plug-in specific.
     * Note that there are many possible default values, depending on
     * how the object was created.
     *
     * @exception IllegalStateException if this object is read-only.
     *
     * @see javax.imageio.ImageReader#getStreamMetadata
     * @see javax.imageio.ImageReader#getImageMetadata
     * @see javax.imageio.ImageWriter#getDefaultStreamMetadata
     * @see javax.imageio.ImageWriter#getDefaultImageMetadata
     */
    public abstract void reset();

    /**
     * Sets the {@code IIOMetadataController} to be used
     * to provide settings for this {@code IIOMetadata}
     * object when the {@code activateController} method
     * is called, overriding any default controller.  If the
     * argument is {@code null}, no controller will be
     * used, including any default.  To restore the default, use
     * {@code setController(getDefaultController())}.
     *
     * <p> The default implementation sets the {@code controller}
     * instance variable to the supplied value.
     *
     * @param controller An appropriate
     * {@code IIOMetadataController}, or {@code null}.
     *
     * @see IIOMetadataController
     * @see #getController
     * @see #getDefaultController
     * @see #hasController
     * @see #activateController()
     */
    public void setController(IIOMetadataController controller) {
        this.controller = controller;
    }

    /**
     * Returns whatever {@code IIOMetadataController} is currently
     * installed.  This could be the default if there is one,
     * {@code null}, or the argument of the most recent call
     * to {@code setController}.
     *
     * <p> The default implementation returns the value of the
     * {@code controller} instance variable.
     *
     * @return the currently installed
     * {@code IIOMetadataController}, or {@code null}.
     *
     * @see IIOMetadataController
     * @see #setController
     * @see #getDefaultController
     * @see #hasController
     * @see #activateController()
     */
    public IIOMetadataController getController() {
        return controller;
    }

    /**
     * Returns the default {@code IIOMetadataController}, if there
     * is one, regardless of the currently installed controller.  If
     * there is no default controller, returns {@code null}.
     *
     * <p> The default implementation returns the value of the
     * {@code defaultController} instance variable.
     *
     * @return the default {@code IIOMetadataController}, or
     * {@code null}.
     *
     * @see IIOMetadataController
     * @see #setController(IIOMetadataController)
     * @see #getController
     * @see #hasController
     * @see #activateController()
     */
    public IIOMetadataController getDefaultController() {
        return defaultController;
    }

    /**
     * Returns {@code true} if there is a controller installed
     * for this {@code IIOMetadata} object.
     *
     * <p> The default implementation returns {@code true} if the
     * {@code getController} method returns a
     * non-{@code null} value.
     *
     * @return {@code true} if a controller is installed.
     *
     * @see IIOMetadataController
     * @see #setController(IIOMetadataController)
     * @see #getController
     * @see #getDefaultController
     * @see #activateController()
     */
    public boolean hasController() {
        return (getController() != null);
    }

    /**
     * Activates the installed {@code IIOMetadataController} for
     * this {@code IIOMetadata} object and returns the resulting
     * value.  When this method returns {@code true}, all values for this
     * {@code IIOMetadata} object will be ready for the next write
     * operation.  If {@code false} is
     * returned, no settings in this object will have been disturbed
     * (<i>i.e.</i>, the user canceled the operation).
     *
     * <p> Ordinarily, the controller will be a GUI providing a user
     * interface for a subclass of {@code IIOMetadata} for a
     * particular plug-in.  Controllers need not be GUIs, however.
     *
     * <p> The default implementation calls {@code getController}
     * and the calls {@code activate} on the returned object if
     * {@code hasController} returns {@code true}.
     *
     * @return {@code true} if the controller completed normally.
     *
     * @exception IllegalStateException if there is no controller
     * currently installed.
     *
     * @see IIOMetadataController
     * @see #setController(IIOMetadataController)
     * @see #getController
     * @see #getDefaultController
     * @see #hasController
     */
    public boolean activateController() {
        if (!hasController()) {
            throw new IllegalStateException("hasController() == false!");
        }
        return getController().activate(this);
    }
}