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 }