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 */
017package org.apache.log4j.spi;
018
019import org.apache.log4j.Appender;
020import 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 */
036public 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 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