ImageOutputStreams. 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 ImageOutputStream. For example, a
+ * particular ImageOutputStreamSpi might allow a generic
+ * OutputStream to be used as a destination; another
+ * might output to a File or to a device such as a serial
+ * port.
+ *
+ *
By treating the creation of ImageOutputStreams as
+ * a pluggable service, it becomes possible to handle future output
+ * destinations without changing the API. Also, high-performance
+ * implementations of ImageOutputStream (for example,
+ * native implementations for a particular platform) can be installed
+ * and used transparently by applications.
+ *
+ * @see IIORegistry
+ * @see javax.imageio.stream.ImageOutputStream
+ *
+ */
+public abstract class ImageOutputStreamSpi extends IIOServiceProvider {
+
+ /**
+ * A Class object indicating the legal object type
+ * for use by the createInputStreamInstance method.
+ */
+ protected Class outputClass;
+
+ /**
+ * Constructs a blank ImageOutputStreamSpi. 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 ImageOutputStreamSpi() {
+ }
+
+ /**
+ * Constructs an ImageOutputStreamSpi with a given
+ * set of values.
+ *
+ * @param vendorName the vendor name.
+ * @param version a version identifier.
+ * @param outputClass a Class object indicating the
+ * legal object type for use by the
+ * createOutputStreamInstance method.
+ *
+ * @exception IllegalArgumentException if vendorName
+ * is null.
+ * @exception IllegalArgumentException if version
+ * is null.
+ */
+ public ImageOutputStreamSpi(String vendorName,
+ String version,
+ Class outputClass) {
+ super(vendorName, version);
+ this.outputClass = outputClass;
+ }
+
+ /**
+ * Returns a Class object representing the class or
+ * interface type that must be implemented by an output
+ * destination in order to be "wrapped" in an
+ * ImageOutputStream via the
+ * createOutputStreamInstance method.
+ *
+ *
Typical return values might include
+ * OutputStream.class or File.class, but
+ * any class may be used.
+ *
+ * @return a Class variable.
+ *
+ * @see #createOutputStreamInstance(Object, boolean, File)
+ */
+ public Class getOutputClass() {
+ return outputClass;
+ }
+
+ /**
+ * Returns true if the ImageOutputStream
+ * 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 cacheFile argument to
+ * createOutputStreamInstance will be ignored.
+ *
+ *
The default implementation returns false.
+ *
+ * @return true if a cache file can be used by the
+ * output streams created by this service provider.
+ */
+ public boolean canUseCacheFile() {
+ return false;
+ }
+
+ /**
+ * Returns true if the ImageOutputStream
+ * implementation associated with this service provider requires
+ * the use of a cache File.
+ *
+ *
The default implementation returns false.
+ *
+ * @return true if a cache file is needed by the
+ * output streams created by this service provider.
+ */
+ public boolean needsCacheFile() {
+ return false;
+ }
+
+ /**
+ * Returns an instance of the ImageOutputStream
+ * 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 output an object of the class type returned by
+ * getOutputClass.
+ * @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 ImageOutputStream instance.
+ *
+ * @exception IllegalArgumentException if output 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 #getOutputClass
+ */
+ public abstract
+ ImageOutputStream createOutputStreamInstance(Object output,
+ boolean useCache,
+ File cacheDir)
+ throws IOException;
+
+ /**
+ * Returns an instance of the ImageOutputStream
+ * implementation associated with this service provider. A cache
+ * file will be created in the system-dependent default
+ * temporary-file directory, if needed.
+ *
+ * @param output an object of the class type returned by
+ * getOutputClass.
+ *
+ * @return an ImageOutputStream instance.
+ *
+ * @exception IllegalArgumentException if output is
+ * not an instance of the correct class or is null.
+ * @exception IOException if a cache file is needed but cannot be
+ * created.
+ *
+ * @see #getOutputClass()
+ */
+ public ImageOutputStream createOutputStreamInstance(Object output)
+ throws IOException {
+ return createOutputStreamInstance(output, true, null);
+ }
+}