ImageInputStreams. For more information on service
* provider interfaces, see the class comment for the
* IIORegistry class.
*
* This interface allows arbitrary objects to be "wrapped" by
* instances of ImageInputStream. For example,
* a particular ImageInputStreamSpi might allow
* a generic InputStream to be used as an input source;
* another might take input from a URL.
*
*
By treating the creation of ImageInputStreams as a
* pluggable service, it becomes possible to handle future input
* sources without changing the API. Also, high-performance
* implementations of ImageInputStream (for example,
* native implementations for a particular platform) can be installed
* and used transparently by applications.
*
* @see IIORegistry
* @see javax.imageio.stream.ImageInputStream
*
*/
public abstract class ImageInputStreamSpi extends IIOServiceProvider {
/**
* A Class object indicating the legal object type
* for use by the createInputStreamInstance method.
*/
protected Class inputClass;
/**
* Constructs a blank ImageInputStreamSpi. 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 ImageInputStreamSpi() {
}
/**
* Constructs an ImageInputStreamSpi with a given set
* of values.
*
* @param vendorName the vendor name.
* @param version a version identifier.
* @param inputClass a Class object indicating the
* legal object type for use by the
* createInputStreamInstance method.
*
* @exception IllegalArgumentException if vendorName
* is null.
* @exception IllegalArgumentException if version
* is null.
*/
public ImageInputStreamSpi(String vendorName,
String version,
Class inputClass) {
super(vendorName, version);
this.inputClass = inputClass;
}
/**
* Returns a Class object representing the class or
* interface type that must be implemented by an input source in
* order to be "wrapped" in an ImageInputStream via
* the createInputStreamInstance method.
*
*
Typical return values might include
* InputStream.class or URL.class, but
* any class may be used.
*
* @return a Class variable.
*
* @see #createInputStreamInstance(Object, boolean, File)
*/
public Class getInputClass() {
return inputClass;
}
/**
* Returns true if the ImageInputStream
* implementation associated with this service provider can
* optionally make use of a cache file for improved performance
* and/or memory footrprint. If false, the value of
* the useCache argument to
* createInputStreamInstance will be ignored.
*
*
The default implementation returns false.
*
* @return true if a cache file can be used by the
* input streams created by this service provider.
*/
public boolean canUseCacheFile() {
return false;
}
/**
* Returns true if the ImageInputStream
* implementation associated with this service provider requires
* the use of a cache File. If true,
* the value of the useCache argument to
* createInputStreamInstance will be ignored.
*
*
The default implementation returns false.
*
* @return true if a cache file is needed by the
* input streams created by this service provider.
*/
public boolean needsCacheFile() {
return false;
}
/**
* Returns an instance of the ImageInputStream
* implementation associated with this service provider. If the
* use of a cache file is optional, the useCache
* parameter will be consulted. Where a cache is required, or
* not applicable, the value of useCache will be ignored.
*
* @param input an object of the class type returned by
* getInputClass.
* @param useCache a boolean indicating whether a
* cache file should be used, in cases where it is optional.
* @param cacheDir a File indicating where the
* cache file should be created, or null to use the
* system directory.
*
* @return an ImageInputStream instance.
*
* @exception IllegalArgumentException if input is
* not an instance of the correct class or is null.
* @exception IllegalArgumentException if a cache file is needed
* but cacheDir is non-null and is not a
* directory.
* @exception IOException if a cache file is needed but cannot be
* created.
*
* @see #getInputClass
* @see #canUseCacheFile
* @see #needsCacheFile
*/
public abstract ImageInputStream
createInputStreamInstance(Object input,
boolean useCache,
File cacheDir) throws IOException;
/**
* Returns an instance of the ImageInputStream
* implementation associated with this service provider. A cache
* file will be created in the system-dependent default
* temporary-file directory, if needed.
*
* @param input an object of the class type returned by
* getInputClass.
*
* @return an ImageInputStream instance.
*
* @exception IllegalArgumentException if input is
* not an instance of the correct class or is null.
* @exception IOException if a cache file is needed but cannot be
* created.
*
* @see #getInputClass()
*/
public ImageInputStream createInputStreamInstance(Object input)
throws IOException {
return createInputStreamInstance(input, true, null);
}
}