ImageOutputStreamSpi (Java SE 26 & JDK 26)
Description: declaration: module: java.desktop, package: javax.imageio.spi, class: ImageOutputStreamSpi
Keywords: javax.imageio.spi.ImageOutputStreamSpi class

# Class ImageOutputStreamSpi

java.lang.Object
javax.imageio.spi.IIOServiceProvider
javax.imageio.spi.ImageOutputStreamSpi

All Implemented Interfaces:
  `RegisterableService`

public abstract class ImageOutputStreamSpi extends IIOServiceProvider
The service provider interface (SPI) for `ImageOutputStream`s. 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 `ImageOutputStream`s 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 Also:
  - `IIORegistry`
  - `ImageOutputStream`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Class<?>`
  `outputClass`
  A `Class` object indicating the legal object type for use by the `createInputStreamInstance` method.

  ### Fields declared in class IIOServiceProvider

  `vendorName, version`
  Modifier and Type
  Field
  Description
  `protected String`
  `vendorName`
  A `String` to be returned from `getVendorName`, initially `null`.
  `protected String`
  `version`
  A `String` to be returned from `getVersion`, initially null.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `ImageOutputStreamSpi()`
  Constructs a blank `ImageOutputStreamSpi`.
  ``
  `ImageOutputStreamSpi(String vendorName, String version, Class<?> outputClass)`
  Constructs an `ImageOutputStreamSpi` with a given set of values.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `canUseCacheFile()`
  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.
  `ImageOutputStream`
  `createOutputStreamInstance(Object output)`
  Returns an instance of the `ImageOutputStream` implementation associated with this service provider.
  `abstract ImageOutputStream`
  `createOutputStreamInstance(Object output, boolean useCache, File cacheDir)`
  Returns an instance of the `ImageOutputStream` implementation associated with this service provider.
  `Class<?>`
  `getOutputClass()`
  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.
  `boolean`
  `needsCacheFile()`
  Returns `true` if the `ImageOutputStream` implementation associated with this service provider requires the use of a cache `File`.

  ### Methods declared in class IIOServiceProvider

  `getDescription, getVendorName, getVersion, onDeregistration, onRegistration`
  Modifier and Type
  Method
  Description
  `abstract String`
  `getDescription(Locale locale)`
  Returns a brief, human-readable description of this service provider and its associated implementation.
  `String`
  `getVendorName()`
  Returns the name of the vendor responsible for creating this service provider and its associated implementation.
  `String`
  `getVersion()`
  Returns a string describing the version number of this service provider and its associated implementation.
  `void`
  `onDeregistration(ServiceRegistry registry, Class<?> category)`
  A callback that will be whenever the Spi class has been deregistered from a `ServiceRegistry`.
  `void`
  `onRegistration(ServiceRegistry registry, Class<?> category)`
  A callback that will be called exactly once after the Spi class has been instantiated and registered in a `ServiceRegistry`.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Field Details

  - ### outputClass

    protected Class<?> outputClass
    A `Class` object indicating the legal object type for use by the `createInputStreamInstance` method.

- ## Constructor Details

  - ### ImageOutputStreamSpi

    protected ImageOutputStreamSpi()
    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.

  - ### ImageOutputStreamSpi

    public ImageOutputStreamSpi(String vendorName, String version, Class<?> outputClass)
    Constructs an `ImageOutputStreamSpi` with a given set of values.
    Parameters:
      `vendorName` - the vendor name.
      `version` - a version identifier.
      `outputClass` - a `Class` object indicating the legal object type for use by the `createOutputStreamInstance` method.
    Throws:
      `IllegalArgumentException` - if `vendorName` is `null`.
      `IllegalArgumentException` - if `version` is `null`.

- ## Method Details

  - ### getOutputClass

    public Class<?> getOutputClass()
    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.

    Returns:
      a `Class` variable.
    See Also:
      - `createOutputStreamInstance(Object, boolean, File)`

  - ### canUseCacheFile

    public boolean canUseCacheFile()
    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`.

    Returns:
      `true` if a cache file can be used by the output streams created by this service provider.

  - ### needsCacheFile

    public boolean needsCacheFile()
    Returns `true` if the `ImageOutputStream` implementation associated with this service provider requires the use of a cache `File`.

    The default implementation returns `false`.

    Returns:
      `true` if a cache file is needed by the output streams created by this service provider.

  - ### createOutputStreamInstance

    public abstract ImageOutputStream createOutputStreamInstance(Object output, boolean useCache, File cacheDir) throws IOException
    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.
    Parameters:
      `output` - an object of the class type returned by `getOutputClass`.
      `useCache` - a `boolean` indicating whether a cache file should be used, in cases where it is optional.
      `cacheDir` - a `File` indicating where the cache file should be created, or `null` to use the system directory.
    Returns:
      an `ImageOutputStream` instance.
    Throws:
      `IllegalArgumentException` - if `output` is not an instance of the correct class or is `null`.
      `IllegalArgumentException` - if a cache file is needed, but `cacheDir` is non-`null` and is not a directory.
      `IOException` - if a cache file is needed but cannot be created.
    See Also:
      - `getOutputClass()`

  - ### createOutputStreamInstance

    public ImageOutputStream createOutputStreamInstance(Object output) 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.
    Parameters:
      `output` - an object of the class type returned by `getOutputClass`.
    Returns:
      an `ImageOutputStream` instance.
    Throws:
      `IllegalArgumentException` - if `output` is not an instance of the correct class or is `null`.
      `IOException` - if a cache file is needed but cannot be created.
    See Also:
      - `getOutputClass()`