View Javadoc

1   /*
2    *   Copyright 2004 The Apache Software Foundation
3    *
4    *   Licensed under the Apache License, Version 2.0 (the "License");
5    *   you may not use this file except in compliance with the License.
6    *   You may obtain a copy of the License at
7    *
8    *       http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *   Unless required by applicable law or agreed to in writing, software
11   *   distributed under the License is distributed on an "AS IS" BASIS,
12   *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *   See the License for the specific language governing permissions and
14   *   limitations under the License.
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  }