An interface used by ImageReader implementations to
notify callers of their image and thumbnail reading methods of
progress.

 This interface receives general indications of decoding
progress (via the imageProgress and
thumbnailProgress methods), and events indicating when
an entire image has been updated (via the
imageStarted, imageComplete,
thumbnailStarted and thumbnailComplete
methods).  Applications that wish to be informed of pixel updates
as they happen (for example, during progressive decoding), should
provide an IIOReadUpdateListener.

An interface used by ImageReader implementations to
notify callers of their image and thumbnail reading methods of
pixel updates.

An interface used by ImageReader implementations to
notify callers of their image and thumbnail reading methods of
warnings (non-fatal errors).  Fatal errors cause the relevant
read method to throw an IIOException.

 Localization is handled by associating a Locale
with each IIOReadWarningListener as it is registered
with an ImageReader.  It is up to the
ImageReader to provide localized messages.

An interface used by ImageWriter implementations to notify
callers of their image writing methods of progress.

An interface used by ImageWriter implementations to
notify callers of their image and thumbnail reading methods of
warnings (non-fatal errors).  Fatal errors cause the relevant
read method to throw an IIOException.

 Localization is handled by associating a Locale
with each IIOWriteWarningListener as it is registered
with an ImageWriter.  It is up to the
ImageWriter to provide localized messages.

An exception class used for signaling run-time failure of reading
and writing operations.

 In addition to a message string, a reference to another
Throwable (Error or
Exception) is maintained.  This reference, if
non-null, refers to the event that caused this
exception to occur.  For example, an IOException while
reading from a File would be stored there.

A simple container class to aggregate an image, a set of
thumbnail (preview) images, and an object representing metadata
associated with the image.

 The image data may take the form of either a
RenderedImage, or a Raster.  Reader
methods that return an IIOImage will always return a
BufferedImage using the RenderedImage
reference.  Writer methods that accept an IIOImage
will always accept a RenderedImage, and may optionally
accept a Raster.

 Exactly one of getRenderedImage and
getRaster will return a non-null value.
Subclasses are responsible for ensuring this behavior.

A superclass of all classes describing how streams should be
decoded or encoded.  This class contains all the variables and
methods that are shared by ImageReadParam and
ImageWriteParam.

 This class provides mechanisms to specify a source region and a
destination region.  When reading, the source is the stream and
the in-memory image is the destination.  When writing, these are
reversed.  In the case of writing, destination regions may be used
only with a writer that supports pixel replacement.

Decimation subsampling may be specified for both readers
and writers, using a movable subsampling grid.

Subsets of the source and destination bands may be selected.

An interface to be implemented by objects that can determine the
settings of an IIOParam object, either by putting up a
GUI to obtain values from a user, or by other means.  This
interface merely specifies a generic activate method
that invokes the controller, without regard for how the controller
obtains values (i.e., whether the controller puts up a GUI
or merely computes a set of values is irrelevant to this
interface).

 Within the activate method, a controller obtains
initial values by querying the IIOParam object's
get methods, modifies values by whatever means, then
invokes the IIOParam object's set methods
to modify the appropriate settings.  Normally, these
set methods will be invoked all at once at a final
commit in order that a cancel operation not disturb existing
values.  In general, applications may expect that when the
activate method returns true, the
IIOParam object is ready for use in a read or write
operation.

 Vendors may choose to provide GUIs for the
IIOParam subclasses they define for a particular
plug-in.  These can be set up as default controllers in the
corresponding IIOParam subclasses.

 Applications may override any default GUIs and provide their
own controllers embedded in their own framework.  All that is
required is that theactivate method behave modally
(not returning until either cancelled or committed), though it need
not put up an explicitly modal dialog.  Such a non-modal GUI
component would be coded roughly as follows:




class MyGUI extends SomeComponent implements IIOParamController {

   public MyGUI() {
       // ...
       setEnabled(false);
   }

   public boolean activate(IIOParam param) {
       // disable other components if desired
       setEnabled(true);
       // go to sleep until either cancelled or committed
       boolean ret = false;
       if (!cancelled) {
           // set values on param
           ret = true;
       }
       setEnabled(false);
       // enable any components disabled above
       return ret;
   }

 Alternatively, an algorithmic process such as a database lookup
or the parsing of a command line could be used as a controller, in
which case the activate method would simply look up or
compute the settings, call the IIOParam.setXXX
methods, and return true.

A class containing static convenience methods for locating
ImageReaders and ImageWriters, and
performing simple encoding and decoding.

An abstract superclass for parsing and decoding of images.  This
class must be subclassed by classes that read in images in the
context of the Java Image I/O framework.

 ImageReader objects are normally instantiated by
the service provider interface (SPI) class for the specific format.
Service provider classes (e.g., instances of
ImageReaderSpi) are registered with the
IIORegistry, which uses them for format recognition
and presentation of available format readers and writers.

 When an input source is set (using the setInput
method), it may be marked as "seek forward only".  This setting
means that images contained within the input source will only be
read in order, possibly allowing the reader to avoid caching
portions of the input containing data associated with images that
have been read previously.

A class describing how a stream is to be decoded.  Instances of
this class or its subclasses are used to supply prescriptive
"how-to" information to instances of ImageReader.

 An image encoded as part of a file or stream may be thought of
extending out in multiple dimensions: the spatial dimensions of
width and height, a number of bands, and a number of progressive
decoding passes.  This class allows a contiguous (hyper)rectangular
subarea of the image in all of these dimensions to be selected for
decoding.  Additionally, the spatial dimensions may be subsampled
discontinuously.  Finally, color and format conversions may be
specified by controlling the ColorModel and
SampleModel of the destination image, either by
providing a BufferedImage or by using an
ImageTypeSpecifier.

 An ImageReadParam object is used to specify how an
image, or a set of images, will be converted on input from
a stream in the context of the Java Image I/O framework.  A plug-in for a
specific image format will return instances of
ImageReadParam from the
getDefaultReadParam method of its
ImageReader implementation.

 The state maintained by an instance of
ImageReadParam is independent of any particular image
being decoded.  When actual decoding takes place, the values set in
the read param are combined with the actual properties of the image
being decoded from the stream and the destination
BufferedImage that will receive the decoded pixel
data.  For example, the source region set using
setSourceRegion will first be intersected with the
actual valid source area.  The result will be translated by the
value returned by getDestinationOffset, and the
resulting rectangle intersected with the actual valid destination
area to yield the destination area that will be written.

 The parameters specified by an ImageReadParam are
applied to an image as follows.  First, if a rendering size has
been set by setSourceRenderSize, the entire decoded
image is rendered at the size given by
getSourceRenderSize.  Otherwise, the image has its
natural size given by ImageReader.getWidth and
ImageReader.getHeight.

 Next, the image is clipped against the source region
specified by getSourceXOffset, getSourceYOffset,
getSourceWidth, and getSourceHeight.

 The resulting region is then subsampled according to the
factors given in IIOParam.setSourceSubsampling.  The first pixel,
the number of pixels per row, and the number of rows all depend
on the subsampling settings.
Call the minimum X and Y coordinates of the resulting rectangle
(minX, minY), its width w
and its height h.

 This rectangle is offset by
(getDestinationOffset().x,
getDestinationOffset().y) and clipped against the
destination bounds.  If no destination image has been set, the
destination is defined to have a width of
getDestinationOffset().x  w, and a
height of getDestinationOffset().y  h so
that all pixels of the source region may be written to the
destination.

 Pixels that land, after subsampling, within the destination
image, and that are written in one of the progressive passes
specified by getSourceMinProgressivePass and
getSourceNumProgressivePasses are passed along to the
next step.

 Finally, the source samples of each pixel are mapped into
destination bands according to the algorithm described in the
comment for setDestinationBands.

 Plug-in writers may extend the functionality of
ImageReadParam by providing a subclass that implements
additional, plug-in specific interfaces.  It is up to the plug-in
to document what interfaces are available and how they are to be
used.  Readers will silently ignore any extended features of an
ImageReadParam subclass of which they are not aware.
Also, they may ignore any optional features that they normally
disable when creating their own ImageReadParam
instances via getDefaultReadParam.

 Note that unless a query method exists for a capability, it must
be supported by all ImageReader implementations
(e.g. source render size is optional, but subsampling must be
supported).

An interface providing metadata transcoding capability.

 Any image may be transcoded (written to a different format
than the one it was originally stored in) simply by performing
a read operation followed by a write operation.  However, loss
of data may occur in this process due to format differences.

 In general, the best results will be achieved when
format-specific metadata objects can be created to encapsulate as
much information about the image and its associated metadata as
possible, in terms that are understood by the specific
ImageWriter used to perform the encoding.

 An ImageTranscoder may be used to convert the
IIOMetadata objects supplied by the
ImageReader (representing per-stream and per-image
metadata) into corresponding objects suitable for encoding by a
particular ImageWriter.  In the case where the methods
of this interface are being called directly on an
ImageWriter, the output will be suitable for that
writer.

 The internal details of converting an IIOMetadata
object into a writer-specific format will vary according to the
context of the operation.  Typically, an ImageWriter
will inspect the incoming object to see if it implements additional
interfaces with which the writer is familiar.  This might be the
case, for example, if the object was obtained by means of a read
operation on a reader plug-in written by the same vendor as the
writer.  In this case, the writer may access the incoming object by
means of its plug-in specific interfaces.  In this case, the
re-encoding may be close to lossless if the image file format is
kept constant.  If the format is changing, the writer may still
attempt to preserve as much information as possible.

 If the incoming object does not implement any additional
interfaces known to the writer, the writer has no choice but to
access it via the standard IIOMetadata interfaces such
as the tree view provided by IIOMetadata.getAsTree.
In this case, there is likely to be significant loss of
information.

 An independent ImageTranscoder essentially takes
on the same role as the writer plug-in in the above examples.  It
must be familiar with the private interfaces used by both the
reader and writer plug-ins, and manually instantiate an object that
will be usable by the writer.  The resulting metadata objects may
be used by the writer directly.

 No independent implementations of ImageTranscoder
are provided as part of the standard API.  Instead, the intention
of this interface is to provide a way for implementations to be
created and discovered by applications as the need arises.

A class that allows the format of an image (in particular, its
SampleModel and ColorModel) to be
specified in a convenient manner.

A class describing how a stream is to be encoded.  Instances of
this class or its subclasses are used to supply prescriptive
"how-to" information to instances of ImageWriter.

 A plug-in for a specific image format may define a subclass of
this class, and return objects of that class from the
getDefaultWriteParam method of its
ImageWriter implementation.  For example, the built-in
JPEG writer plug-in will return instances of
javax.imageio.plugins.jpeg.JPEGImageWriteParam.

 The region of the image to be written is determined by first
intersecting the actual bounds of the image with the rectangle
specified by IIOParam.setSourceRegion, if any.  If the
resulting rectangle has a width or height of zero, the writer will
throw an IIOException. If the intersection is
non-empty, writing will commence with the first subsampled pixel
and include additional pixels within the intersected bounds
according to the horizontal and vertical subsampling factors
specified by IIOParam.setSourceSubsampling.

 Individual features such as tiling, progressive encoding, and
compression may be set in one of four modes.
MODE_DISABLED disables the features;
MODE_DEFAULT enables the feature with
writer-controlled parameter values; MODE_EXPLICIT
enables the feature and allows the use of a set method
to provide additional parameters; and
MODE_COPY_FROM_METADATA copies relevant parameter
values from the stream and image metadata objects passed to the
writer.  The default for all features is
MODE_COPY_FROM_METADATA.  Non-standard features
supplied in subclasses are encouraged, but not required to use a
similar scheme.

 Plug-in writers may extend the functionality of
ImageWriteParam by providing a subclass that implements
additional, plug-in specific interfaces.  It is up to the plug-in
to document what interfaces are available and how they are to be
used.  Writers will silently ignore any extended features of an
ImageWriteParam subclass of which they are not aware.
Also, they may ignore any optional features that they normally
disable when creating their own ImageWriteParam
instances via getDefaultWriteParam.

 Note that unless a query method exists for a capability, it must
be supported by all ImageWriter implementations
(e.g. progressive encoding is optional, but subsampling must be
supported).

An abstract superclass for encoding and writing images.  This class
must be subclassed by classes that write out images in the context
of the Java Image I/O framework.

 ImageWriter objects are normally instantiated by
the service provider class for the specific format.  Service
provider classes are registered with the IIORegistry,
which uses them for format recognition and presentation of
available format readers and writers.

An IIOInvalidTreeException is thrown when an attempt
by an IIOMetadata object to parse a tree of
IIOMetadataNodes fails.  The node that led to the
parsing error may be stored.  As with any parsing error, the actual
error may occur at a different point that that where it is
detected.  The node returned by getOffendingNode
should merely be considered as a clue to the actual nature of the
problem.

An abstract class to be extended by objects that represent metadata
(non-image data) associated with images and streams.  Plug-ins
represent metadata using opaque, plug-in specific objects.  These
objects, however, provide the ability to access their internal
information as a tree of IIOMetadataNode objects that
support the XML DOM interfaces as well as additional interfaces for
storing non-textual data and retrieving information about legal
data values.  The format of such trees is plug-in dependent, but
plug-ins may choose to support a plug-in neutral format described
below.  A single plug-in may support multiple metadata formats,
whose names maybe determined by calling
getMetadataFormatNames.  The plug-in may also support
a single special format, referred to as the "native" format, which
is designed to encode its metadata losslessly.  This format will
typically be designed specifically to work with a specific file
format, so that images may be loaded and saved in the same format
with no loss of metadata, but may be less useful for transferring
metadata between an ImageReader and an
ImageWriter for different image formats.  To convert
between two native formats as losslessly as the image file formats
will allow, an ImageTranscoder object must be used.

An interface to be implemented by objects that can determine the
settings of an IIOMetadata object, either by putting
up a GUI to obtain values from a user, or by other means.  This
interface merely specifies a generic activate method
that invokes the controller, without regard for how the controller
obtains values (i.e., whether the controller puts up a GUI
or merely computes a set of values is irrelevant to this
interface).

 Within the activate method, a controller obtains
initial values by querying the IIOMetadata object's
settings, either using the XML DOM tree or a plug-in specific
interface, modifies values by whatever means, then modifies the
IIOMetadata object's settings, using either the
setFromTree or mergeTree methods, or a
plug-in specific interface.  In general, applications may expect
that when the activate method returns
true, the IIOMetadata object is ready for
use in a write operation.

 Vendors may choose to provide GUIs for the
IIOMetadata subclasses they define for a particular
plug-in.  These can be set up as default controllers in the
corresponding IIOMetadata subclasses.

 Alternatively, an algorithmic process such as a database lookup
or the parsing of a command line could be used as a controller, in
which case the activate method would simply look up or
compute the settings, call methods on IIOMetadata to
set its state, and return true.

An object describing the structure of metadata documents returned
from IIOMetadata.getAsTree and passed to
IIOMetadata.setFromTree and mergeTree.
Document structures are described by a set of constraints on the
type and number of child elements that may belong to a given parent
element type, the names, types, and values of attributes that may
belong to an element, and the type and values of
Object reference that may be stored at a node.

 N.B: classes that implement this interface should contain a
method declared as public static getInstance() which
returns an instance of the class.  Commonly, an implementation will
construct only a single instance and cache it for future
invocations of getInstance.

 The structures that may be described by this class are a subset
of those expressible using XML document type definitions (DTDs),
with the addition of some basic information on the datatypes of
attributes and the ability to store an Object
reference within a node.  In the future, XML Schemas could be used
to represent these structures, and many others.

 The differences between
IIOMetadataFormat-described structures and DTDs are as
follows:


 Elements may not contain text or mix text with embedded
tags.

 The children of an element must conform to one of a few simple
patterns, described in the documentation for the
CHILD_* constants;

 The in-memory representation of an elements may contain a
reference to an Object.  There is no provision for
representing such objects textually.

A concrete class providing a reusable implementation of the
IIOMetadataFormat interface.  In addition, a static
instance representing the standard, plug-in neutral
javax_imageio_1.0 format is provided by the
getStandardFormatInstance method.

 In order to supply localized descriptions of elements and
attributes, a ResourceBundle with a base name of
this.getClass().getName()  "Resources" should be
supplied via the usual mechanism used by
ResourceBundle.getBundle.  Briefly, the subclasser
supplies one or more additional classes according to a naming
convention (by default, the fully-qualified name of the subclass
extending IIMetadataFormatImpl, plus the string
"Resources", plus the country, language, and variant codes
separated by underscores).  At run time, calls to
getElementDescription or
getAttributeDescription will attempt to load such
classes dynamically according to the supplied locale, and will use
either the element name, or the element name followed by a '/'
character followed by the attribute name as a key.  This key will
be supplied to the ResourceBundle's
getString method, and the resulting localized
description of the node or attribute is returned.

 The subclass may supply a different base name for the resource
bundles using the setResourceBaseName method.

 A subclass may choose its own localization mechanism, if so
desired, by overriding the supplied implementations of
getElementDescription and
getAttributeDescription.

A class representing a node in a meta-data tree, which implements
the
org.w3c.dom.Element interface and additionally allows
for the storage of non-textual objects via the
getUserObject and setUserObject methods.

 This class is not intended to be used for general XML
processing. In particular, Element nodes created
within the Image I/O API are not compatible with those created by
Sun's standard implementation of the org.w3.dom API.
In particular, the implementation is tuned for simple uses and may
not perform well for intensive processing.

 Namespaces are ignored in this implementation.  The terms "tag
name" and "node name" are always considered to be synonymous.

Note:
The DOM Level 3 specification added a number of new methods to the
Node, Element and Attr interfaces that are not
of value to the IIOMetadataNode implementation or specification.

Calling such methods on an IIOMetadataNode, or an Attr
instance returned from an IIOMetadataNode will result in a
DOMException being thrown.

A subclass of ImageWriteParam for encoding images in
the BMP format.

 This class allows for the specification of various parameters
while writing a BMP format image file.  By default, the data layout
is bottom-up, such that the pixels are stored in bottom-up order,
the first scanline being stored last.

The particular compression scheme to be used can be specified by using
the setCompressionType() method with the appropriate type
string.  The compression scheme specified will be honored if and only if it
is compatible with the type of image being written. If the specified
compression scheme is not compatible with the type of image being written
then the IOException will be thrown by the BMP image writer.
If the compression type is not set explicitly then getCompressionType()
will return null. In this case the BMP image writer will select
a compression type that supports encoding of the given image without loss
of the color resolution.
The compression type strings and the image type(s) each supports are
listed in the following
table:


Compression Types
Type String Description  Image Types
BI_RGB  Uncompressed RLE <=  8-bits/sample
BI_RLE8 8-bit Run Length Encoding <= 8-bits/sample
BI_RLE4 4-bit Run Length Encoding <= 4-bits/sample
BI_BITFIELDS Packed data  16 or 32 bits/sample

A class encapsulating a single JPEG Huffman table.
Fields are provided for the "standard" tables taken
from Annex K of the JPEG specification.
These are the tables used as defaults.

For more information about the operation of the standard JPEG plug-in,
see the JPEG
metadata format specification and usage notes

This class adds the ability to set JPEG quantization and Huffman
tables when using the built-in JPEG reader plug-in.  An instance of
this class will be returned from the
getDefaultImageReadParam methods of the built-in JPEG
ImageReader.

 The sole purpose of these additions is to allow the
specification of tables for use in decoding abbreviated streams.
The built-in JPEG reader will also accept an ordinary
ImageReadParam, which is sufficient for decoding
non-abbreviated streams.

 While tables for abbreviated streams are often obtained by
first reading another abbreviated stream containing only the
tables, in some applications the tables are fixed ahead of time.
This class allows the tables to be specified directly from client
code.  If no tables are specified either in the stream or in a
JPEGImageReadParam, then the stream is presumed to use
the "standard" visually lossless tables.  See JPEGQTable
and JPEGHuffmanTable for more information
 on the default tables.

 The default JPEGImageReadParam returned by the
getDefaultReadParam method of the builtin JPEG reader
contains no tables.  Default tables may be obtained from the table
classes JPEGQTable and
JPEGHuffmanTable.

 If a stream does contain tables, the tables given in a
JPEGImageReadParam are ignored.  Furthermore, if the
first image in a stream does contain tables and subsequent ones do
not, then the tables given in the first image are used for all the
abbreviated images.  Once tables have been read from a stream, they
can be overridden only by tables subsequently read from the same
stream.  In order to specify new tables, the setInput method of
the reader must be called to change the stream.

 Note that this class does not provide a means for obtaining the
tables found in a stream.  These may be extracted from a stream by
consulting the IIOMetadata object returned by the reader.


For more information about the operation of the built-in JPEG plug-ins,
see the JPEG
metadata format specification and usage notes.

This class adds the ability to set JPEG quantization and Huffman
tables when using the built-in JPEG writer plug-in, and to request that
optimized Huffman tables be computed for an image.  An instance of
this class will be returned from the
getDefaultImageWriteParam methods of the built-in JPEG
ImageWriter.

 The principal purpose of these additions is to allow the
specification of tables to use in encoding abbreviated streams.
The built-in JPEG writer will also accept an ordinary
ImageWriteParam, in which case the writer will
construct the necessary tables internally.

 In either case, the quality setting in an ImageWriteParam
has the same meaning as for the underlying library: 1.00 means a
quantization table of all 1's, 0.75 means the "standard", visually
lossless quantization table, and 0.00 means aquantization table of
all 255's.

 While tables for abbreviated streams are often specified by
first writing an abbreviated stream containing only the tables, in
some applications the tables are fixed ahead of time.  This class
allows the tables to be specified directly from client code.

 Normally, the tables are specified in the
IIOMetadata objects passed in to the writer, and any
tables included in these objects are written to the stream.
If no tables are specified in the metadata, then an abbreviated
stream is written.  If no tables are included in the metadata and
no tables are specified in a JPEGImageWriteParam, then
an abbreviated stream is encoded using the "standard" visually
lossless tables.  This class is necessary for specifying tables
when an abbreviated stream must be written without writing any tables
to a stream first.  In order to use this class, the metadata object
passed into the writer must contain no tables, and no stream metadata
must be provided.  See JPEGQTable and
JPEGHuffmanTable for more
information on the default tables.

 The default JPEGImageWriteParam returned by the
getDefaultWriteParam method of the writer contains no
tables.  Default tables are included in the default
IIOMetadata objects returned by the writer.

 If the metadata does contain tables, the tables given in a
JPEGImageWriteParam are ignored.  Furthermore, once a
set of tables has been written, only tables in the metadata can
override them for subsequent writes, whether to the same stream or
a different one.  In order to specify new tables using this class,
the reset
method of the writer must be called.


For more information about the operation of the built-in JPEG plug-ins,
see the JPEG
metadata format specification and usage notes.

A class encapsulating a single JPEG quantization table.
The elements appear in natural order (as opposed to zig-zag order).
Static variables are provided for the "standard" tables taken from
 Annex K of the JPEG specification, as well as the default tables
conventionally used for visually lossless encoding.

For more information about the operation of the standard JPEG plug-in,
see the JPEG
metadata format specification and usage notes

A registry for service provider instances.  Service provider
classes may be detected at run time by means of meta-information in
the JAR files containing them.  The intent is that it be relatively
inexpensive to load and inspect all available service provider
classes.  These classes may them be used to locate and instantiate
more heavyweight classes that will perform actual work, in this
case instances of ImageReader,
ImageWriter, ImageTranscoder,
ImageInputStream, and ImageOutputStream.

 Service providers found on the system classpath (typically
the lib/ext directory in the Java
installation directory) are automatically loaded as soon as this class is
instantiated.

 When the registerApplicationClasspathSpis method
is called, service provider instances declared in the
meta-information section of JAR files on the application class path
are loaded.  To declare a service provider, a services
subdirectory is placed within the META-INF directory
that is present in every JAR file.  This directory contains a file
for each service provider interface that has one or more
implementation classes present in the JAR file.  For example, if
the JAR file contained a class named
com.mycompany.imageio.MyFormatReaderSpi which
implements the ImageReaderSpi interface, the JAR file
would contain a file named:



META-INF/services/javax.imageio.spi.ImageReaderSpi

containing the line:



com.mycompany.imageio.MyFormatReaderSpi

 The service provider classes are intended to be lightweight
and quick to load.  Implementations of these interfaces
should avoid complex dependencies on other classes and on
native code.

 It is also possible to manually add service providers not found
automatically, as well as to remove those that are using the
interfaces of the ServiceRegistry class.  Thus
the application may customize the contents of the registry as it
sees fit.

 For more details on declaring service providers, and the JAR
format in general, see the
JAR File Specification.

A superinterface for functionality common to all Image I/O service
provider interfaces (SPIs).  For more information on service
provider classes, see the class comment for the
IIORegistry class.

The service provider interface (SPI) for
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.

The service provider interface (SPI) for
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.

The service provider interface (SPI) for ImageReaders.
For more information on service provider classes, see the class comment
for the IIORegistry class.

 Each ImageReaderSpi provides several types of information
about the ImageReader class with which it is associated.

 The name of the vendor who defined the SPI class and a
brief description of the class are available via the
getVendorName, getDescription,
and getVersion methods.
These methods may be internationalized to provide locale-specific
output.  These methods are intended mainly to provide short,
human-readable information that might be used to organize a pop-up
menu or other list.

 Lists of format names, file suffixes, and MIME types associated
with the service may be obtained by means of the
getFormatNames, getFileSuffixes, and
getMIMETypes methods.  These methods may be used to
identify candidate ImageReaders for decoding a
particular file or stream based on manual format selection, file
naming, or MIME associations (for example, when accessing a file
over HTTP or as an email attachment).

 A more reliable way to determine which ImageReaders
are likely to be able to parse a particular data stream is provided
by the canDecodeInput method.  This methods allows the
service provider to inspect the actual stream contents.

 Finally, an instance of the ImageReader class
associated with this service provider may be obtained by calling
the createReaderInstance method.  Any heavyweight
initialization, such as the loading of native libraries or creation
of large tables, should be deferred at least until the first
invocation of this method.

A superclass containing instance variables and methods common to
ImageReaderSpi and ImageWriterSpi.

The service provider interface (SPI) for ImageTranscoders.
For more information on service provider classes, see the class comment
for the IIORegistry class.

The service provider interface (SPI) for ImageWriters.
For more information on service provider classes, see the class comment
for the IIORegistry class.

 Each ImageWriterSpi provides several types of information
about the ImageWriter class with which it is associated.

 The name of the vendor who defined the SPI class and a
brief description of the class are available via the
getVendorName, getDescription,
and getVersion methods.
These methods may be internationalized to provide locale-specific
output.  These methods are intended mainly to provide short,
human-writable information that might be used to organize a pop-up
menu or other list.

 Lists of format names, file suffixes, and MIME types associated
with the service may be obtained by means of the
getFormatNames, getFileSuffixes, and
getMIMEType methods.  These methods may be used to
identify candidate ImageWriters for writing a
particular file or stream based on manual format selection, file
naming, or MIME associations.

 A more reliable way to determine which ImageWriters
are likely to be able to parse a particular data stream is provided
by the canEncodeImage method.  This methods allows the
service provider to inspect the actual image contents.

 Finally, an instance of the ImageWriter class
associated with this service provider may be obtained by calling
the createWriterInstance method.  Any heavyweight
initialization, such as the loading of native libraries or creation
of large tables, should be deferred at least until the first
invocation of this method.

An optional interface that may be provided by service provider
objects that will be registered with a
ServiceRegistry.  If this interface is present,
notification of registration and deregistration will be performed.

A registry for service provider instances.

 A service is a well-known set of interfaces and (usually
abstract) classes.  A service provider is a specific
implementation of a service.  The classes in a provider typically
implement the interface or subclass the class defined by the
service itself.

 Service providers are stored in one or more categories,
each of which is defined by a class of interface (described by a
Class object) that all of its members must implement.
The set of categories may be changed dynamically.

 Only a single instance of a given leaf class (that is, the
actual class returned by getClass(), as opposed to any
inherited classes or interfaces) may be registered.  That is,
suppose that the
com.mycompany.mypkg.GreenServiceProvider class
implements the com.mycompany.mypkg.MyService
interface.  If a GreenServiceProvider instance is
registered, it will be stored in the category defined by the
MyService class.  If a new instance of
GreenServiceProvider is registered, it will replace
the previous instance.  In practice, service provider objects are
usually singletons so this behavior is appropriate.

 To declare a service provider, a services
subdirectory is placed within the META-INF directory
that is present in every JAR file.  This directory contains a file
for each service provider interface that has one or more
implementation classes present in the JAR file.  For example, if
the JAR file contained a class named
com.mycompany.mypkg.MyServiceImpl which implements the
javax.someapi.SomeService interface, the JAR file
would contain a file named:

META-INF/services/javax.someapi.SomeService

containing the line:



com.mycompany.mypkg.MyService

 The service provider classes should be to be lightweight and
quick to load.  Implementations of these interfaces should avoid
complex dependencies on other classes and on native code. The usual
pattern for more complex services is to register a lightweight
proxy for the heavyweight service.

 An application may customize the contents of a registry as it
sees fit, so long as it has the appropriate runtime permission.

 For more details on declaring service providers, and the JAR
format in general, see the
JAR File Specification.

A simple filter interface used by
ServiceRegistry.getServiceProviders to select
providers matching an arbitrary criterion.  Classes that
implement this interface should be defined in order to make use
of the getServiceProviders method of
ServiceRegistry that takes a Filter.

An implementation of ImageInputStream that gets its
input from a regular InputStream.  A file is used to
cache previously read data.

An implementation of ImageOutputStream that writes its
output to a regular OutputStream.  A file is used to
cache data until it is flushed to the output stream.

An implementation of ImageInputStream that gets its
input from a File or RandomAccessFile.
The file contents are assumed to be stable during the lifetime of
the object.

An implementation of ImageOutputStream that writes its
output directly to a File or
RandomAccessFile.

A class representing a mutable reference to an array of bytes and
an offset and length within that array.  IIOByteBuffer
is used by ImageInputStream to supply a sequence of bytes
to the caller, possibly with fewer copies than using the conventional
read methods that take a user-supplied byte array.

 The byte array referenced by an IIOByteBuffer will
generally be part of an internal data structure belonging to an
ImageReader implementation; its contents should be
considered read-only and must not be modified.

A seekable input stream interface for use by
ImageReaders.  Various input sources, such as
InputStreams and Files,
as well as future fast I/O sources may be "wrapped" by a suitable
implementation of this interface for use by the Image I/O API.

An abstract class implementing the ImageInputStream interface.
This class is designed to reduce the number of methods that must
be implemented by subclasses.

 In particular, this class handles most or all of the details of
byte order interpretation, buffering, mark/reset, discarding,
closing, and disposing.

A seekable output stream interface for use by
ImageWriters.  Various output destinations, such as
OutputStreams and Files, as well as
future fast I/O destinations may be "wrapped" by a suitable
implementation of this interface for use by the Image I/O API.

 Unlike a standard OutputStream, ImageOutputStream
extends its counterpart, ImageInputStream.  Thus it is
possible to read from the stream as it is being written.  The same
seek and flush positions apply to both reading and writing, although
the semantics for dealing with a non-zero bit offset before a byte-aligned
write are necessarily different from the semantics for dealing with
a non-zero bit offset before a byte-aligned read.  When reading bytes,
any bit offset is set to 0 before the read; when writing bytes, a
non-zero bit offset causes the remaining bits in the byte to be written
as 0s.  The byte-aligned write then starts at the next byte position.

An abstract class implementing the ImageOutputStream interface.
This class is designed to reduce the number of methods that must
be implemented by subclasses.

An implementation of ImageInputStream that gets its
input from a regular InputStream.  A memory buffer is
used to cache at least the data between the discard position and
the current read position.

 In general, it is preferable to use a
FileCacheImageInputStream when reading from a regular
InputStream.  This class is provided for cases where
it is not possible to create a writable temporary file.

An implementation of ImageOutputStream that writes its
output to a regular OutputStream.  A memory buffer is
used to cache at least the data between the discard position and
the current write position.  The only constructor takes an
OutputStream, so this class may not be used for
read/modify/write operations.  Reading can occur only on parts of
the stream that have already been written to the cache and not
yet flushed.