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

Module java.desktop
Package javax.imageio.spi

# Class ImageReaderWriterSpi

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

All Implemented Interfaces:
  `RegisterableService`

Direct Known Subclasses:
  `ImageReaderSpi`, `ImageWriterSpi`

public abstract class ImageReaderWriterSpi extends IIOServiceProvider
A superclass containing instance variables and methods common to `ImageReaderSpi` and `ImageWriterSpi`.

See Also:
  - `IIORegistry`
  - `ImageReaderSpi`
  - `ImageWriterSpi`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected String[]`
  `extraImageMetadataFormatClassNames`
  An array of `String`s containing the class names of any additional image metadata formats supported by this plug-in, initially `null`.
  `protected String[]`
  `extraImageMetadataFormatNames`
  An array of `String`s containing the names of any additional image metadata formats supported by this plug-in, initially `null`.
  `protected String[]`
  `extraStreamMetadataFormatClassNames`
  An array of `String`s containing the class names of any additional stream metadata formats supported by this plug-in, initially `null`.
  `protected String[]`
  `extraStreamMetadataFormatNames`
  An array of `String`s containing the names of any additional stream metadata formats supported by this plug-in, initially `null`.
  `protected String[]`
  `MIMETypes`
  An array of strings to be returned from `getMIMETypes`, initially `null`.
  `protected String[]`
  `names`
  An array of strings to be returned from `getFormatNames`, initially `null`.
  `protected String`
  `nativeImageMetadataFormatClassName`
  A `String` containing the class name of the native stream metadata format supported by this plug-in, initially `null`.
  `protected String`
  `nativeImageMetadataFormatName`
  A `String` containing the name of the native stream metadata format supported by this plug-in, initially `null`.
  `protected String`
  `nativeStreamMetadataFormatClassName`
  A `String` containing the class name of the native stream metadata format supported by this plug-in, initially `null`.
  `protected String`
  `nativeStreamMetadataFormatName`
  A `String` containing the name of the native stream metadata format supported by this plug-in, initially `null`.
  `protected String`
  `pluginClassName`
  A `String` containing the name of the associated plug-in class, initially `null`.
  `protected String[]`
  `suffixes`
  An array of strings to be returned from `getFileSuffixes`, initially `null`.
  `protected boolean`
  `supportsStandardImageMetadataFormat`
  A boolean indicating whether this plug-in supports the standard metadata format for image metadata, initially `false`.
  `protected boolean`
  `supportsStandardStreamMetadataFormat`
  A boolean indicating whether this plug-in supports the standard metadata format for stream metadata, initially `false`.

  ### Fields declared in class javax.imageio.spi.IIOServiceProvider

  `vendorName, version`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ImageReaderWriterSpi()`
  Constructs a blank `ImageReaderWriterSpi`.
  `ImageReaderWriterSpi(String vendorName, String version, String[] names, String[] suffixes, String[] MIMETypes, String pluginClassName, boolean supportsStandardStreamMetadataFormat, String nativeStreamMetadataFormatName, String nativeStreamMetadataFormatClassName, String[] extraStreamMetadataFormatNames, String[] extraStreamMetadataFormatClassNames, boolean supportsStandardImageMetadataFormat, String nativeImageMetadataFormatName, String nativeImageMetadataFormatClassName, String[] extraImageMetadataFormatNames, String[] extraImageMetadataFormatClassNames)`
  Constructs an `ImageReaderWriterSpi` with a given set of values.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String[]`
  `getExtraImageMetadataFormatNames()`
  Returns an array of `String`s containing the names of additional document formats, other than the native and standard formats, recognized by the `getAsTree` and `setFromTree` methods on the image metadata objects produced or consumed by this plug-in.
  `String[]`
  `getExtraStreamMetadataFormatNames()`
  Returns an array of `String`s containing the names of additional document formats, other than the native and standard formats, recognized by the `getAsTree` and `setFromTree` methods on the stream metadata objects produced or consumed by this plug-in.
  `String[]`
  `getFileSuffixes()`
  Returns an array of `String`s containing a list of file suffixes associated with the formats that are generally usable by the `ImageReader` or `ImageWriter` implementation associated with this service provider.
  `String[]`
  `getFormatNames()`
  Returns an array of `String`s containing human-readable names for the formats that are generally usable by the `ImageReader` or `ImageWriter` implementation associated with this service provider.
  `IIOMetadataFormat`
  `getImageMetadataFormat(String formatName)`
  Returns an `IIOMetadataFormat` object describing the given image metadata format, or `null` if no description is available.
  `String[]`
  `getMIMETypes()`
  Returns an array of `String`s containing a list of MIME types associated with the formats that are generally usable by the `ImageReader` or `ImageWriter` implementation associated with this service provider.
  `String`
  `getNativeImageMetadataFormatName()`
  Returns the name of the "native" image metadata format for this plug-in, which typically allows for lossless encoding and transmission of the image metadata stored in the format handled by this plug-in.
  `String`
  `getNativeStreamMetadataFormatName()`
  Returns the name of the "native" stream metadata format for this plug-in, which typically allows for lossless encoding and transmission of the stream metadata stored in the format handled by this plug-in.
  `String`
  `getPluginClassName()`
  Returns the fully-qualified class name of the `ImageReader` or `ImageWriter` plug-in associated with this service provider.
  `IIOMetadataFormat`
  `getStreamMetadataFormat(String formatName)`
  Returns an `IIOMetadataFormat` object describing the given stream metadata format, or `null` if no description is available.
  `boolean`
  `isStandardImageMetadataFormatSupported()`
  Returns `true` if the standard metadata format is among the document formats recognized by the `getAsTree` and `setFromTree` methods on the image metadata objects produced or consumed by this plug-in.
  `boolean`
  `isStandardStreamMetadataFormatSupported()`
  Returns `true` if the standard metadata format is among the document formats recognized by the `getAsTree` and `setFromTree` methods on the stream metadata objects produced or consumed by this plug-in.

  ### Methods declared in class javax.imageio.spi.IIOServiceProvider

  `getDescription, getVendorName, getVersion, onDeregistration, onRegistration`

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### names

    protected String[] names
    An array of strings to be returned from `getFormatNames`, initially `null`. Constructors should set this to a non-`null` value.

  - ### suffixes

    protected String[] suffixes
    An array of strings to be returned from `getFileSuffixes`, initially `null`.

  - ### MIMETypes

    protected String[] MIMETypes
    An array of strings to be returned from `getMIMETypes`, initially `null`.

  - ### pluginClassName

    protected String pluginClassName
    A `String` containing the name of the associated plug-in class, initially `null`.

  - ### supportsStandardStreamMetadataFormat

    protected boolean supportsStandardStreamMetadataFormat
    A boolean indicating whether this plug-in supports the standard metadata format for stream metadata, initially `false`.

  - ### nativeStreamMetadataFormatName

    protected String nativeStreamMetadataFormatName
    A `String` containing the name of the native stream metadata format supported by this plug-in, initially `null`.

  - ### nativeStreamMetadataFormatClassName

    protected String nativeStreamMetadataFormatClassName
    A `String` containing the class name of the native stream metadata format supported by this plug-in, initially `null`.

  - ### extraStreamMetadataFormatNames

    protected String[] extraStreamMetadataFormatNames
    An array of `String`s containing the names of any additional stream metadata formats supported by this plug-in, initially `null`.

  - ### extraStreamMetadataFormatClassNames

    protected String[] extraStreamMetadataFormatClassNames
    An array of `String`s containing the class names of any additional stream metadata formats supported by this plug-in, initially `null`.

  - ### supportsStandardImageMetadataFormat

    protected boolean supportsStandardImageMetadataFormat
    A boolean indicating whether this plug-in supports the standard metadata format for image metadata, initially `false`.

  - ### nativeImageMetadataFormatName

    protected String nativeImageMetadataFormatName
    A `String` containing the name of the native stream metadata format supported by this plug-in, initially `null`.

  - ### nativeImageMetadataFormatClassName

    protected String nativeImageMetadataFormatClassName
    A `String` containing the class name of the native stream metadata format supported by this plug-in, initially `null`.

  - ### extraImageMetadataFormatNames

    protected String[] extraImageMetadataFormatNames
    An array of `String`s containing the names of any additional image metadata formats supported by this plug-in, initially `null`.

  - ### extraImageMetadataFormatClassNames

    protected String[] extraImageMetadataFormatClassNames
    An array of `String`s containing the class names of any additional image metadata formats supported by this plug-in, initially `null`.

- ## Constructor Details

  - ### ImageReaderWriterSpi

    public ImageReaderWriterSpi(String vendorName, String version, String[] names, String[] suffixes, String[] MIMETypes, String pluginClassName, boolean supportsStandardStreamMetadataFormat, String nativeStreamMetadataFormatName, String nativeStreamMetadataFormatClassName, String[] extraStreamMetadataFormatNames, String[] extraStreamMetadataFormatClassNames, boolean supportsStandardImageMetadataFormat, String nativeImageMetadataFormatName, String nativeImageMetadataFormatClassName, String[] extraImageMetadataFormatNames, String[] extraImageMetadataFormatClassNames)
    Constructs an `ImageReaderWriterSpi` with a given set of values.
    Parameters:
      `vendorName` - the vendor name, as a non-`null` `String`.
      `version` - a version identifier, as a non-`null` `String`.
      `names` - a non-`null` array of `String`s indicating the format names. At least one entry must be present.
      `suffixes` - an array of `String`s indicating the common file suffixes. If no suffixes are defined, `null` should be supplied. An array of length 0 will be normalized to `null`.
      `MIMETypes` - an array of `String`s 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`.
      `pluginClassName` - the fully-qualified name of the associated `ImageReader` or `ImageWriter` class, as a non-`null String`.
      `supportsStandardStreamMetadataFormat` - a `boolean` that indicates whether a stream metadata object can use trees described by the standard metadata format.
      `nativeStreamMetadataFormatName` - a `String`, or `null`, to be returned from `getNativeStreamMetadataFormatName`.
      `nativeStreamMetadataFormatClassName` - a `String`, or `null`, to be used to instantiate a metadata format object to be returned from `getNativeStreamMetadataFormat`.
      `extraStreamMetadataFormatNames` - an array of `String`s, or `null`, to be returned from `getExtraStreamMetadataFormatNames`. An array of length 0 is normalized to `null`.
      `extraStreamMetadataFormatClassNames` - an array of `String`s, 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`.
      `supportsStandardImageMetadataFormat` - a `boolean` that indicates whether an image metadata object can use trees described by the standard metadata format.
      `nativeImageMetadataFormatName` - a `String`, or `null`, to be returned from `getNativeImageMetadataFormatName`.
      `nativeImageMetadataFormatClassName` - a `String`, or `null`, to be used to instantiate a metadata format object to be returned from `getNativeImageMetadataFormat`.
      `extraImageMetadataFormatNames` - an array of `String`s to be returned from `getExtraImageMetadataFormatNames`. An array of length 0 is normalized to `null`.
      `extraImageMetadataFormatClassNames` - an array of `String`s, 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`.
    Throws:
      `IllegalArgumentException` - if `vendorName` is `null`.
      `IllegalArgumentException` - if `version` is `null`.
      `IllegalArgumentException` - if `names` is `null` or has length 0.
      `IllegalArgumentException` - if `pluginClassName` is `null`.

  - ### ImageReaderWriterSpi

    public ImageReaderWriterSpi()
    Constructs a blank `ImageReaderWriterSpi`. It is up to the subclass to initialize instance variables and/or override method implementations in order to provide working versions of all methods.

- ## Method Details

  - ### getFormatNames

    public String[] getFormatNames()
    Returns an array of `String`s containing human-readable names for the formats that are generally usable by the `ImageReader` or `ImageWriter` implementation associated with this service provider. For example, a single `ImageReader` might be able to process both PBM and PNM files.
    Returns:
      a non-`null` array of `String`s or length at least 1 containing informal format names associated with this reader or writer.

  - ### getFileSuffixes

    public String[] getFileSuffixes()
    Returns an array of `String`s containing a list of file suffixes associated with the formats that are generally usable by the `ImageReader` or `ImageWriter` implementation associated with this service provider. For example, a single `ImageReader` might be able to process files with '.pbm' and '.pnm' suffixes, or both '.jpg' and '.jpeg' suffixes. If there are no known file suffixes, `null` will be returned.

    Returning a particular suffix does not guarantee that files with that suffix can be processed; it merely indicates that it may be worthwhile attempting to decode or encode such files using this service provider.

    Returns:
      an array of `String`s or length at least 1 containing common file suffixes associated with this reader or writer, or `null`.

  - ### getMIMETypes

    public String[] getMIMETypes()
    Returns an array of `String`s containing a list of MIME types associated with the formats that are generally usable by the `ImageReader` or `ImageWriter` implementation associated with this service provider.

    Ideally, only a single MIME type would be required in order to describe a particular format. However, for several reasons it is necessary to associate a list of types with each service provider. First, many common image file formats do not have standard MIME types, so a list of commonly used unofficial names will be required, such as `image/x-pbm` and `image/x-portable-bitmap`. Some file formats have official MIME types but may sometimes be referred to using their previous unofficial designations, such as `image/x-png` instead of the official `image/png`. Finally, a single service provider may be capable of parsing multiple distinct types from the MIME point of view, for example `image/x-xbitmap` and `image/x-xpixmap`.

    Returning a particular MIME type does not guarantee that files claiming to be of that type can be processed; it merely indicates that it may be worthwhile attempting to decode or encode such files using this service provider.

    Returns:
      an array of `String`s or length at least 1 containing MIME types associated with this reader or writer, or `null`.

  - ### getPluginClassName

    public String getPluginClassName()
    Returns the fully-qualified class name of the `ImageReader` or `ImageWriter` plug-in associated with this service provider.
    Returns:
      the class name, as a non-`null` `String`.

  - ### isStandardStreamMetadataFormatSupported

    public boolean isStandardStreamMetadataFormatSupported()
    Returns `true` if the standard metadata format is among the document formats recognized by the `getAsTree` and `setFromTree` methods on the stream metadata objects produced or consumed by this plug-in.
    Returns:
      `true` if the standard format is supported for stream metadata.

  - ### getNativeStreamMetadataFormatName

    public String getNativeStreamMetadataFormatName()
    Returns the name of the "native" stream metadata format for this plug-in, which typically allows for lossless encoding and transmission of the stream metadata stored in the format handled by this plug-in. If no such format is supported, `null` will be returned.

    The default implementation returns the `nativeStreamMetadataFormatName` instance variable, which is typically set by the constructor.

    Returns:
      the name of the native stream metadata format, or `null`.

  - ### getExtraStreamMetadataFormatNames

    public String[] getExtraStreamMetadataFormatNames()
    Returns an array of `String`s containing the names of additional document formats, other than the native and standard formats, recognized by the `getAsTree` and `setFromTree` methods on the stream metadata objects produced or consumed by this plug-in.

    If the plug-in does not handle metadata, null should be returned.

    The set of formats may differ according to the particular images being read or written; this method should indicate all the additional formats supported by the plug-in under any circumstances.

    The default implementation returns a clone of the `extraStreamMetadataFormatNames` instance variable, which is typically set by the constructor.

    Returns:
      an array of `String`s, or null.
    See Also:
      - `IIOMetadata.getMetadataFormatNames()`
      - `getExtraImageMetadataFormatNames()`
      - `getNativeStreamMetadataFormatName()`

  - ### isStandardImageMetadataFormatSupported

    public boolean isStandardImageMetadataFormatSupported()
    Returns `true` if the standard metadata format is among the document formats recognized by the `getAsTree` and `setFromTree` methods on the image metadata objects produced or consumed by this plug-in.
    Returns:
      `true` if the standard format is supported for image metadata.

  - ### getNativeImageMetadataFormatName

    public String getNativeImageMetadataFormatName()
    Returns the name of the "native" image metadata format for this plug-in, which typically allows for lossless encoding and transmission of the image metadata stored in the format handled by this plug-in. If no such format is supported, `null` will be returned.

    The default implementation returns the `nativeImageMetadataFormatName` instance variable, which is typically set by the constructor.

    Returns:
      the name of the native image metadata format, or `null`.
    See Also:
      - `getExtraImageMetadataFormatNames()`

  - ### getExtraImageMetadataFormatNames

    public String[] getExtraImageMetadataFormatNames()
    Returns an array of `String`s containing the names of additional document formats, other than the native and standard formats, recognized by the `getAsTree` and `setFromTree` methods on the image metadata objects produced or consumed by this plug-in.

    If the plug-in does not handle image metadata, null should be returned.

    The set of formats may differ according to the particular images being read or written; this method should indicate all the additional formats supported by the plug-in under any circumstances.

    The default implementation returns a clone of the `extraImageMetadataFormatNames` instance variable, which is typically set by the constructor.

    Returns:
      an array of `String`s, or null.
    See Also:
      - `IIOMetadata.getMetadataFormatNames()`
      - `getExtraStreamMetadataFormatNames()`
      - `getNativeImageMetadataFormatName()`

  - ### getStreamMetadataFormat

    public IIOMetadataFormat getStreamMetadataFormat(String formatName)
    Returns an `IIOMetadataFormat` object describing the given stream metadata format, or `null` if no description is available. The supplied name must be the native stream metadata format name, the standard metadata format name, or one of those returned by `getExtraStreamMetadataFormatNames`.
    Parameters:
      `formatName` - the desired stream metadata format.
    Returns:
      an `IIOMetadataFormat` object.
    Throws:
      `IllegalArgumentException` - if `formatName` is `null` or is not a supported name.

  - ### getImageMetadataFormat

    public IIOMetadataFormat getImageMetadataFormat(String formatName)
    Returns an `IIOMetadataFormat` object describing the given image metadata format, or `null` if no description is available. The supplied name must be the native image metadata format name, the standard metadata format name, or one of those returned by `getExtraImageMetadataFormatNames`.
    Parameters:
      `formatName` - the desired image metadata format.
    Returns:
      an `IIOMetadataFormat` object.
    Throws:
      `IllegalArgumentException` - if `formatName` is `null` or is not a supported name.