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.

errorOccurred

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.