ImageWriters.
* For more information on service provider classes, see the class comment
* for the IIORegistry class.
*
* Each ImageWriterSpi provides several types of information
* about the ImageWriter class with which it is associated.
*
*
The name of the vendor who defined the SPI class and a
* brief description of the class are available via the
* getVendorName, getDescription,
* and getVersion 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.
*
*
Lists of format names, file suffixes, and MIME types associated
* with the service may be obtained by means of the
* getFormatNames, getFileSuffixes, and
* getMIMEType methods. These methods may be used to
* identify candidate ImageWriters for writing a
* particular file or stream based on manual format selection, file
* naming, or MIME associations.
*
*
A more reliable way to determine which ImageWriters
* are likely to be able to parse a particular data stream is provided
* by the canEncodeImage method. This methods allows the
* service provider to inspect the actual image contents.
*
*
Finally, an instance of the ImageWriter class
* associated with this service provider may be obtained by calling
* the createWriterInstance 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
* ImageOutputStream.class, to be returned from
* getOutputTypes.
* @deprecated Instead of using this field, directly create
* the equivalent array { ImageOutputStream.class }.
*/
@Deprecated
public static final Class[] STANDARD_OUTPUT_TYPE =
{ ImageOutputStream.class };
/**
* An array of Class objects to be returned from
* getOutputTypes, initially null.
*/
protected Class[] outputTypes = null;
/**
* An array of strings to be returned from
* getImageReaderSpiNames, initially
* null.
*/
protected String[] readerSpiNames = null;
/**
* The Class of the writer, initially
* null.
*/
private Class writerClass = null;
/**
* Constructs a blank ImageWriterSpi. 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 ImageWriterSpi with a given
* set of values.
*
* @param vendorName the vendor name, as a non-null
* String.
* @param version a version identifier, as a non-null
* String.
* @param names a non-null array of
* Strings indicating the format names. At least one
* entry must be present.
* @param suffixes an array of Strings indicating the
* common file suffixes. If no suffixes are defined,
* null should be supplied. An array of length 0
* will be normalized to null.
* @param MIMETypes an array of Strings indicating
* the format's MIME types. If no suffixes are defined,
* null should be supplied. An array of length 0
* will be normalized to null.
* @param writerClassName the fully-qualified name of the
* associated ImageWriterSpi class, as a
* non-null String.
* @param outputTypes an array of Class objects of
* length at least 1 indicating the legal output types.
* @param readerSpiNames an array Strings of length
* at least 1 naming the classes of all associated
* ImageReaders, or null. An array of
* length 0 is normalized to null.
* @param supportsStandardStreamMetadataFormat a
* boolean that indicates whether a stream metadata
* object can use trees described by the standard metadata format.
* @param nativeStreamMetadataFormatName a
* String, or null, to be returned from
* getNativeStreamMetadataFormatName.
* @param nativeStreamMetadataFormatClassName a
* String, or null, to be used to instantiate
* a metadata format object to be returned from
* getNativeStreamMetadataFormat.
* @param extraStreamMetadataFormatNames an array of
* Strings, or null, to be returned from
* getExtraStreamMetadataFormatNames. An array of length
* 0 is normalized to null.
* @param extraStreamMetadataFormatClassNames an array of
* Strings, or null, to be used to instantiate
* a metadata format object to be returned from
* getStreamMetadataFormat. An array of length
* 0 is normalized to null.
* @param supportsStandardImageMetadataFormat a
* boolean that indicates whether an image metadata
* object can use trees described by the standard metadata format.
* @param nativeImageMetadataFormatName a
* String, or null, to be returned from
* getNativeImageMetadataFormatName.
* @param nativeImageMetadataFormatClassName a
* String, or null, to be used to instantiate
* a metadata format object to be returned from
* getNativeImageMetadataFormat.
* @param extraImageMetadataFormatNames an array of
* Strings to be returned from
* getExtraImageMetadataFormatNames. An array of length 0
* is normalized to null.
* @param extraImageMetadataFormatClassNames an array of
* Strings, or null, to be used to instantiate
* a metadata format object to be returned from
* getImageMetadataFormat. An array of length
* 0 is normalized to null.
*
* @exception IllegalArgumentException if vendorName
* is null.
* @exception IllegalArgumentException if version
* is null.
* @exception IllegalArgumentException if names
* is null or has length 0.
* @exception IllegalArgumentException if writerClassName
* is null.
* @exception IllegalArgumentException if outputTypes
* is null 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 = readerSpiNames.clone();
}
}
/**
* Returns true if the format that this writer
* outputs preserves pixel data bit-accurately. The default
* implementation returns true.
*
* @return true if the format preserves full pixel
* accuracy.
*/
public boolean isFormatLossless() {
return true;
}
/**
* Returns an array of Class objects indicating what
* types of objects may be used as arguments to the writer's
* setOutput method.
*
*
For most writers, which only output to an
* ImageOutputStream, a single-element array
* containing ImageOutputStream.class should be
* returned.
*
* @return a non-null array of
* Classobjects of length at least 1.
*/
public Class[] getOutputTypes() {
return outputTypes.clone();
}
/**
* Returns true if the ImageWriter
* implementation associated with this service provider is able to
* encode an image with the given layout. The layout
* (i.e., the image's SampleModel and
* ColorModel) is described by an
* ImageTypeSpecifier object.
*
*
A return value of true 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
* false if handed an RGB BufferedImage.
* 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.
*
*
Different ImageWriters, 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 ImageTypeSpecifier specifying the
* layout of the image to be written.
*
* @return true if this writer is likely to be able
* to encode images with the given layout.
*
* @exception IllegalArgumentException if type
* is null.
*/
public abstract boolean canEncodeImage(ImageTypeSpecifier type);
/**
* Returns true if the ImageWriter
* implementation associated with this service provider is able to
* encode the given RenderedImage instance. Note
* that this includes instances of
* java.awt.image.BufferedImage.
*
*
See the discussion for
* canEncodeImage(ImageTypeSpecifier) for information
* on the semantics of this method.
*
* @param im an instance of RenderedImage to be encoded.
*
* @return true if this writer is likely to be able
* to encode this image.
*
* @exception IllegalArgumentException if im
* is null.
*/
public boolean canEncodeImage(RenderedImage im) {
return canEncodeImage(ImageTypeSpecifier.createFromRenderedImage(im));
}
/**
* Returns an instance of the ImageWriter
* implementation associated with this service provider.
* The returned object will initially be in an initial state as if
* its reset method had been called.
*
*
The default implementation simply returns
* createWriterInstance(null).
*
* @return an ImageWriter 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 ImageWriter
* implementation associated with this service provider.
* The returned object will initially be in an initial state
* as if its reset method had been called.
*
*
An Object may be supplied to the plug-in at
* construction time. The nature of the object is entirely
* plug-in specific.
*
*
Typically, a plug-in will implement this method using code
* such as return new MyImageWriter(this).
*
* @param extension a plug-in specific extension object, which may
* be null.
*
* @return an ImageWriter instance.
*
* @exception IOException if the attempt to instantiate
* the writer fails.
* @exception IllegalArgumentException if the
* ImageWriter's constructor throws an
* IllegalArgumentException to indicate that the
* extension object is unsuitable.
*/
public abstract ImageWriter createWriterInstance(Object extension)
throws IOException;
/**
* Returns true if the ImageWriter object
* passed in is an instance of the ImageWriter
* associated with this service provider.
*
* @param writer an ImageWriter instance.
*
* @return true if writer is recognized
*
* @exception IllegalArgumentException if writer is
* null.
*/
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 Strings containing all the
* fully qualified names of all the ImageReaderSpi
* classes that can understand the internal metadata
* representation used by the ImageWriter associated
* with this service provider, or null if there are
* no such ImageReaders specified. If a
* non-null value is returned, it must have non-zero
* length.
*
*
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 ImageReader returned by
* ImageIO.getImageReader(ImageWriter).
*
*
This mechanism may be used to obtain
* ImageReaders that will generated non-pixel
* meta-data (see IIOExtraDataInfo) in a structure
* understood by an ImageWriter. By reading the
* image and obtaining this data from one of the
* ImageReaders obtained with this method and passing
* it on to the ImageWriter, 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 Strings of length at least 1
* containing names of ImageReaderSpis, or
* null.
*
* @see javax.imageio.ImageIO#getImageReader(ImageWriter)
* @see ImageReaderSpi#getImageWriterSpiNames()
*/
public String[] getImageReaderSpiNames() {
return readerSpiNames == null ?
null : readerSpiNames.clone();
}
}