Back to index...

	/*
	* Copyright (c) 1999, 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.awt.image.RenderedImage;
	import java.io.IOException;
	import javax.imageio.ImageTypeSpecifier;
	import javax.imageio.ImageWriter;
	import javax.imageio.stream.ImageOutputStream;

	/**
	* The service provider interface (SPI) for <code>ImageWriter</code>s.
	* For more information on service provider classes, see the class comment
	* for the <code>IIORegistry</code> class.
	*
	* <p> Each <code>ImageWriterSpi</code> provides several types of information
	* about the <code>ImageWriter</code> class with which it is associated.
	*
	* <p> The name of the vendor who defined the SPI class and a
	* brief description of the class are available via the
	* <code>getVendorName</code>, <code>getDescription</code>,
	* and <code>getVersion</code> methods.
	* These methods may be internationalized to provide locale-specific
	* output. These methods are intended mainly to provide short,
	* human-writable information that might be used to organize a pop-up
	* menu or other list.
	*
	* <p> Lists of format names, file suffixes, and MIME types associated
	* with the service may be obtained by means of the
	* <code>getFormatNames</code>, <code>getFileSuffixes</code>, and
	* <code>getMIMEType</code> methods. These methods may be used to
	* identify candidate <code>ImageWriter</code>s for writing a
	* particular file or stream based on manual format selection, file
	* naming, or MIME associations.
	*
	* <p> A more reliable way to determine which <code>ImageWriter</code>s
	* are likely to be able to parse a particular data stream is provided
	* by the <code>canEncodeImage</code> method. This methods allows the
	* service provider to inspect the actual image contents.
	*
	* <p> Finally, an instance of the <code>ImageWriter</code> class
	* associated with this service provider may be obtained by calling
	* the <code>createWriterInstance</code> method. Any heavyweight
	* initialization, such as the loading of native libraries or creation
	* of large tables, should be deferred at least until the first
	* invocation of this method.
	*
	* @see IIORegistry
	* @see javax.imageio.ImageTypeSpecifier
	* @see javax.imageio.ImageWriter
	*
	*/
	public abstract class ImageWriterSpi extends ImageReaderWriterSpi {

	/**
	* A single-element array, initially containing
	* <code>ImageOutputStream.class</code>, to be returned from
	* <code>getOutputTypes</code>.
	* @deprecated Instead of using this field, directly create
	* the equivalent array <code>{ ImageOutputStream.class }</code>.
	*/
	@Deprecated
	public static final Class[] STANDARD_OUTPUT_TYPE =
	{ ImageOutputStream.class };

	/**
	* An array of <code>Class</code> objects to be returned from
	* <code>getOutputTypes</code>, initially <code>null</code>.
	*/
	protected Class[] outputTypes = null;

	/**
	* An array of strings to be returned from
	* <code>getImageReaderSpiNames</code>, initially
	* <code>null</code>.
	*/
	protected String[] readerSpiNames = null;

	/**
	* The <code>Class</code> of the writer, initially
	* <code>null</code>.
	*/
	private Class writerClass = null;

	/**
	* Constructs a blank <code>ImageWriterSpi</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.
	*/
	protected ImageWriterSpi() {
	}

	/**
	* Constructs an <code>ImageWriterSpi</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 suffixes are defined,
	* <code>null</code> should be supplied. An array of length 0
	* will be normalized to <code>null</code>.
	* @param writerClassName the fully-qualified name of the
	* associated <code>ImageWriterSpi</code> class, as a
	* non-<code>null</code> <code>String</code>.
	* @param outputTypes an array of <code>Class</code> objects of
	* length at least 1 indicating the legal output types.
	* @param readerSpiNames an array <code>String</code>s of length
	* at least 1 naming the classes of all associated
	* <code>ImageReader</code>s, or <code>null</code>. An array of
	* length 0 is normalized to <code>null</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>writerClassName</code>
	* is <code>null</code>.
	* @exception IllegalArgumentException if <code>outputTypes</code>
	* is <code>null</code> or has length 0.
	*/
	public ImageWriterSpi(String vendorName,
	String version,
	String[] names,
	String[] suffixes,
	String[] MIMETypes,
	String writerClassName,
	Class[] outputTypes,
	String[] readerSpiNames,
	boolean supportsStandardStreamMetadataFormat,
	String nativeStreamMetadataFormatName,
	String nativeStreamMetadataFormatClassName,
	String[] extraStreamMetadataFormatNames,
	String[] extraStreamMetadataFormatClassNames,
	boolean supportsStandardImageMetadataFormat,
	String nativeImageMetadataFormatName,
	String nativeImageMetadataFormatClassName,
	String[] extraImageMetadataFormatNames,
	String[] extraImageMetadataFormatClassNames) {
	super(vendorName, version,
	names, suffixes, MIMETypes, writerClassName,
	supportsStandardStreamMetadataFormat,
	nativeStreamMetadataFormatName,
	nativeStreamMetadataFormatClassName,
	extraStreamMetadataFormatNames,
	extraStreamMetadataFormatClassNames,
	supportsStandardImageMetadataFormat,
	nativeImageMetadataFormatName,
	nativeImageMetadataFormatClassName,
	extraImageMetadataFormatNames,
	extraImageMetadataFormatClassNames);

	if (outputTypes == null) {
	throw new IllegalArgumentException
	("outputTypes == null!");
	}
	if (outputTypes.length == 0) {
	throw new IllegalArgumentException
	("outputTypes.length == 0!");
	}

	this.outputTypes = (outputTypes == STANDARD_OUTPUT_TYPE) ?
	new Class<?>[] { ImageOutputStream.class } :
	outputTypes.clone();

	// If length == 0, leave it null
	if (readerSpiNames != null && readerSpiNames.length > 0) {
	this.readerSpiNames = (String[])readerSpiNames.clone();
	}
	}

	/**
	* Returns <code>true</code> if the format that this writer
	* outputs preserves pixel data bit-accurately. The default
	* implementation returns <code>true</code>.
	*
	* @return <code>true</code> if the format preserves full pixel
	* accuracy.
	*/
	public boolean isFormatLossless() {
	return true;
	}

	/**
	* Returns an array of <code>Class</code> objects indicating what
	* types of objects may be used as arguments to the writer's
	* <code>setOutput</code> method.
	*
	* <p> For most writers, which only output to an
	* <code>ImageOutputStream</code>, a single-element array
	* containing <code>ImageOutputStream.class</code> should be
	* returned.
	*
	* @return a non-<code>null</code> array of
	* <code>Class</code>objects of length at least 1.
	*/
	public Class[] getOutputTypes() {
	return (Class[])outputTypes.clone();
	}

	/**
	* Returns <code>true</code> if the <code>ImageWriter</code>
	* implementation associated with this service provider is able to
	* encode an image with the given layout. The layout
	* (<i>i.e.</i>, the image's <code>SampleModel</code> and
	* <code>ColorModel</code>) is described by an
	* <code>ImageTypeSpecifier</code> object.
	*
	* <p> A return value of <code>true</code> is not an absolute
	* guarantee of successful encoding; the encoding process may still
	* produce errors due to factors such as I/O errors, inconsistent
	* or malformed data structures, etc. The intent is that a
	* reasonable inspection of the basic structure of the image be
	* performed in order to determine if it is within the scope of
	* the encoding format. For example, a service provider for a
	* format that can only encode greyscale would return
	* <code>false</code> if handed an RGB <code>BufferedImage</code>.
	* Similarly, a service provider for a format that can encode
	* 8-bit RGB imagery might refuse to encode an image with an
	* associated alpha channel.
	*
	* <p> Different <code>ImageWriter</code>s, and thus service
	* providers, may choose to be more or less strict. For example,
	* they might accept an image with premultiplied alpha even though
	* it will have to be divided out of each pixel, at some loss of
	* precision, in order to be stored.
	*
	* @param type an <code>ImageTypeSpecifier</code> specifying the
	* layout of the image to be written.
	*
	* @return <code>true</code> if this writer is likely to be able
	* to encode images with the given layout.
	*
	* @exception IllegalArgumentException if <code>type</code>
	* is <code>null</code>.
	*/
	public abstract boolean canEncodeImage(ImageTypeSpecifier type);

	/**
	* Returns <code>true</code> if the <code>ImageWriter</code>
	* implementation associated with this service provider is able to
	* encode the given <code>RenderedImage</code> instance. Note
	* that this includes instances of
	* <code>java.awt.image.BufferedImage</code>.
	*
	* <p> See the discussion for
	* <code>canEncodeImage(ImageTypeSpecifier)</code> for information
	* on the semantics of this method.
	*
	* @param im an instance of <code>RenderedImage</code> to be encoded.
	*
	* @return <code>true</code> if this writer is likely to be able
	* to encode this image.
	*
	* @exception IllegalArgumentException if <code>im</code>
	* is <code>null</code>.
	*/
	public boolean canEncodeImage(RenderedImage im) {
	return canEncodeImage(ImageTypeSpecifier.createFromRenderedImage(im));
	}

	/**
	* Returns an instance of the <code>ImageWriter</code>
	* implementation associated with this service provider.
	* The returned object will initially be in an initial state as if
	* its <code>reset</code> method had been called.
	*
	* <p> The default implementation simply returns
	* <code>createWriterInstance(null)</code>.
	*
	* @return an <code>ImageWriter</code> instance.
	*
	* @exception IOException if an error occurs during loading,
	* or initialization of the writer class, or during instantiation
	* or initialization of the writer object.
	*/
	public ImageWriter createWriterInstance() throws IOException {
	return createWriterInstance(null);
	}

	/**
	* Returns an instance of the <code>ImageWriter</code>
	* implementation associated with this service provider.
	* The returned object will initially be in an initial state
	* as if its <code>reset</code> method had been called.
	*
	* <p> An <code>Object</code> may be supplied to the plug-in at
	* construction time. The nature of the object is entirely
	* plug-in specific.
	*
	* <p> Typically, a plug-in will implement this method using code
	* such as <code>return new MyImageWriter(this)</code>.
	*
	* @param extension a plug-in specific extension object, which may
	* be <code>null</code>.
	*
	* @return an <code>ImageWriter</code> instance.
	*
	* @exception IOException if the attempt to instantiate
	* the writer fails.
	* @exception IllegalArgumentException if the
	* <code>ImageWriter</code>'s constructor throws an
	* <code>IllegalArgumentException</code> to indicate that the
	* extension object is unsuitable.
	*/
	public abstract ImageWriter createWriterInstance(Object extension)
	throws IOException;

	/**
	* Returns <code>true</code> if the <code>ImageWriter</code> object
	* passed in is an instance of the <code>ImageWriter</code>
	* associated with this service provider.
	*
	* @param writer an <code>ImageWriter</code> instance.
	*
	* @return <code>true</code> if <code>writer</code> is recognized
	*
	* @exception IllegalArgumentException if <code>writer</code> is
	* <code>null</code>.
	*/
	public boolean isOwnWriter(ImageWriter writer) {
	if (writer == null) {
	throw new IllegalArgumentException("writer == null!");
	}
	String name = writer.getClass().getName();
	return name.equals(pluginClassName);
	}

	/**
	* Returns an array of <code>String</code>s containing all the
	* fully qualified names of all the <code>ImageReaderSpi</code>
	* classes that can understand the internal metadata
	* representation used by the <code>ImageWriter</code> associated
	* with this service provider, or <code>null</code> if there are
	* no such <code>ImageReaders</code> specified. If a
	* non-<code>null</code> value is returned, it must have non-zero
	* length.
	*
	* <p> The first item in the array must be the name of the service
	* provider for the "preferred" reader, as it will be used to
	* instantiate the <code>ImageReader</code> returned by
	* <code>ImageIO.getImageReader(ImageWriter)</code>.
	*
	* <p> This mechanism may be used to obtain
	* <code>ImageReaders</code> that will generated non-pixel
	* meta-data (see <code>IIOExtraDataInfo</code>) in a structure
	* understood by an <code>ImageWriter</code>. By reading the
	* image and obtaining this data from one of the
	* <code>ImageReaders</code> obtained with this method and passing
	* it on to the <code>ImageWriter</code>, a client program can
	* read an image, modify it in some way, and write it back out
	* preserving all meta-data, without having to understand anything
	* about the internal structure of the meta-data, or even about
	* the image format.
	*
	* @return an array of <code>String</code>s of length at least 1
	* containing names of <code>ImageReaderSpi</code>s, or
	* <code>null</code>.
	*
	* @see javax.imageio.ImageIO#getImageReader(ImageWriter)
	* @see ImageReaderSpi#getImageWriterSpiNames()
	*/
	public String[] getImageReaderSpiNames() {
	return readerSpiNames == null ?
	null : (String[])readerSpiNames.clone();
	}
	}

Back to index...