| /* |
| * 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.spi; |
| |
| import java.io.IOException; |
| import java.lang.reflect.Constructor; |
| import java.lang.reflect.Method; |
| import java.util.Arrays; |
| import java.util.Iterator; |
| import javax.imageio.ImageReader; |
| import javax.imageio.metadata.IIOMetadata; |
| import javax.imageio.metadata.IIOMetadataFormat; |
| import javax.imageio.metadata.IIOMetadataFormatImpl; |
| import javax.imageio.stream.ImageInputStream; |
| |
| /** |
| * A superclass containing instance variables and methods common to |
| * <code>ImageReaderSpi</code> and <code>ImageWriterSpi</code>. |
| * |
| * @see IIORegistry |
| * @see ImageReaderSpi |
| * @see ImageWriterSpi |
| * |
| */ |
| public abstract class ImageReaderWriterSpi extends IIOServiceProvider { |
| |
| /** |
| * An array of strings to be returned from |
| * <code>getFormatNames</code>, initially <code>null</code>. |
| * Constructors should set this to a non-<code>null</code> value. |
| */ |
| protected String[] names = null; |
| |
| /** |
| * An array of strings to be returned from |
| * <code>getFileSuffixes</code>, initially <code>null</code>. |
| */ |
| protected String[] suffixes = null; |
| |
| /** |
| * An array of strings to be returned from |
| * <code>getMIMETypes</code>, initially <code>null</code>. |
| */ |
| protected String[] MIMETypes = null; |
| |
| /** |
| * A <code>String</code> containing the name of the associated |
| * plug-in class, initially <code>null</code>. |
| */ |
| protected String pluginClassName = null; |
| |
| /** |
| * A boolean indicating whether this plug-in supports the |
| * standard metadata format for stream metadata, initially |
| * <code>false</code>. |
| */ |
| protected boolean supportsStandardStreamMetadataFormat = false; |
| |
| /** |
| * A <code>String</code> containing the name of the native stream |
| * metadata format supported by this plug-in, initially |
| * <code>null</code>. |
| */ |
| protected String nativeStreamMetadataFormatName = null; |
| |
| /** |
| * A <code>String</code> containing the class name of the native |
| * stream metadata format supported by this plug-in, initially |
| * <code>null</code>. |
| */ |
| protected String nativeStreamMetadataFormatClassName = null; |
| |
| /** |
| * An array of <code>String</code>s containing the names of any |
| * additional stream metadata formats supported by this plug-in, |
| * initially <code>null</code>. |
| */ |
| protected String[] extraStreamMetadataFormatNames = null; |
| |
| /** |
| * An array of <code>String</code>s containing the class names of |
| * any additional stream metadata formats supported by this plug-in, |
| * initially <code>null</code>. |
| */ |
| protected String[] extraStreamMetadataFormatClassNames = null; |
| |
| /** |
| * A boolean indicating whether this plug-in supports the |
| * standard metadata format for image metadata, initially |
| * <code>false</code>. |
| */ |
| protected boolean supportsStandardImageMetadataFormat = false; |
| |
| /** |
| * A <code>String</code> containing the name of the |
| * native stream metadata format supported by this plug-in, |
| * initially <code>null</code>. |
| */ |
| protected String nativeImageMetadataFormatName = null; |
| |
| /** |
| * A <code>String</code> containing the class name of the |
| * native stream metadata format supported by this plug-in, |
| * initially <code>null</code>. |
| */ |
| protected String nativeImageMetadataFormatClassName = null; |
| |
| /** |
| * An array of <code>String</code>s containing the names of any |
| * additional image metadata formats supported by this plug-in, |
| * initially <code>null</code>. |
| */ |
| protected String[] extraImageMetadataFormatNames = null; |
| |
| /** |
| * An array of <code>String</code>s containing the class names of |
| * any additional image metadata formats supported by this |
| * plug-in, initially <code>null</code>. |
| */ |
| protected String[] extraImageMetadataFormatClassNames = null; |
| |
| /** |
| * Constructs an <code>ImageReaderWriterSpi</code> with a given |
| * set of values. |
| * |
| * @param vendorName the vendor name, as a non-<code>null</code> |
| * <code>String</code>. |
| * @param version a version identifier, as a non-<code>null</code> |
| * <code>String</code>. |
| * @param names a non-<code>null</code> array of |
| * <code>String</code>s indicating the format names. At least one |
| * entry must be present. |
| * @param suffixes an array of <code>String</code>s indicating the |
| * common file suffixes. If no suffixes are defined, |
| * <code>null</code> should be supplied. An array of length 0 |
| * will be normalized to <code>null</code>. |
| * @param MIMETypes an array of <code>String</code>s indicating |
| * the format's MIME types. If no MIME types are defined, |
| * <code>null</code> should be supplied. An array of length 0 |
| * will be normalized to <code>null</code>. |
| * @param pluginClassName the fully-qualified name of the |
| * associated <code>ImageReader</code> or <code>ImageWriter</code> |
| * class, as a non-<code>null</code> <code>String</code>. |
| * @param supportsStandardStreamMetadataFormat a |
| * <code>boolean</code> that indicates whether a stream metadata |
| * object can use trees described by the standard metadata format. |
| * @param nativeStreamMetadataFormatName a |
| * <code>String</code>, or <code>null</code>, to be returned from |
| * <code>getNativeStreamMetadataFormatName</code>. |
| * @param nativeStreamMetadataFormatClassName a |
| * <code>String</code>, or <code>null</code>, to be used to instantiate |
| * a metadata format object to be returned from |
| * <code>getNativeStreamMetadataFormat</code>. |
| * @param extraStreamMetadataFormatNames an array of |
| * <code>String</code>s, or <code>null</code>, to be returned from |
| * <code>getExtraStreamMetadataFormatNames</code>. An array of length |
| * 0 is normalized to <code>null</code>. |
| * @param extraStreamMetadataFormatClassNames an array of |
| * <code>String</code>s, or <code>null</code>, to be used to instantiate |
| * a metadata format object to be returned from |
| * <code>getStreamMetadataFormat</code>. An array of length |
| * 0 is normalized to <code>null</code>. |
| * @param supportsStandardImageMetadataFormat a |
| * <code>boolean</code> that indicates whether an image metadata |
| * object can use trees described by the standard metadata format. |
| * @param nativeImageMetadataFormatName a |
| * <code>String</code>, or <code>null</code>, to be returned from |
| * <code>getNativeImageMetadataFormatName</code>. |
| * @param nativeImageMetadataFormatClassName a |
| * <code>String</code>, or <code>null</code>, to be used to instantiate |
| * a metadata format object to be returned from |
| * <code>getNativeImageMetadataFormat</code>. |
| * @param extraImageMetadataFormatNames an array of |
| * <code>String</code>s to be returned from |
| * <code>getExtraImageMetadataFormatNames</code>. An array of length 0 |
| * is normalized to <code>null</code>. |
| * @param extraImageMetadataFormatClassNames an array of |
| * <code>String</code>s, or <code>null</code>, to be used to instantiate |
| * a metadata format object to be returned from |
| * <code>getImageMetadataFormat</code>. An array of length |
| * 0 is normalized to <code>null</code>. |
| * |
| * @exception IllegalArgumentException if <code>vendorName</code> |
| * is <code>null</code>. |
| * @exception IllegalArgumentException if <code>version</code> |
| * is <code>null</code>. |
| * @exception IllegalArgumentException if <code>names</code> |
| * is <code>null</code> or has length 0. |
| * @exception IllegalArgumentException if <code>pluginClassName</code> |
| * is <code>null</code>. |
| */ |
| public ImageReaderWriterSpi(String vendorName, |
| String version, |
| String[] names, |
| String[] suffixes, |
| String[] MIMETypes, |
| String pluginClassName, |
| boolean supportsStandardStreamMetadataFormat, |
| String nativeStreamMetadataFormatName, |
| String nativeStreamMetadataFormatClassName, |
| String[] extraStreamMetadataFormatNames, |
| String[] extraStreamMetadataFormatClassNames, |
| boolean supportsStandardImageMetadataFormat, |
| String nativeImageMetadataFormatName, |
| String nativeImageMetadataFormatClassName, |
| String[] extraImageMetadataFormatNames, |
| String[] extraImageMetadataFormatClassNames) { |
| super(vendorName, version); |
| if (names == null) { |
| throw new IllegalArgumentException("names == null!"); |
| } |
| if (names.length == 0) { |
| throw new IllegalArgumentException("names.length == 0!"); |
| } |
| if (pluginClassName == null) { |
| throw new IllegalArgumentException("pluginClassName == null!"); |
| } |
| |
| this.names = (String[])names.clone(); |
| // If length == 0, leave it null |
| if (suffixes != null && suffixes.length > 0) { |
| this.suffixes = (String[])suffixes.clone(); |
| } |
| // If length == 0, leave it null |
| if (MIMETypes != null && MIMETypes.length > 0) { |
| this.MIMETypes = (String[])MIMETypes.clone(); |
| } |
| this.pluginClassName = pluginClassName; |
| |
| this.supportsStandardStreamMetadataFormat = |
| supportsStandardStreamMetadataFormat; |
| this.nativeStreamMetadataFormatName = nativeStreamMetadataFormatName; |
| this.nativeStreamMetadataFormatClassName = |
| nativeStreamMetadataFormatClassName; |
| // If length == 0, leave it null |
| if (extraStreamMetadataFormatNames != null && |
| extraStreamMetadataFormatNames.length > 0) { |
| this.extraStreamMetadataFormatNames = |
| (String[])extraStreamMetadataFormatNames.clone(); |
| } |
| // If length == 0, leave it null |
| if (extraStreamMetadataFormatClassNames != null && |
| extraStreamMetadataFormatClassNames.length > 0) { |
| this.extraStreamMetadataFormatClassNames = |
| (String[])extraStreamMetadataFormatClassNames.clone(); |
| } |
| this.supportsStandardImageMetadataFormat = |
| supportsStandardImageMetadataFormat; |
| this.nativeImageMetadataFormatName = nativeImageMetadataFormatName; |
| this.nativeImageMetadataFormatClassName = |
| nativeImageMetadataFormatClassName; |
| // If length == 0, leave it null |
| if (extraImageMetadataFormatNames != null && |
| extraImageMetadataFormatNames.length > 0) { |
| this.extraImageMetadataFormatNames = |
| (String[])extraImageMetadataFormatNames.clone(); |
| } |
| // If length == 0, leave it null |
| if (extraImageMetadataFormatClassNames != null && |
| extraImageMetadataFormatClassNames.length > 0) { |
| this.extraImageMetadataFormatClassNames = |
| (String[])extraImageMetadataFormatClassNames.clone(); |
| } |
| } |
| |
| /** |
| * Constructs a blank <code>ImageReaderWriterSpi</code>. It is up |
| * to the subclass to initialize instance variables and/or |
| * override method implementations in order to provide working |
| * versions of all methods. |
| */ |
| public ImageReaderWriterSpi() { |
| } |
| |
| /** |
| * Returns an array of <code>String</code>s containing |
| * human-readable names for the formats that are generally usable |
| * by the <code>ImageReader</code> or <code>ImageWriter</code> |
| * implementation associated with this service provider. For |
| * example, a single <code>ImageReader</code> might be able to |
| * process both PBM and PNM files. |
| * |
| * @return a non-<code>null</code> array of <code>String</code>s |
| * or length at least 1 containing informal format names |
| * associated with this reader or writer. |
| */ |
| public String[] getFormatNames() { |
| return (String[])names.clone(); |
| } |
| |
| /** |
| * Returns an array of <code>String</code>s containing a list of |
| * file suffixes associated with the formats that are generally |
| * usable by the <code>ImageReader</code> or |
| * <code>ImageWriter</code> implementation associated with this |
| * service provider. For example, a single |
| * <code>ImageReader</code> might be able to process files with |
| * '.pbm' and '.pnm' suffixes, or both '.jpg' and '.jpeg' |
| * suffixes. If there are no known file suffixes, |
| * <code>null</code> will be returned. |
| * |
| * <p> Returning a particular suffix does not guarantee that files |
| * with that suffix can be processed; it merely indicates that it |
| * may be worthwhile attempting to decode or encode such files |
| * using this service provider. |
| * |
| * @return an array of <code>String</code>s or length at least 1 |
| * containing common file suffixes associated with this reader or |
| * writer, or <code>null</code>. |
| */ |
| public String[] getFileSuffixes() { |
| return suffixes == null ? null : (String[])suffixes.clone(); |
| } |
| |
| /** |
| * Returns an array of <code>String</code>s containing a list of |
| * MIME types associated with the formats that are generally |
| * usable by the <code>ImageReader</code> or |
| * <code>ImageWriter</code> implementation associated with this |
| * service provider. |
| * |
| * <p> Ideally, only a single MIME type would be required in order |
| * to describe a particular format. However, for several reasons |
| * it is necessary to associate a list of types with each service |
| * provider. First, many common image file formats do not have |
| * standard MIME types, so a list of commonly used unofficial |
| * names will be required, such as <code>image/x-pbm</code> and |
| * <code>image/x-portable-bitmap</code>. Some file formats have |
| * official MIME types but may sometimes be referred to using |
| * their previous unofficial designations, such as |
| * <code>image/x-png</code> instead of the official |
| * <code>image/png</code>. Finally, a single service provider may |
| * be capable of parsing multiple distinct types from the MIME |
| * point of view, for example <code>image/x-xbitmap</code> and |
| * <code>image/x-xpixmap</code>. |
| * |
| * <p> Returning a particular MIME type does not guarantee that |
| * files claiming to be of that type can be processed; it merely |
| * indicates that it may be worthwhile attempting to decode or |
| * encode such files using this service provider. |
| * |
| * @return an array of <code>String</code>s or length at least 1 |
| * containing MIME types associated with this reader or writer, or |
| * <code>null</code>. |
| */ |
| public String[] getMIMETypes() { |
| return MIMETypes == null ? null : (String[])MIMETypes.clone(); |
| } |
| |
| /** |
| * Returns the fully-qualified class name of the |
| * <code>ImageReader</code> or <code>ImageWriter</code> plug-in |
| * associated with this service provider. |
| * |
| * @return the class name, as a non-<code>null</code> |
| * <code>String</code>. |
| */ |
| public String getPluginClassName() { |
| return pluginClassName; |
| } |
| |
| /** |
| * Returns <code>true</code> if the standard metadata format is |
| * among the document formats recognized by the |
| * <code>getAsTree</code> and <code>setFromTree</code> methods on |
| * the stream metadata objects produced or consumed by this |
| * plug-in. |
| * |
| * @return <code>true</code> if the standard format is supported |
| * for stream metadata. |
| */ |
| public boolean isStandardStreamMetadataFormatSupported() { |
| return supportsStandardStreamMetadataFormat; |
| } |
| |
| /** |
| * Returns the name of the "native" stream metadata format for |
| * this plug-in, which typically allows for lossless encoding and |
| * transmission of the stream metadata stored in the format handled by |
| * this plug-in. If no such format is supported, |
| * <code>null</code>will be returned. |
| * |
| * <p> The default implementation returns the |
| * <code>nativeStreamMetadataFormatName</code> instance variable, |
| * which is typically set by the constructor. |
| * |
| * @return the name of the native stream metadata format, or |
| * <code>null</code>. |
| * |
| */ |
| public String getNativeStreamMetadataFormatName() { |
| return nativeStreamMetadataFormatName; |
| } |
| |
| /** |
| * Returns an array of <code>String</code>s containing the names |
| * of additional document formats, other than the native and |
| * standard formats, recognized by the |
| * <code>getAsTree</code> and <code>setFromTree</code> methods on |
| * the stream metadata objects produced or consumed by this |
| * plug-in. |
| * |
| * <p> If the plug-in does not handle metadata, null should be |
| * returned. |
| * |
| * <p> The set of formats may differ according to the particular |
| * images being read or written; this method should indicate all |
| * the additional formats supported by the plug-in under any |
| * circumstances. |
| * |
| * <p> The default implementation returns a clone of the |
| * <code>extraStreamMetadataFormatNames</code> instance variable, |
| * which is typically set by the constructor. |
| * |
| * @return an array of <code>String</code>s, or null. |
| * |
| * @see IIOMetadata#getMetadataFormatNames |
| * @see #getExtraImageMetadataFormatNames |
| * @see #getNativeStreamMetadataFormatName |
| */ |
| public String[] getExtraStreamMetadataFormatNames() { |
| return extraStreamMetadataFormatNames == null ? |
| null : (String[])extraStreamMetadataFormatNames.clone(); |
| } |
| |
| /** |
| * Returns <code>true</code> if the standard metadata format is |
| * among the document formats recognized by the |
| * <code>getAsTree</code> and <code>setFromTree</code> methods on |
| * the image metadata objects produced or consumed by this |
| * plug-in. |
| * |
| * @return <code>true</code> if the standard format is supported |
| * for image metadata. |
| */ |
| public boolean isStandardImageMetadataFormatSupported() { |
| return supportsStandardImageMetadataFormat; |
| } |
| |
| /** |
| * Returns the name of the "native" image metadata format for |
| * this plug-in, which typically allows for lossless encoding and |
| * transmission of the image metadata stored in the format handled by |
| * this plug-in. If no such format is supported, |
| * <code>null</code>will be returned. |
| * |
| * <p> The default implementation returns the |
| * <code>nativeImageMetadataFormatName</code> instance variable, |
| * which is typically set by the constructor. |
| * |
| * @return the name of the native image metadata format, or |
| * <code>null</code>. |
| * |
| * @see #getExtraImageMetadataFormatNames |
| */ |
| public String getNativeImageMetadataFormatName() { |
| return nativeImageMetadataFormatName; |
| } |
| |
| /** |
| * Returns an array of <code>String</code>s containing the names |
| * of additional document formats, other than the native and |
| * standard formats, recognized by the |
| * <code>getAsTree</code> and <code>setFromTree</code> methods on |
| * the image metadata objects produced or consumed by this |
| * plug-in. |
| * |
| * <p> If the plug-in does not handle image metadata, null should |
| * be returned. |
| * |
| * <p> The set of formats may differ according to the particular |
| * images being read or written; this method should indicate all |
| * the additional formats supported by the plug-in under any circumstances. |
| * |
| * <p> The default implementation returns a clone of the |
| * <code>extraImageMetadataFormatNames</code> instance variable, |
| * which is typically set by the constructor. |
| * |
| * @return an array of <code>String</code>s, or null. |
| * |
| * @see IIOMetadata#getMetadataFormatNames |
| * @see #getExtraStreamMetadataFormatNames |
| * @see #getNativeImageMetadataFormatName |
| */ |
| public String[] getExtraImageMetadataFormatNames() { |
| return extraImageMetadataFormatNames == null ? |
| null : (String[])extraImageMetadataFormatNames.clone(); |
| } |
| |
| /** |
| * Returns an <code>IIOMetadataFormat</code> object describing the |
| * given stream metadata format, or <code>null</code> if no |
| * description is available. The supplied name must be the native |
| * stream metadata format name, the standard metadata format name, |
| * or one of those returned by |
| * <code>getExtraStreamMetadataFormatNames</code>. |
| * |
| * @param formatName the desired stream metadata format. |
| * |
| * @return an <code>IIOMetadataFormat</code> object. |
| * |
| * @exception IllegalArgumentException if <code>formatName</code> |
| * is <code>null</code> or is not a supported name. |
| */ |
| public IIOMetadataFormat getStreamMetadataFormat(String formatName) { |
| return getMetadataFormat(formatName, |
| supportsStandardStreamMetadataFormat, |
| nativeStreamMetadataFormatName, |
| nativeStreamMetadataFormatClassName, |
| extraStreamMetadataFormatNames, |
| extraStreamMetadataFormatClassNames); |
| } |
| |
| /** |
| * Returns an <code>IIOMetadataFormat</code> object describing the |
| * given image metadata format, or <code>null</code> if no |
| * description is available. The supplied name must be the native |
| * iamge metadata format name, the standard metadata format name, |
| * or one of those returned by |
| * <code>getExtraImageMetadataFormatNames</code>. |
| * |
| * @param formatName the desired image metadata format. |
| * |
| * @return an <code>IIOMetadataFormat</code> object. |
| * |
| * @exception IllegalArgumentException if <code>formatName</code> |
| * is <code>null</code> or is not a supported name. |
| */ |
| public IIOMetadataFormat getImageMetadataFormat(String formatName) { |
| return getMetadataFormat(formatName, |
| supportsStandardImageMetadataFormat, |
| nativeImageMetadataFormatName, |
| nativeImageMetadataFormatClassName, |
| extraImageMetadataFormatNames, |
| extraImageMetadataFormatClassNames); |
| } |
| |
| private IIOMetadataFormat getMetadataFormat(String formatName, |
| boolean supportsStandard, |
| String nativeName, |
| String nativeClassName, |
| String [] extraNames, |
| String [] extraClassNames) { |
| if (formatName == null) { |
| throw new IllegalArgumentException("formatName == null!"); |
| } |
| if (supportsStandard && formatName.equals |
| (IIOMetadataFormatImpl.standardMetadataFormatName)) { |
| |
| return IIOMetadataFormatImpl.getStandardFormatInstance(); |
| } |
| String formatClassName = null; |
| if (formatName.equals(nativeName)) { |
| formatClassName = nativeClassName; |
| } else if (extraNames != null) { |
| for (int i = 0; i < extraNames.length; i++) { |
| if (formatName.equals(extraNames[i])) { |
| formatClassName = extraClassNames[i]; |
| break; // out of for |
| } |
| } |
| } |
| if (formatClassName == null) { |
| throw new IllegalArgumentException("Unsupported format name"); |
| } |
| try { |
| Class 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; |
| } |
| } |
| } |
