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