ImagingListener has the capability to report the abnormal situations in the image processing procedures. The concrete class either holds the reported information and processes it, or passes them to other processing or logging mechanisms. A default ImagingListener resides in an instance of JAI (by calling the method setImagingListener), and can be retrieved by calling the method getImagingListener. This listener should not propagate the Throwable reported from an OperationRegistry. Otherwise, it may break the loop through the image factories. The typical JAI to be used will be the default JAI instance.
An ImagingListener can also be attached to a rendering node as a rendering hint with a key JAI.KEY_IMAGING_LISTENER. This listener can monitor errors occurring in the rendering process. The default value for this rendering hint is the listener registered to the default JAI instance.
The typical situations where ImagingListener objects can be called are: (1) The create method of a concrete RenderedImageFactory or ContextualRenderedImageFactory. (2) The rendering of the node. For the latter case, the I/O, network, and arithmetic problems will be reported.
When errors are encountered in user-written operations, those operations have two choices. The typical choice will be to simply throw an exception and let the JAI framework call errorOccurred. However, it is also acceptable to obtain the proper ImagingListener and call errorOccurred directly. This might be useful if for example special retry options were available to the user operation. Care should be taken in this case to avoid an infinite retry loop.
For backward compatibility, an instance of a simple implementation of this interface is used as the default in all the JAI instances. It re-throws the Throwable if it is a RuntimeException. For the other types of Throwable, it only prints the message and the stack trace to the stream System.err, and returns false. To process the reported errors or warnings an alternate implementation of ImagingListener should be written.
The provided Throwable, its cause, or its root cause may be re-thrown directly, or wrapped into a subclass of RuntimeException and thrown if this listener cannot handle it properly, in which case the Throwable will be propogated back to the calling application.
In the JAI 1.1.2 implementation from Sun, when the method errorOccurred is called, the parameter isRetryable is always false; future implementations may activate retry capability.
| |