3.7 Listening for Events

As an image is being read or written, the plug-in may provide updates to the 
application. The application may provide one or more classes that implement 
interfaces from the javax.image.event package. Instances of these classes are then 
added to the ImageReader or ImageWriter being used. For example,

class MyReadProgressListener implements IIOReadProgressListener {

	public MyReadProgressListener() {}

	public void imageStarted(ImageReader source) {
		System.out.println("Started reading!");
	}

	// Other methods from IIOReadProgressListener omitted
}

IIOReadProgressListener listener = new MyReadProgressListener();
reader.addIIOReadProgressListener(listener);

As the ImageReader.read method progresses, methods on listener will be called at various times to indicate how much of the image has been read. Because these methods are being called while ImageReader.read is active, they must not call most methods from the same ImageReader object. They may call ImageReader.abort(), which will cause ImageReader.read to return even if it is only partially complete.

3.7.1 The IIOReadProgressListener Interface

An IIOReadProgressListener may be used to provide simple status information during reading. An estimate of the percentage of completion of a read is provided, which may be used to update a Swing JProgressBar or other progress indicator, or to estimate the time remaining to read a large image.

The imageStarted method will be called at the start of the read. During the read, the imageProgress method will be called multiple times, each time with a different, increasing value for its percentageDone parameter. When the read is about to complete, the imageComplete method will be called.

Similarly, the thumbnailStarted, thumbnailProgress, and thumbnailComplete methods will be called during thumbnail reads.

Other methods exist to indicate the start and end of a sequence of image reads performed by the ImageReader.readAll method. Additionally, it is possible for an ongoing read to be aborted using the ImageReader.abort method; in this case, the listener's readAborted method will be called.

3.7.2 The IIOReadUpdateListener Interface

An IIOReadUpdateListener provides more detailed information on the progress of an image read. Some image formats allow interlaced or progressive encoding, in which a subset of the pixel data is made available quickly, so that a crude version of the image may be displayed while the remainder of the pixel data is still being received and decoded. A typical scheme might begin by sending only every fourth row, and only every fourth pixel in each of those rows, so that the initial image requires only one sixteenth of the total amount of data to be transmitted and decoded. If interlacing were not used, only the top one-sixteenth of the image would be displayed in the same amount of time. Thus, a person viewing an interlaced image will be able to get a sense of its contents much sooner than if a traditional left-to-right, top-to-bottom order were used.

By implementing the methods of the IIOReadUpdateListener interface, an application class can receive notification when groups of possibly non-contiguous pixels are ready to be displayed. These methods also receive a reference to the BufferedImage that is in the process of being filled in, which may be used to refresh the display to include the newly decoded pixels.

When decoding an interlaced or progressive image, the decoding proceeds in multiple passes. At the start of each pass, the listener's passStarted method will be called to indicate the set of pixels that may be overwritten during the following pass. This estimate is conservative; not every pixel in the region will necessarily be updated during the pass. As the pass progresses, the imageUpdate method will be called with arguments describing the region of pixels that have receive new values. This region is described by the coordinates of its upper-left corner, its width and height, and the spacing between the pixels that make up the pass (in the example above, both parameters would be equal to 4 for the initial pass). When a pass has completed, the passComplete method is called. Similar methods allow the progress of thumbnail image reads to be tracked.

3.7.3 The IIOReadWarningListener Interface

By attaching an IIOReadWarningListener to an ImageReader, information on non-fatal errors may be received. For example, a reader might detect a tag or chunk that should not be present. Even though the reader may choose to ignore the error and proceed with decoding, it may wish to inform the application that the input source was malformed, as this could indicate problems in the application that generated the images.

ImageReaders may specify a set of Locales for which they can provide localized warning messages. The set of available locales can be obtained from the reader's getAvailableLocales method. The desired locale should then be set by calling the reader's setLocale method prior to attaching the IIOReadWarningListener. Each listener will receive messages in the Locale that was in effect at the time it was attached to the reader.

3.7.4 The IIOWriteProgressListener and IIOWriteWarningListener Interfaces

The IIOWriteProgressListener and IIOWriteWarningListener interfaces function similarly to their reader counterparts.