001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements. See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache license, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License. You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the license for the specific language governing permissions and
015     * limitations under the license.
016     */
017    package org.apache.log4j.spi;
018    
019    import org.apache.log4j.Appender;
020    import org.apache.log4j.Logger;
021    
022    
023    /**
024     * Appenders may delegate their error handling to
025     * <code>ErrorHandlers</code>.
026     * <p/>
027     * <p>Error handling is a particularly tedious to get right because by
028     * definition errors are hard to predict and to reproduce.
029     * <p/>
030     * <p/>
031     * <p>Please take the time to contact the author in case you discover
032     * that errors are not properly handled. You are most welcome to
033     * suggest new error handling policies or criticize existing policies.
034     *
035     * @author Ceki G&uuml;lc&uuml;
036     */
037    public interface ErrorHandler {
038    
039        /**
040         * Add a reference to a logger to which the failing appender might
041         * be attached to. The failing appender will be searched and
042         * replaced only in the loggers you add through this method.
043         *
044         * @param logger One of the loggers that will be searched for the failing
045         *               appender in view of replacement.
046         * @since 1.2
047         */
048        void setLogger(Logger logger);
049    
050    
051        /**
052         * Equivalent to the {@link #error(String, Exception, int,
053         * LoggingEvent event)} with the the event parameteter set to
054         * <code>null</code>.
055         */
056        void error(String message, Exception e, int errorCode);
057    
058        /**
059         * This method is normally used to just print the error message
060         * passed as a parameter.
061         */
062        void error(String message);
063    
064        /**
065         * This method is invoked to handle the error.
066         *
067         * @param message   The message assoicated with the error.
068         * @param e         The Exption that was thrown when the error occured.
069         * @param errorCode The error code associated with the error.
070         * @param event     The logging event that the failing appender is asked
071         *                  to log.
072         * @since 1.2
073         */
074        void error(String message, Exception e, int errorCode, LoggingEvent event);
075    
076        /**
077         * Set the appender for which errors are handled. This method is
078         * usually called when the error handler is configured.
079         *
080         * @since 1.2
081         */
082        void setAppender(Appender appender);
083    
084        /**
085         * Set the appender to falkback upon in case of failure.
086         *
087         * @since 1.2
088         */
089        void setBackupAppender(Appender appender);
090    }
091