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   * Document me.
24   * 
25   * @author <a href="mailto:dev@directory.apache.org"> Apache Directory
26   *         Project</a> $Rev: 161723 $
27   */
28  public interface EncoderMonitor
29  {
30      /*** Use this if you don't want to recreate this as just a NOOP monitor */
31      public EncoderMonitor INSTANCE = new EncoderMonitorAdapter();
32  
33      /***
34       * Receive notification of a recoverable error.  This callback is used to
35       * denote a failure to handle a unit of data to be encoded or decoded.  The
36       * entire [en|de]codable unit is lost but the [en|de]coding operation can
37       * still proceed.
38       *
39       * @param encoder the encoder that had the error
40       * @param exception the error information encapsulated in an exception
41       */
42      void error( StatefulEncoder encoder, Exception exception ) ;
43  
44      /***
45       * Receive notification of a non-recoverable error.  The application must
46       * assume that the stream data is unusable after the encoder has invoked
47       * this method, and should continue (if at all) only for the sake of
48       * collecting addition error messages: in fact, encoders are free to stop
49       * reporting any other events once this method has been invoked.
50       *
51       * @param encoder the encoder that had the failure
52       * @param exception the warning information encapsulated in an exception
53       */
54      void fatalError( StatefulEncoder encoder, Exception exception ) ;
55  
56      /***
57       * Receive notification of a warning.  The encoder must continue to provide
58       * normal callbacks after invoking this method: it should still be possible
59       * for the application to process the encoded data through to the end.
60       *
61       * @param encoder the encoder that had the error
62       * @param exception the warning information encapsulated in an exception
63       */
64      void warning( StatefulEncoder encoder, Exception exception ) ;
65  
66      /***
67       * Monitors callbacks that deliver a fully decoded object.
68       *
69       * @param encoder the stateful encoder driving the callback
70       * @param decoded the object that was decoded
71       */
72      void callbackOccured( StatefulEncoder encoder, EncoderCallback cb,
73  						  Object decoded ) ;
74  
75      /***
76       * Monitors changes to the callback.
77       *
78       * @param encoder the encoder whose callback was set
79       * @param oldcb the unset old callback, or null if none was set
80       * @param newcb the newly set callback, or null if callback is cleared
81       */
82      void callbackSet( StatefulEncoder encoder, EncoderCallback oldcb,
83  					  EncoderCallback newcb ) ;
84  }