ImageReaders.
* For more information on service provider classes, see the class comment
* for the IIORegistry class.
*
* Each ImageReaderSpi provides several types of information
* about the ImageReader 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-readable 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
* getMIMETypes methods. These methods may be used to
* identify candidate ImageReaders for decoding a
* particular file or stream based on manual format selection, file
* naming, or MIME associations (for example, when accessing a file
* over HTTP or as an email attachment).
*
*
A more reliable way to determine which ImageReaders
* are likely to be able to parse a particular data stream is provided
* by the canDecodeInput method. This methods allows the
* service provider to inspect the actual stream contents.
*
*
Finally, an instance of the For most readers, which only accept input from an
* It is important that the state of the object not be
* disturbed in order that other Formats such as "raw," which can potentially attempt
* to read nearly any stream, should return If The default implementation simply returns
* An Typically, a plug-in will implement this method using code
* such as The default implementation compares the fully-qualified
* class name of the The first item in the array must be the name of the service
* provider for the "preferred" writer, as it will be used to
* instantiate the This mechanism may be used to obtain
* ImageReader class
* associated with this service provider may be obtained by calling
* the createReaderInstance 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.ImageReader
*
*/
public abstract class ImageReaderSpi extends ImageReaderWriterSpi {
/**
* A single-element array, initially containing
* ImageInputStream.class, to be returned from
* getInputTypes.
* @deprecated Instead of using this field, directly create
* the equivalent array { ImageInputStream.class }.
*/
@Deprecated
public static final Class[] STANDARD_INPUT_TYPE =
{ ImageInputStream.class };
/**
* An array of Class objects to be returned from
* getInputTypes, initially null.
*/
protected Class[] inputTypes = null;
/**
* An array of strings to be returned from
* getImageWriterSpiNames, initially
* null.
*/
protected String[] writerSpiNames = null;
/**
* The Class of the reader, initially
* null.
*/
private Class readerClass = null;
/**
* Constructs a blank ImageReaderSpi. 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 ImageReaderSpi() {
}
/**
* Constructs an ImageReaderSpi 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 MIME types are defined,
* null should be supplied. An array of length 0
* will be normalized to null.
* @param readerClassName the fully-qualified name of the
* associated ImageReader class, as a
* non-null String.
* @param inputTypes a non-null array of
* Class objects of length at least 1 indicating the
* legal input types.
* @param writerSpiNames an array Strings naming the
* classes of all associated ImageWriters, 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 readerClassName
* is null.
* @exception IllegalArgumentException if inputTypes
* is null or has length 0.
*/
public ImageReaderSpi(String vendorName,
String version,
String[] names,
String[] suffixes,
String[] MIMETypes,
String readerClassName,
Class[] inputTypes,
String[] writerSpiNames,
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, readerClassName,
supportsStandardStreamMetadataFormat,
nativeStreamMetadataFormatName,
nativeStreamMetadataFormatClassName,
extraStreamMetadataFormatNames,
extraStreamMetadataFormatClassNames,
supportsStandardImageMetadataFormat,
nativeImageMetadataFormatName,
nativeImageMetadataFormatClassName,
extraImageMetadataFormatNames,
extraImageMetadataFormatClassNames);
if (inputTypes == null) {
throw new IllegalArgumentException
("inputTypes == null!");
}
if (inputTypes.length == 0) {
throw new IllegalArgumentException
("inputTypes.length == 0!");
}
this.inputTypes = (inputTypes == STANDARD_INPUT_TYPE) ?
new Class[] { ImageInputStream.class } :
inputTypes.clone();
// If length == 0, leave it null
if (writerSpiNames != null && writerSpiNames.length > 0) {
this.writerSpiNames = (String[])writerSpiNames.clone();
}
}
/**
* Returns an array of Class objects indicating what
* types of objects may be used as arguments to the reader's
* setInput method.
*
* ImageInputStream, a single-element array
* containing ImageInputStream.class should be
* returned.
*
* @return a non-null array of
* Classobjects of length at least 1.
*/
public Class[] getInputTypes() {
return (Class[])inputTypes.clone();
}
/**
* Returns true if the supplied source object appears
* to be of the format supported by this reader. Returning
* true from this method does not guarantee that
* reading will succeed, only that there appears to be a
* reasonable chance of success based on a brief inspection of the
* stream contents. If the source is an
* ImageInputStream, implementations will commonly
* check the first several bytes of the stream for a "magic
* number" associated with the format. Once actual reading has
* commenced, the reader may still indicate failure at any time
* prior to the completion of decoding.
*
* ImageReaderSpis can
* properly determine whether they are able to decode the object.
* In particular, if the source is an
* ImageInputStream, a
* mark/reset pair should be used to
* preserve the stream position.
*
* false
* in order to avoid being invoked in preference to a closer
* match.
*
* source is not an instance of one of the
* classes returned by getInputTypes, the method
* should simply return false.
*
* @param source the object (typically an
* ImageInputStream) to be decoded.
*
* @return true if it is likely that this stream can
* be decoded.
*
* @exception IllegalArgumentException if source is
* null.
* @exception IOException if an I/O error occurs while reading the
* stream.
*/
public abstract boolean canDecodeInput(Object source) throws IOException;
/**
* Returns an instance of the ImageReader
* implementation associated with this service provider.
* The returned object will initially be in an initial state
* as if its reset method had been called.
*
* createReaderInstance(null).
*
* @return an ImageReader instance.
*
* @exception IOException if an error occurs during loading,
* or initialization of the reader class, or during instantiation
* or initialization of the reader object.
*/
public ImageReader createReaderInstance() throws IOException {
return createReaderInstance(null);
}
/**
* Returns an instance of the ImageReader
* implementation associated with this service provider.
* The returned object will initially be in an initial state
* as if its reset method had been called.
*
* Object may be supplied to the plug-in at
* construction time. The nature of the object is entirely
* plug-in specific.
*
* return new MyImageReader(this).
*
* @param extension a plug-in specific extension object, which may
* be null.
*
* @return an ImageReader instance.
*
* @exception IOException if the attempt to instantiate
* the reader fails.
* @exception IllegalArgumentException if the
* ImageReader's contructor throws an
* IllegalArgumentException to indicate that the
* extension object is unsuitable.
*/
public abstract ImageReader createReaderInstance(Object extension)
throws IOException;
/**
* Returns true if the ImageReader object
* passed in is an instance of the ImageReader
* associated with this service provider.
*
* reader argument with the class
* name passed into the constructor. This method may be overridden
* if more sophisticated checking is required.
*
* @param reader an ImageReader instance.
*
* @return true if reader is recognized.
*
* @exception IllegalArgumentException if reader is
* null.
*/
public boolean isOwnReader(ImageReader reader) {
if (reader == null) {
throw new IllegalArgumentException("reader == null!");
}
String name = reader.getClass().getName();
return name.equals(pluginClassName);
}
/**
* Returns an array of Strings containing the fully
* qualified names of all the ImageWriterSpi classes
* that can understand the internal metadata representation used
* by the ImageReader associated with this service
* provider, or null if there are no such
* ImageWriters specified. If a
* non-null value is returned, it must have non-zero
* length.
*
* ImageWriter returned by
* ImageIO.getImageWriter(ImageReader).
*
* ImageWriters that will understand the internal
* structure of non-pixel meta-data (see
* IIOTreeInfo) generated by an
* ImageReader. By obtaining this data from the
* ImageReader and passing it on to one of the
* ImageWriters obtained with this method, a client
* program can read an image, modify it in some way, and write it
* back out while 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 ImageWriterSpi, or
* null.
*
* @see javax.imageio.ImageIO#getImageWriter(ImageReader)
*/
public String[] getImageWriterSpiNames() {
return writerSpiNames == null ?
null : (String[])writerSpiNames.clone();
}
}