4.2 Embedding Plug-ins in JAR Files

Since a plug-in consists of several classes, the JAR file mechanism is used to allow them to be combined into a single file. In addition to class files, JAR files may contain additional files used to describe their contents. In particular, a JAR file may contain a META-INF/services directory that is used to list any service providers that are contained in the file. For each service provider interface that is implemented by a class stored in the JAR file, a file whose name is the fully-qualified class name of the service provider interface is placed within the services directory. The file should contain the fully-qualified class names of the implementation classes present in the JAR file, one per line. For example, if the JAR file contains a service provider class named com.mycompany.mypackage.MyImageReaderSpi, which implements the javax.imageio.spi.ImageReaderSpi interface, there should be a file named META-INF/services/javax.imageio.spi.ImageReaderSpi containing the line com.mycompany.mypackage.MyImageReaderSpi.

The Image I/O API will automatically examine any JAR files that are found on the class path, and identify those that contain Image I/O plug-ins. For each plug-in found, a single instance of its service provider class will be instantiated and stored in a run-time registry class, javax.iamgeio.spi.IIORegistry.

JAR files on the application class path (i.e., the path set using the CLASSPATH variable), or elsewhere (e.g., available via a network URL) may be loaded by the application. They are not loaded by default in order to minimize startup time.

The javax.imageio.spi.IIORegistry class may also be used at run-time to deregister installed plug-ins and to register new ones. In particular, it is possible to use a ClassLoader to load a plug-in over the network, which may then be registered and used exactly like a locally installed plug-in.

Most applications should not need to deal directly with the registry. Instead, they may make use of convenience methods contained within the javax.imageio.ImageIO class that search for appropriate plug-ins automatically.