javax.media.jai.util
Interface ImagingListener

public interface ImagingListener

An 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.

Since:

JAI 1.1.2

Method Summary

boolean

errorOccurred(String message, Throwable thrown, Object where, boolean isRetryable) Reports the occurrence of an error or warning generated from JAI or one of its operation nodes.

Method Detail

errorOccurred

public boolean errorOccurred(String message,
                             Throwable thrown,
                             Object where,
                             boolean isRetryable)
                      throws RuntimeException

Reports the occurrence of an error or warning generated from JAI or one of its operation nodes.

Parameters:

message - The message that describes what is reported.

thrown - The Throwable that caused this method to be called..

where - The object from which this Throwable is caught and sent to this listener. The typical type for this argument will be RenderedOp, OpImage, RenderedImageFactory, or other image types such as the RenderedImage generated from codecs.

isRetryable - Indicates whether or not the caller is capable of retrying the operation, if the problem is corrected in this method. If this parameter is false, the return value should also be false. This parameter can be used to stop the retry, e.g., if a maximum retry number is reached.

Returns:

Returns true if the recovery is a success and the caller should attempt a retry; otherwise returns false (in which case no retry should be attempted). The return value may be ignored by the caller if isRetryable is false.

Throws:

RuntimeException - Propagates the Throwable to the caller.