Back to index...

	/*
	* Copyright (c) 2000, 2013, 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
	* image 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;
	}
	}
	}

Back to index...