1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.asn1.codec.stateful ;
18
19
20
21
22 /***
23 * Monitors decoder activity. This class borrowed some from the <code>
24 * org.xml.sax.ErrorHandler</code> interface and its documentation. A monitor
25 * is a generalized callback for any sort of activity used for tracking both
26 * successes and failures. So you'll realize similarities between monitors
27 * and callbacks especially where the callbackOccurred() method is concerned.
28 *
29 * @author <a href="mailto:dev@directory.apache.org">
30 * Apache Directory Project</a>
31 * @version $Rev: 161723 $
32 */
33 public interface DecoderMonitor
34 {
35 /***
36 * Receive notification of a recoverable error. This callback is used to
37 * denote a failure to handle a unit of data to be encoded or decoded. The
38 * entire [en|de]codable unit is lost but the [en|de]coding operation can
39 * still proceed.
40 *
41 * @param decoder the decoder that had the error
42 * @param exception the error information encapsulated in an exception
43 */
44 void error( StatefulDecoder decoder, Exception exception ) ;
45
46 /***
47 * Receive notification of a non-recoverable error. The application must
48 * assume that the stream data is unusable after the decoder has invoked
49 * this method, and should continue (if at all) only for the sake of
50 * collecting addition error messages: in fact, decoders are free to stop
51 * reporting any other events once this method has been invoked.
52 *
53 * @param decoder the decoder that had the failure
54 * @param exception the warning information encapsulated in an exception
55 */
56 void fatalError( StatefulDecoder decoder, Exception exception ) ;
57
58 /***
59 * Receive notification of a warning. The decoder must continue to provide
60 * normal callbacks after invoking this method: it should still be possible
61 * for the application to process the encoded data through to the end.
62 *
63 * @param decoder the decoder that had the error
64 * @param exception the warning information encapsulated in an exception
65 */
66 void warning( StatefulDecoder decoder, Exception exception ) ;
67
68 /***
69 * Monitors callbacks that deliver a fully decoded object.
70 *
71 * @param decoder the stateful decoder driving the callback
72 * @param decoded the object that was decoded
73 */
74 void callbackOccured( StatefulDecoder decoder, DecoderCallback cb,
75 Object decoded ) ;
76
77 /***
78 * Monitors changes to the callback.
79 *
80 * @param decoder the decoder whose callback was set
81 * @param oldcb the unset old callback, or null if none was set
82 * @param newcb the newly set callback, or null if callback is cleared
83 */
84 void callbackSet( StatefulDecoder decoder, DecoderCallback oldcb,
85 DecoderCallback newcb ) ;
86 }