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.