1879N/A * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved. 1612N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 1612N/A * This code is free software; you can redistribute it and/or modify it 1612N/A * under the terms of the GNU General Public License version 2 only, as 1612N/A * published by the Free Software Foundation. Oracle designates this 1612N/A * particular file as subject to the "Classpath" exception as provided 1612N/A * by Oracle in the LICENSE file that accompanied this code. 1612N/A * This code is distributed in the hope that it will be useful, but WITHOUT 1612N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1612N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1612N/A * version 2 for more details (a copy is included in the LICENSE file that 1612N/A * You should have received a copy of the GNU General Public License version 1612N/A * 2 along with this work; if not, write to the Free Software Foundation, 1612N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1612N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 1612N/A * or visit www.oracle.com if you need additional information or have any 1879N/A * An abstract class to be extended by objects that represent metadata 1879N/A * (non-image data) associated with images and streams. Plug-ins 1879N/A * represent metadata using opaque, plug-in specific objects. These 1879N/A * objects, however, provide the ability to access their internal 1879N/A * information as a tree of <code>IIOMetadataNode</code> objects that 1879N/A * support the XML DOM interfaces as well as additional interfaces for 1612N/A * storing non-textual data and retrieving information about legal 1612N/A * data values. The format of such trees is plug-in dependent, but 1612N/A * plug-ins may choose to support a plug-in neutral format described 1612N/A * below. A single plug-in may support multiple metadata formats, 1612N/A * whose names maybe determined by calling 1612N/A * <code>getMetadataFormatNames</code>. The plug-in may also support 1612N/A * a single special format, referred to as the "native" format, which 1612N/A * is designed to encode its metadata losslessly. This format will 1612N/A * typically be designed specifically to work with a specific file 1612N/A * format, so that images may be loaded and saved in the same format 1612N/A * with no loss of metadata, but may be less useful for transfering 1612N/A * metadata between an <code>ImageReader</code> and an 1612N/A * <code>ImageWriter</code> for different image formats. To convert 1612N/A * between two native formats as losslessly as the image file formats 1612N/A * will allow, an <code>ImageTranscoder</code> object must be used. 1612N/A * @see javax.imageio.ImageReader#getImageMetadata 1612N/A * @see javax.imageio.ImageReader#getStreamMetadata 1612N/A * @see javax.imageio.ImageReader#readAll 1612N/A * @see javax.imageio.ImageWriter#getDefaultStreamMetadata 1612N/A * @see javax.imageio.ImageWriter#getDefaultImageMetadata 1612N/A * @see javax.imageio.ImageWriter#write 1612N/A * @see javax.imageio.ImageWriter#convertImageMetadata 1612N/A * @see javax.imageio.ImageWriter#convertStreamMetadata 1612N/A * @see javax.imageio.IIOImage 1612N/A * @see javax.imageio.ImageTranscoder 1612N/A * A boolean indicating whether the concrete subclass supports the 1612N/A * standard metadata format, set via the constructor. 1612N/A * The name of the native metadata format for this object, 1612N/A * initialized to <code>null</code> and set via the constructor. 1612N/A * The name of the class implementing <code>IIOMetadataFormat</code> 1612N/A * and representing the native metadata format, initialized to 1612N/A * <code>null</code> and set via the constructor. 1612N/A * An array of names of formats, other than the standard and 1612N/A * native formats, that are supported by this plug-in, 1612N/A * initialized to <code>null</code> and set via the constructor. 1612N/A * An array of names of classes implementing <code>IIOMetadataFormat</code> 1612N/A * and representing the metadata formats, other than the standard and 1612N/A * native formats, that are supported by this plug-in, 1612N/A * initialized to <code>null</code> and set via the constructor. 1612N/A * An <code>IIOMetadataController</code> that is suggested for use 1612N/A * as the controller for this <code>IIOMetadata</code> object. It 1612N/A * may be retrieved via <code>getDefaultController</code>. To 1612N/A * install the default controller, call 1612N/A * <code>setController(getDefaultController())</code>. This 1612N/A * instance variable should be set by subclasses that choose to 1612N/A * provide their own default controller, usually a GUI, for 1612N/A * @see IIOMetadataController 1612N/A * @see #getDefaultController 1612N/A * The <code>IIOMetadataController</code> that will be 1612N/A * used to provide settings for this <code>IIOMetadata</code> 1612N/A * object when the <code>activateController</code> method 1612N/A * is called. This value overrides any default controller, 1612N/A * even when <code>null</code>. 1612N/A * @see IIOMetadataController 1612N/A * @see #setController(IIOMetadataController) 1612N/A * @see #activateController() 1612N/A * Constructs an empty <code>IIOMetadata</code> object. The 1612N/A * subclass is responsible for suppying values for all protected 1612N/A * instance variables that will allow any non-overridden default 1612N/A * implemtations of methods to satisfy their contracts. For example, 1612N/A * <code>extraMetadataFormatNames</code> should not have length 0. 1612N/A * Constructs an <code>IIOMetadata</code> object with the given 1612N/A * format names and format class names, as well as a boolean 1612N/A * indicating whether the standard format is supported. 1612N/A * <p> This constructor does not attempt to check the class names 1612N/A * for validity. Invalid class names may cause exceptions in 1612N/A * subsequent calls to <code>getMetadataFormat</code>. 1612N/A * @param standardMetadataFormatSupported <code>true</code> if 1612N/A * this object can return or accept a DOM tree using the standard 1612N/A * @param nativeMetadataFormatName the name of the native metadata 1612N/A * format, as a <code>String</code>, or <code>null</code> if there 1612N/A * @param nativeMetadataFormatClassName the name of the class of 1612N/A * the native metadata format, or <code>null</code> if there is 1612N/A * @param extraMetadataFormatNames an array of <code>String</code>s 1612N/A * indicating additional formats supported by this object, or 1612N/A * <code>null</code> if there are none. 1612N/A * @param extraMetadataFormatClassNames an array of <code>String</code>s 1612N/A * indicating the class names of any additional formats supported by 1612N/A * this object, or <code>null</code> if there are none. 1612N/A * @exception IllegalArgumentException if 1612N/A * <code>extraMetadataFormatNames</code> has length 0. 1612N/A * @exception IllegalArgumentException if 1612N/A * <code>extraMetadataFormatNames</code> and 1612N/A * <code>extraMetadataFormatClassNames</code> are neither both 1612N/A * <code>null</code>, nor of the same length. 1612N/A (
"extraMetadataFormatNames.length == 0!");
1612N/A (
"extraMetadataFormatNames != null && extraMetadataFormatClassNames == null!");
1612N/A (
"extraMetadataFormatClassNames.length != extraMetadataFormatNames.length!");
(
"extraMetadataFormatNames == null && extraMetadataFormatClassNames != null!");
* Returns <code>true</code> if the standard metadata format is * supported by <code>getMetadataFormat</code>, * <code>getAsTree</code>, <code>setFromTree</code>, and * <code>mergeTree</code>. * <p> The default implementation returns the value of the * <code>standardFormatSupported</code> instance variable. * @return <code>true</code> if the standard metadata format * @see #getMetadataFormat * Returns <code>true</code> if this object does not support the * <code>mergeTree</code>, <code>setFromTree</code>, and * <code>reset</code> methods. * @return true if this <code>IIOMetadata</code> object cannot be * 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</code>will be returned. * <p> The structure and contents of the "native" metadata format * are defined by the plug-in that created this * <code>IIOMetadata</code> 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</code> instance variable. * @return the name of the native format, or <code>null</code>. * @see #getExtraMetadataFormatNames * @see #getMetadataFormatNames * Returns an array of <code>String</code>s containing the names * of additional metadata formats, other than the native and standard * formats, recognized by this plug-in's * <code>getAsTree</code>, <code>setFromTree</code>, and * <code>mergeTree</code> methods. If there are no such additional * formats, <code>null</code> is returned. * <p> The default implementation returns a clone of the * <code>extraMetadataFormatNames</code> instance variable. * @return an array of <code>String</code>s with length at least * 1, or <code>null</code>. * @see #getNativeMetadataFormatName * @see #getMetadataFormatNames * Returns an array of <code>String</code>s containing the names * of all metadata formats, including the native and standard * formats, recognized by this plug-in's <code>getAsTree</code>, * <code>setFromTree</code>, and <code>mergeTree</code> methods. * If there are no such formats, <code>null</code> is returned. * <p> The default implementation calls * <code>getNativeMetadataFormatName</code>, * <code>isStandardMetadataFormatSupported</code>, and * <code>getExtraMetadataFormatNames</code> and returns the * @return an array of <code>String</code>s. * @see #getNativeMetadataFormatName * @see #isStandardMetadataFormatSupported * @see #getExtraMetadataFormatNames * Returns an <code>IIOMetadataFormat</code> object describing the * given metadata format, or <code>null</code> if no description * is available. The supplied name must be one of those returned * by <code>getMetadataFormatNames</code> (<i>i.e.</i>, either the * native format name, the standard format name, or one of those * returned by <code>getExtraMetadataFormatNames</code>). * <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</code> class from * <code>nativeMetadataFormatClassName</code> or * <code>extraMetadataFormatClassNames</code> as appropriate, and * constructs an instance of that class using its * <code>getInstance</code> method. * @param formatName the desired metadata format. * @return an <code>IIOMetadataFormat</code> object. * @exception IllegalArgumentException if <code>formatName</code> * is <code>null</code> or is not one of the names recognized by * @exception IllegalStateException if the class corresponding to * the format name cannot be loaded. // firstly we try to use classloader used for loading // the IIOMetadata implemantation for this plugin. // we failed to load IIOMetadataFormat class by // using IIOMetadata classloader.Next try is to // use thread context classloader. // finally we try to use system classloader in case // if we failed to load IIOMetadataFormat implementation * Returns an XML DOM <code>Node</code> object that represents the * root of a tree of metadata contained within this object * according to the conventions defined by a given metadata * <p> The names of the available metadata formats may be queried * using the <code>getMetadataFormatNames</code> method. * @param formatName the desired metadata format. * @return an XML DOM <code>Node</code> object forming the * @exception IllegalArgumentException if <code>formatName</code> * is <code>null</code> or is not one of the names returned by * <code>getMetadataFormatNames</code>. * @see #getMetadataFormatNames * Alters the internal state of this <code>IIOMetadata</code> * object from a tree of XML DOM <code>Node</code>s whose syntax * is defined by the given metadata format. The previous state is * altered only as necessary to accomodate the nodes that are * present in the given tree. If the tree structure or contents * are invalid, an <code>IIOInvalidTreeException</code> will be * <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</code> object forming the * @exception IllegalStateException if this object is read-only. * @exception IllegalArgumentException if <code>formatName</code> * is <code>null</code> or is not one of the names returned by * <code>getMetadataFormatNames</code>. * @exception IllegalArgumentException if <code>root</code> is * @exception IIOInvalidTreeException if the tree cannot be parsed * successfully using the rules of the given format. * @see #getMetadataFormatNames * Returns an <code>IIOMetadataNode</code> representing the chroma * information of the standard <code>javax_imageio_1.0</code> * metadata format, or <code>null</code> if no such information is * available. This method is intended to be called by the utility * routine <code>getStandardTree</code>. * <p> The default implementation returns <code>null</code>. * <p> Subclasses should override this method to produce an * appropriate subtree if they wish to support the standard * @return an <code>IIOMetadataNode</code>, or <code>null</code>. * Returns an <code>IIOMetadataNode</code> representing the * compression information of the standard * <code>javax_imageio_1.0</code> metadata format, or * <code>null</code> if no such information is available. This * method is intended to be called by the utility routine * <code>getStandardTree</code>. * <p> The default implementation returns <code>null</code>. * <p> Subclasses should override this method to produce an * appropriate subtree if they wish to support the standard * @return an <code>IIOMetadataNode</code>, or <code>null</code>. * Returns an <code>IIOMetadataNode</code> representing the data * format information of the standard * <code>javax_imageio_1.0</code> metadata format, or * <code>null</code> if no such information is available. This * method is intended to be called by the utility routine * <code>getStandardTree</code>. * <p> The default implementation returns <code>null</code>. * <p> Subclasses should override this method to produce an * appropriate subtree if they wish to support the standard * @return an <code>IIOMetadataNode</code>, or <code>null</code>. * Returns an <code>IIOMetadataNode</code> representing the * dimension information of the standard * <code>javax_imageio_1.0</code> metadata format, or * <code>null</code> if no such information is available. This * method is intended to be called by the utility routine * <code>getStandardTree</code>. * <p> The default implementation returns <code>null</code>. * <p> Subclasses should override this method to produce an * appropriate subtree if they wish to support the standard * @return an <code>IIOMetadataNode</code>, or <code>null</code>. * Returns an <code>IIOMetadataNode</code> representing the document * information of the standard <code>javax_imageio_1.0</code> * metadata format, or <code>null</code> if no such information is * available. This method is intended to be called by the utility * routine <code>getStandardTree</code>. * <p> The default implementation returns <code>null</code>. * <p> Subclasses should override this method to produce an * appropriate subtree if they wish to support the standard * @return an <code>IIOMetadataNode</code>, or <code>null</code>. * Returns an <code>IIOMetadataNode</code> representing the textual * information of the standard <code>javax_imageio_1.0</code> * metadata format, or <code>null</code> if no such information is * available. This method is intended to be called by the utility * routine <code>getStandardTree</code>. * <p> The default implementation returns <code>null</code>. * <p> Subclasses should override this method to produce an * appropriate subtree if they wish to support the standard * @return an <code>IIOMetadataNode</code>, or <code>null</code>. * Returns an <code>IIOMetadataNode</code> representing the tiling * information of the standard <code>javax_imageio_1.0</code> * metadata format, or <code>null</code> if no such information is * available. This method is intended to be called by the utility * routine <code>getStandardTree</code>. * <p> The default implementation returns <code>null</code>. * <p> Subclasses should override this method to produce an * appropriate subtree if they wish to support the standard * @return an <code>IIOMetadataNode</code>, or <code>null</code>. * Returns an <code>IIOMetadataNode</code> representing the * transparency information of the standard * <code>javax_imageio_1.0</code> metadata format, or * <code>null</code> if no such information is available. This * method is intended to be called by the utility routine * <code>getStandardTree</code>. * <p> The default implementation returns <code>null</code>. * <p> Subclasses should override this method to produce an * appropriate subtree if they wish to support the standard * @return an <code>IIOMetadataNode</code>, or <code>null</code>. * Appends a new node to an existing node, if the new node is * A utility method to return a tree of * <code>IIOMetadataNode</code>s representing the metadata * contained within this object according to the conventions of * the standard <code>javax_imageio_1.0</code> metadata format. * <p> This method calls the various <code>getStandard*Node</code> * methods to supply each of the subtrees rooted at the children * of the root node. If any of those methods returns * <code>null</code>, the corresponding subtree will be omitted. * If all of them return <code>null</code>, a tree consisting of a * single root node will be returned. * @return an <code>IIOMetadataNode</code> representing the root * of a metadata tree in the <code>javax_imageio_1.0</code> * @see #getStandardChromaNode * @see #getStandardCompressionNode * @see #getStandardDataNode * @see #getStandardDimensionNode * @see #getStandardDocumentNode * @see #getStandardTextNode * @see #getStandardTileNode * @see #getStandardTransparencyNode * Sets the internal state of this <code>IIOMetadata</code> object * from a tree of XML DOM <code>Node</code>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</code> will be thrown. * <p> The default implementation calls <code>reset</code> * followed by <code>mergeTree(formatName, root)</code>. * @param formatName the desired metadata format. * @param root an XML DOM <code>Node</code> object forming the * @exception IllegalStateException if this object is read-only. * @exception IllegalArgumentException if <code>formatName</code> * is <code>null</code> or is not one of the names returned by * <code>getMetadataFormatNames</code>. * @exception IllegalArgumentException if <code>root</code> is * @exception IIOInvalidTreeException if the tree cannot be parsed * successfully using the rules of the given format. * @see #getMetadataFormatNames * 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</code> to be used * to provide settings for this <code>IIOMetadata</code> * object when the <code>activateController</code> method * is called, overriding any default controller. If the * argument is <code>null</code>, no controller will be * used, including any default. To restore the default, use * <code>setController(getDefaultController())</code>. * <p> The default implementation sets the <code>controller</code> * instance variable to the supplied value. * @param controller An appropriate * <code>IIOMetadataController</code>, or <code>null</code>. * @see IIOMetadataController * @see #getDefaultController * @see #activateController() * Returns whatever <code>IIOMetadataController</code> is currently * installed. This could be the default if there is one, * <code>null</code>, or the argument of the most recent call * to <code>setController</code>. * <p> The default implementation returns the value of the * <code>controller</code> instance variable. * @return the currently installed * <code>IIOMetadataController</code>, or <code>null</code>. * @see IIOMetadataController * @see #getDefaultController * @see #activateController() * Returns the default <code>IIOMetadataController</code>, if there * is one, regardless of the currently installed controller. If * there is no default controller, returns <code>null</code>. * <p> The default implementation returns the value of the * <code>defaultController</code> instance variable. * @return the default <code>IIOMetadataController</code>, or * @see IIOMetadataController * @see #setController(IIOMetadataController) * @see #activateController() * Returns <code>true</code> if there is a controller installed * for this <code>IIOMetadata</code> object. * <p> The default implementation returns <code>true</code> if the * <code>getController</code> method returns a * non-<code>null</code> value. * @return <code>true</code> if a controller is installed. * @see IIOMetadataController * @see #setController(IIOMetadataController) * @see #getDefaultController * @see #activateController() * Activates the installed <code>IIOMetadataController</code> for * this <code>IIOMetadata</code> object and returns the resulting * value. When this method returns <code>true</code>, all values for this * <code>IIOMetadata</code> object will be ready for the next write * operation. If <code>false</code> 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</code> for a * particular plug-in. Controllers need not be GUIs, however. * <p> The default implementation calls <code>getController</code> * and the calls <code>activate</code> on the returned object if * <code>hasController</code> returns <code>true</code>. * @return <code>true</code> if the controller completed normally. * @exception IllegalStateException if there is no controller * @see IIOMetadataController * @see #setController(IIOMetadataController) * @see #getDefaultController