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     * 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     * 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     * </p>
035     */
036    public interface ErrorHandler {
037    
038        /**
039         * Add a reference to a logger to which the failing appender might
040         * be attached to. The failing appender will be searched and
041         * replaced only in the loggers you add through this method.
042         *
043         * @param logger One of the loggers that will be searched for the failing
044         *               appender in view of replacement.
045         * @since 1.2
046         */
047        void setLogger(Logger logger);
048    
049    
050        /**
051         * Equivalent to the {@link #error(String, Exception, int,
052         * LoggingEvent)} with the the event parameter set to
053         * <code>null</code>.
054         *
055         * @param message   The message associated with the error.
056         * @param e         The Exception that was thrown when the error occurred.
057         * @param errorCode The error code associated with the error.
058         */
059        void error(String message, Exception e, int errorCode);
060    
061        /**
062         * This method is normally used to just print the error message
063         * passed as a parameter.
064         *
065         * @param message   The message associated with the error.
066         */
067        void error(String message);
068    
069        /**
070         * This method is invoked to handle the error.
071         *
072         * @param message   The message associated with the error.
073         * @param e         The Exception that was thrown when the error occurred.
074         * @param errorCode The error code associated with the error.
075         * @param event     The logging event that the failing appender is asked
076         *                  to log.
077         * @since 1.2
078         */
079        void error(String message, Exception e, int errorCode, LoggingEvent event);
080    
081        /**
082         * Set the appender for which errors are handled. This method is
083         * usually called when the error handler is configured.
084         *
085         * @param appender The appender
086         * @since 1.2
087         */
088        void setAppender(Appender appender);
089    
090        /**
091         * Set the appender to fallback upon in case of failure.
092         *
093         * @param appender The backup appender
094         * @since 1.2
095         */
096        void setBackupAppender(Appender appender);
097    }
098