/* * Copyright (c) 2000, 2005, 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; /** * 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</code> 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</code>. 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 transfering * metadata between an <code>ImageReader</code> and an * <code>ImageWriter</code> for different image formats. To convert * between two native formats as losslessly as the image file formats * will allow, an <code>ImageTranscoder</code> 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</code> and set via the constructor. */ protected String nativeMetadataFormatName = null; /** * The name of the class implementing <code>IIOMetadataFormat</code> * and representing the native metadata format, initialized to * <code>null</code> 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</code> and set via the constructor. */ protected String[] extraMetadataFormatNames = null; /** * An array of names of classes implementing <code>IIOMetadataFormat</code> * and representing the metadata formats, other than the standard and * native formats, that are supported by this plug-in, * initialized to <code>null</code> and set via the constructor. */ protected String[] extraMetadataFormatClassNames = null; /** * An <code>IIOMetadataController</code> that is suggested for use * as the controller for this <code>IIOMetadata</code> object. It * may be retrieved via <code>getDefaultController</code>. To * install the default controller, call * <code>setController(getDefaultController())</code>. 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</code> that will be * used to provide settings for this <code>IIOMetadata</code> * object when the <code>activateController</code> method * is called. This value overrides any default controller, * even when <code>null</code>. * * @see IIOMetadataController * @see #setController(IIOMetadataController) * @see #hasController() * @see #activateController() */ protected IIOMetadataController controller = null; /** * Constructs an empty <code>IIOMetadata</code> object. The * subclass is responsible for suppying values for all protected * instance variables that will allow any non-overridden default * implemtations of methods to satisfy their contracts. For example, * <code>extraMetadataFormatNames</code> should not have length 0. */ protected IIOMetadata() {} /** * Constructs an <code>IIOMetadata</code> 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</code>. * * @param standardMetadataFormatSupported <code>true</code> 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</code>, or <code>null</code> if there * is no native format. * @param nativeMetadataFormatClassName the name of the class of * the native metadata format, or <code>null</code> if there is * no native format. * @param extraMetadataFormatNames an array of <code>String</code>s * indicating additional formats supported by this object, or * <code>null</code> if there are none. * @param extraMetadataFormatClassNames an array of <code>String</code>s * indicating the class names of any additional formats supported by * this object, or <code>null</code> if there are none. * * @exception IllegalArgumentException if * <code>extraMetadataFormatNames</code> has length 0. * @exception IllegalArgumentException if * <code>extraMetadataFormatNames</code> and * <code>extraMetadataFormatClassNames</code> are neither both * <code>null</code>, 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 = (String[]) extraMetadataFormatNames.clone(); this.extraMetadataFormatClassNames = (String[]) extraMetadataFormatClassNames.clone(); } else { if (extraMetadataFormatClassNames != null) { throw new IllegalArgumentException ("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 * is supported. * * @see #getAsTree * @see #setFromTree * @see #mergeTree * @see #getMetadataFormat */ public boolean isStandardMetadataFormatSupported() { return standardFormatSupported; } /** * 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 * 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</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 */ public String getNativeMetadataFormatName() { return nativeMetadataFormatName; } /** * 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 #getAsTree * @see #setFromTree * @see #mergeTree * @see #getNativeMetadataFormatName * @see #getMetadataFormatNames */ public String[] getExtraMetadataFormatNames() { if (extraMetadataFormatNames == null) { return null; } return (String[])extraMetadataFormatNames.clone(); } /** * 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 * combined results. * * @return an array of <code>String</code>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</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 * 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 { Class cls = null; final Object o = this; // firstly we try to use classloader used for loading // the IIOMetadata implemantation for this plugin. ClassLoader loader = (ClassLoader) java.security.AccessController.doPrivileged( new java.security.PrivilegedAction() { public Object run() { return o.getClass().getClassLoader(); } }); try { cls = Class.forName(formatClassName, true, loader); } catch (ClassNotFoundException e) { // we failed to load IIOMetadataFormat class by // using IIOMetadata classloader.Next try is to // use thread context classloader. loader = (ClassLoader) java.security.AccessController.doPrivileged( new java.security.PrivilegedAction() { public Object run() { return Thread.currentThread().getContextClassLoader(); } }); try { cls = Class.forName(formatClassName, true, loader); } catch (ClassNotFoundException e1) { // finally we try to use system classloader in case // if we failed to load IIOMetadataFormat implementation // class above. cls = Class.forName(formatClassName, true, ClassLoader.getSystemClassLoader()); } } 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; } } /** * 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 * format. * * <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 * root of a tree. * * @exception IllegalArgumentException if <code>formatName</code> * is <code>null</code> or is not one of the names returned by * <code>getMetadataFormatNames</code>. * * @see #getMetadataFormatNames * @see #setFromTree * @see #mergeTree */ public abstract Node getAsTree(String formatName); /** * 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 * 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</code> object forming the * root of a tree. * * @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 * <code>null</code>. * @exception IIOInvalidTreeException if the tree cannot be parsed * successfully using the rules of the given format.Lines 1–500 of 900. Load more
/* * Copyright (c) 2000, 2005, 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; /** * 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</code> 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</code>. 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 transfering * metadata between an <code>ImageReader</code> and an * <code>ImageWriter</code> for different image formats. To convert * between two native formats as losslessly as the image file formats * will allow, an <code>ImageTranscoder</code> 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</code> and set via the constructor. */ protected String nativeMetadataFormatName = null; /** * The name of the class implementing <code>IIOMetadataFormat</code> * and representing the native metadata format, initialized to * <code>null</code> 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</code> and set via the constructor. */ protected String[] extraMetadataFormatNames = null; /** * An array of names of classes implementing <code>IIOMetadataFormat</code> * and representing the metadata formats, other than the standard and * native formats, that are supported by this plug-in, * initialized to <code>null</code> and set via the constructor. */ protected String[] extraMetadataFormatClassNames = null; /** * An <code>IIOMetadataController</code> that is suggested for use * as the controller for this <code>IIOMetadata</code> object. It * may be retrieved via <code>getDefaultController</code>. To * install the default controller, call * <code>setController(getDefaultController())</code>. 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</code> that will be * used to provide settings for this <code>IIOMetadata</code> * object when the <code>activateController</code> method * is called. This value overrides any default controller, * even when <code>null</code>. * * @see IIOMetadataController * @see #setController(IIOMetadataController) * @see #hasController() * @see #activateController() */ protected IIOMetadataController controller = null; /** * Constructs an empty <code>IIOMetadata</code> object. The * subclass is responsible for suppying values for all protected * instance variables that will allow any non-overridden default * implemtations of methods to satisfy their contracts. For example, * <code>extraMetadataFormatNames</code> should not have length 0. */ protected IIOMetadata() {} /** * Constructs an <code>IIOMetadata</code> 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</code>. * * @param standardMetadataFormatSupported <code>true</code> 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</code>, or <code>null</code> if there * is no native format. * @param nativeMetadataFormatClassName the name of the class of * the native metadata format, or <code>null</code> if there is * no native format. * @param extraMetadataFormatNames an array of <code>String</code>s * indicating additional formats supported by this object, or * <code>null</code> if there are none. * @param extraMetadataFormatClassNames an array of <code>String</code>s * indicating the class names of any additional formats supported by * this object, or <code>null</code> if there are none. * * @exception IllegalArgumentException if * <code>extraMetadataFormatNames</code> has length 0. * @exception IllegalArgumentException if * <code>extraMetadataFormatNames</code> and * <code>extraMetadataFormatClassNames</code> are neither both * <code>null</code>, 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 = (String[]) extraMetadataFormatNames.clone(); this.extraMetadataFormatClassNames = (String[]) extraMetadataFormatClassNames.clone(); } else { if (extraMetadataFormatClassNames != null) { throw new IllegalArgumentException ("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 * is supported. * * @see #getAsTree * @see #setFromTree * @see #mergeTree * @see #getMetadataFormat */ public boolean isStandardMetadataFormatSupported() { return standardFormatSupported; } /** * 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 * 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</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 */ public String getNativeMetadataFormatName() { return nativeMetadataFormatName; } /** * 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 #getAsTree * @see #setFromTree * @see #mergeTree * @see #getNativeMetadataFormatName * @see #getMetadataFormatNames */ public String[] getExtraMetadataFormatNames() { if (extraMetadataFormatNames == null) { return null; } return (String[])extraMetadataFormatNames.clone(); } /** * 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 * combined results. * * @return an array of <code>String</code>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</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 * 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 { Class cls = null; final Object o = this; // firstly we try to use classloader used for loading // the IIOMetadata implemantation for this plugin. ClassLoader loader = (ClassLoader) java.security.AccessController.doPrivileged( new java.security.PrivilegedAction() { public Object run() { return o.getClass().getClassLoader(); } }); try { cls = Class.forName(formatClassName, true, loader); } catch (ClassNotFoundException e) { // we failed to load IIOMetadataFormat class by // using IIOMetadata classloader.Next try is to // use thread context classloader. loader = (ClassLoader) java.security.AccessController.doPrivileged( new java.security.PrivilegedAction() { public Object run() { return Thread.currentThread().getContextClassLoader(); } }); try { cls = Class.forName(formatClassName, true, loader); } catch (ClassNotFoundException e1) { // finally we try to use system classloader in case // if we failed to load IIOMetadataFormat implementation // class above. cls = Class.forName(formatClassName, true, ClassLoader.getSystemClassLoader()); } } 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; } } /** * 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 * format. * * <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 * root of a tree. * * @exception IllegalArgumentException if <code>formatName</code> * is <code>null</code> or is not one of the names returned by * <code>getMetadataFormatNames</code>. * * @see #getMetadataFormatNames * @see #setFromTree * @see #mergeTree */ public abstract Node getAsTree(String formatName); /** * 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 * 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</code> object forming the * root of a tree. * * @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 * <code>null</code>. * @exception IIOInvalidTreeException if the tree cannot be parsed * successfully using the rules of the given format.