| /* |
| * Copyright (c) 1999, 2001, 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(); |
| } |
| } |