001: /*
002: * $RCSfile: ImagingListener.java,v $
003: *
004: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Use is subject to license terms.
007: *
008: * $Revision: 1.1 $
009: * $Date: 2005/02/11 04:57:57 $
010: * $State: Exp $
011: */
012: package javax.media.jai.util;
013:
014: /**
015: * An <code> ImagingListener</code> has the capability to report the
016: * abnormal situations in the image processing procedures.
017: * The concrete class either holds the reported information and processes
018: * it, or passes them to other processing or logging mechanisms.
019: *
020: * <p> A default <code>ImagingListener</code> resides in an instance of
021: * <code>JAI</code> (by calling the method
022: * <code>setImagingListener</code>), and can be retrieved by calling
023: * the method <code>getImagingListener</code>. This listener should not
024: * propagate the <code>Throwable</code> reported from an
025: * <code>OperationRegistry</code>. Otherwise, it may break the loop through
026: * the image factories. The typical <code>JAI</code> to be used will
027: * be the default JAI instance.
028: *
029: * <p> An <code>ImagingListener</code> can also be attached to a rendering node
030: * as a rendering hint with a key <code>JAI.KEY_IMAGING_LISTENER</code>.
031: * This listener can monitor errors occurring in the rendering process.
032: * The default value for this rendering hint is the listener registered
033: * to the default <code>JAI</code> instance.
034: *
035: * <p> The typical situations where <code>ImagingListener</code>
036: * objects can be called are:
037: * (1) The <code>create</code> method of a concrete
038: * <code>RenderedImageFactory</code> or
039: * <code>ContextualRenderedImageFactory</code>. (2) The rendering of the node.
040: * For the latter case, the I/O, network, and arithmetic problems
041: * will be reported.
042: *
043: * <p> When errors are encountered in user-written operations, those
044: * operations have two choices. The typical choice will be to simply
045: * throw an exception and let the JAI framework call
046: * <code>errorOccurred</code>. However, it is also acceptable to
047: * obtain the proper <code>ImagingListener</code> and call
048: * <code>errorOccurred</code> directly. This might be useful if
049: * for example special retry options were available to the user
050: * operation. Care should be taken in this case to avoid an
051: * infinite retry loop.
052: *
053: * <p> For backward compatibility, an instance of a simple
054: * implementation of this interface is used as the default in all the
055: * <code>JAI</code> instances. It re-throws the <code>Throwable</code>
056: * if it is a <code>RuntimeException</code>. For the other types of
057: * <code>Throwable</code>, it only prints the message and the stack trace
058: * to the stream <code>System.err</code>, and returns <code>false</code>.
059: * To process the reported errors or warnings an alternate implementation
060: * of <code>ImagingListener</code> should be written.</p>
061: *
062: * <p> The provided <code>Throwable</code>, its cause, or its root cause
063: * may be re-thrown directly, or wrapped into a subclass of
064: * <code>RuntimeException</code> and thrown if this listener cannot
065: * handle it properly, in which case the <code>Throwable</code> will
066: * be propogated back to the calling application.
067: *
068: * <p> In the JAI 1.1.2 implementation from Sun, when the method
069: * <code>errorOccurred</code> is called, the parameter
070: * <code>isRetryable</code> is always <code>false</code>; future
071: * implementations may activate retry capability.</p>
072: *
073: * @since JAI 1.1.2
074: */
075: public interface ImagingListener {
076: /**
077: * Reports the occurrence of an error or warning generated
078: * from JAI or one of its operation nodes.
079: *
080: * @param message The message that describes what is reported.
081: * @param thrown The <code>Throwable</code> that caused this
082: * method to be called..
083: * @param where The object from which this <code>Throwable</code> is caught
084: * and sent to this listener. The typical type for this
085: * argument will be <code>RenderedOp</code>,
086: * <code>OpImage</code>, <code>RenderedImageFactory</code>,
087: * or other image types such as the
088: * <code>RenderedImage</code> generated from codecs.
089: * @param isRetryable Indicates whether or not the caller is capable of
090: * retrying the operation, if the problem is corrected
091: * in this method. If this parameter is <code>false</code>,
092: * the return value should also be <code>false</code>.
093: * This parameter can be used to stop the retry, e.g.,
094: * if a maximum retry number is reached.
095: *
096: * @return Returns <code>true</code> if the recovery is a success
097: * and the caller should attempt a retry; otherwise
098: * returns <code>false</code> (in which case no retry
099: * should be attempted). The return value may be
100: * ignored by the caller if <code>isRetryable</code>
101: * is <code>false</code>.
102: * @throws RuntimeException Propagates the <code>Throwable</code> to
103: * the caller.
104: */
105: boolean errorOccurred(String message, Throwable thrown,
106: Object where, boolean isRetryable) throws RuntimeException;
107: }
|