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.