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     * Document me.
025     * 
026     * @author <a href="mailto:dev@directory.apache.org"> Apache Directory Project</a>
027     * @version $Rev: 664290 $, $Date: 2008-06-07 08:28:06 +0200 (Sat, 07 Jun 2008) $
028     */
029    public interface EncoderMonitor
030    {
031        /** Use this if you don't want to recreate this as just a NOOP monitor */
032        EncoderMonitor INSTANCE = new EncoderMonitorAdapter();
033    
034    
035        /**
036         * Receive notification of a recoverable error. This callback is used to
037         * denote a failure to handle a unit of data to be encoded or decoded. The
038         * entire [en|de]codable unit is lost but the [en|de]coding operation can
039         * still proceed.
040         * 
041         * @param encoder
042         *            the encoder that had the error
043         * @param exception
044         *            the error information encapsulated in an exception
045         */
046        void error( StatefulEncoder encoder, Exception exception );
047    
048    
049        /**
050         * Receive notification of a non-recoverable error. The application must
051         * assume that the stream data is unusable after the encoder has invoked
052         * this method, and should continue (if at all) only for the sake of
053         * collecting addition error messages: in fact, encoders are free to stop
054         * reporting any other events once this method has been invoked.
055         * 
056         * @param encoder
057         *            the encoder that had the failure
058         * @param exception
059         *            the warning information encapsulated in an exception
060         */
061        void fatalError( StatefulEncoder encoder, Exception exception );
062    
063    
064        /**
065         * Receive notification of a warning. The encoder must continue to provide
066         * normal callbacks after invoking this method: it should still be possible
067         * for the application to process the encoded data through to the end.
068         * 
069         * @param encoder
070         *            the encoder that had the error
071         * @param exception
072         *            the warning information encapsulated in an exception
073         */
074        void warning( StatefulEncoder encoder, Exception exception );
075    
076    
077        /**
078         * Monitors callbacks that deliver a fully decoded object.
079         * 
080         * @param encoder the stateful encoder driving the callback
081         * @param cb the callback to call when the encoder has done its job
082         * @param decoded the object that was decoded
083         */
084        void callbackOccured( StatefulEncoder encoder, EncoderCallback cb, Object decoded );
085    
086    
087        /**
088         * Monitors changes to the callback.
089         * 
090         * @param encoder
091         *            the encoder whose callback was set
092         * @param oldcb
093         *            the unset old callback, or null if none was set
094         * @param newcb
095         *            the newly set callback, or null if callback is cleared
096         */
097        void callbackSet( StatefulEncoder encoder, EncoderCallback oldcb, EncoderCallback newcb );
098    }