001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 *
019 */
020 package org.apache.directory.shared.asn1.codec.stateful;
021
022
023 /**
024 * Monitors decoder activity. This class borrowed some from the <code>
025 * org.xml.sax.ErrorHandler</code>
026 * interface and its documentation. A monitor is a generalized callback for any
027 * sort of activity used for tracking both successes and failures. So you'll
028 * realize similarities between monitors and callbacks especially where the
029 * callbackOccurred() method is concerned.
030 *
031 * @author <a href="mailto:dev@directory.apache.org"> Apache Directory Project</a>
032 * @version $Rev: 664290 $
033 */
034 public interface DecoderMonitor
035 {
036 /**
037 * Receive notification of a recoverable error. This callback is used to
038 * denote a failure to handle a unit of data to be encoded or decoded. The
039 * entire [en|de]codable unit is lost but the [en|de]coding operation can
040 * still proceed.
041 *
042 * @param decoder
043 * the decoder that had the error
044 * @param exception
045 * the error information encapsulated in an exception
046 */
047 void error( StatefulDecoder decoder, Exception exception );
048
049
050 /**
051 * Receive notification of a non-recoverable error. The application must
052 * assume that the stream data is unusable after the decoder has invoked
053 * this method, and should continue (if at all) only for the sake of
054 * collecting addition error messages: in fact, decoders are free to stop
055 * reporting any other events once this method has been invoked.
056 *
057 * @param decoder
058 * the decoder that had the failure
059 * @param exception
060 * the warning information encapsulated in an exception
061 */
062 void fatalError( StatefulDecoder decoder, Exception exception );
063
064
065 /**
066 * Receive notification of a warning. The decoder must continue to provide
067 * normal callbacks after invoking this method: it should still be possible
068 * for the application to process the encoded data through to the end.
069 *
070 * @param decoder
071 * the decoder that had the error
072 * @param exception
073 * the warning information encapsulated in an exception
074 */
075 void warning( StatefulDecoder decoder, Exception exception );
076
077
078 /**
079 * Monitors callbacks that deliver a fully decoded object.
080 *
081 * @param decoder the stateful decoder driving the callback
082 * @param cb the callback to call when the decoder has done its job
083 * @param decoded the object that was decoded
084 */
085 void callbackOccured( StatefulDecoder decoder, DecoderCallback cb, Object decoded );
086
087
088 /**
089 * Monitors changes to the callback.
090 *
091 * @param decoder the decoder whose callback was set
092 * @param oldcb the unset old callback, or null if none was set
093 * @param newcb the newly set callback, or null if callback is cleared
094 */
095 void callbackSet( StatefulDecoder decoder, DecoderCallback oldcb, DecoderCallback newcb );
096 }