/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.log4j.spi;

import org.apache.log4j.Appender;
import org.apache.log4j.Logger;

/**
 * Appenders may delegate their error handling to <code>ErrorHandlers</code>.
 * 
 * <p>
 * Error handling is a particularly tedious to get right because by definition
 * errors are hard to predict and to reproduce.
 * 
 * 
 * <p>
 * Please take the time to contact the author in case you discover that errors
 * are not properly handled. You are most welcome to suggest new error handling
 * policies or criticize existing policies.
 * 
 * 
 * @author Ceki G&uuml;lc&uuml;
 * 
 */
public interface ErrorHandler extends OptionHandler {

    /**
     * Add a reference to a logger to which the failing appender might be attached
     * to. The failing appender will be searched and replaced only in the loggers
     * you add through this method.
     * 
     * @param logger One of the loggers that will be searched for the failing
     *               appender in view of replacement.
     * 
     * @since 1.2
     */
    void setLogger(Logger logger);

    /**
     * Equivalent to the {@link #error(String, Exception, int, LoggingEvent event)}
     * with the the event parameteter set to <code>null</code>.
     * 
     */
    void error(String message, Exception e, int errorCode);

    /**
     * This method is normally used to just print the error message passed as a
     * parameter.
     */
    void error(String message);

    /**
     * This method is invoked to handle the error.
     * 
     * @param message   The message assoicated with the error.
     * @param e         The Exption that was thrown when the error occured.
     * @param errorCode The error code associated with the error.
     * @param event     The logging event that the failing appender is asked to log.
     * 
     * @since 1.2
     */
    void error(String message, Exception e, int errorCode, LoggingEvent event);

    /**
     * Set the appender for which errors are handled. This method is usually called
     * when the error handler is configured.
     * 
     * @since 1.2
     */
    void setAppender(Appender appender);

    /**
     * Set the appender to falkback upon in case of failure.
     * 
     * @since 1.2
     */
    void setBackupAppender(Appender appender);
}
