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
018package org.apache.log4j.spi;
019
020import org.apache.log4j.Appender;
021import org.apache.log4j.Logger;
022
023
024/**
025   Appenders may delegate their error handling to
026   <code>ErrorHandlers</code>.
027
028   <p>Error handling is a particularly tedious to get right because by
029   definition errors are hard to predict and to reproduce. 
030
031
032   <p>Please take the time to contact the author in case you discover
033   that errors are not properly handled. You are most welcome to
034   suggest new error handling policies or criticize existing policies.
035
036
037   @author Ceki G&uuml;lc&uuml;
038   
039*/
040public interface ErrorHandler extends OptionHandler {
041
042  /**
043     Add a reference to a logger to which the failing appender might
044     be attached to. The failing appender will be searched and
045     replaced only in the loggers you add through this method.
046
047     @param logger One of the loggers that will be searched for the failing
048     appender in view of replacement.
049     
050     @since 1.2 */
051  void setLogger(Logger logger);
052
053
054  /**
055     Equivalent to the {@link #error(String, Exception, int,
056     LoggingEvent event)} with the the event parameteter set to
057     <code>null</code>.
058     
059  */
060  void error(String message, Exception e, int errorCode);
061
062  /**
063     This method is normally used to just print the error message
064     passed as a parameter.       
065  */
066  void error(String message);
067
068  /**
069     This method is invoked to handle the error.
070
071     @param message The message assoicated with the error.
072     @param e The Exption that was thrown when the error occured.
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
077     @since 1.2 */
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     @since 1.2 */
085  void setAppender(Appender appender);
086
087  /**
088     Set the appender to falkback upon in case of failure.
089     
090     @since 1.2 */
091  void setBackupAppender(Appender appender);
092}