1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache license, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the license for the specific language governing permissions and 15 * limitations under the license. 16 */ 17 package org.apache.log4j.spi; 18 19 import org.apache.log4j.Appender; 20 import org.apache.log4j.Logger; 21 22 23 /** 24 * Appenders may delegate their error handling to 25 * <code>ErrorHandlers</code>. 26 * <p/> 27 * <p>Error handling is a particularly tedious to get right because by 28 * definition errors are hard to predict and to reproduce. 29 * <p/> 30 * <p/> 31 * <p>Please take the time to contact the author in case you discover 32 * that errors are not properly handled. You are most welcome to 33 * suggest new error handling policies or criticize existing policies. 34 */ 35 public interface ErrorHandler { 36 37 /** 38 * Add a reference to a logger to which the failing appender might 39 * be attached to. The failing appender will be searched and 40 * replaced only in the loggers you add through this method. 41 * 42 * @param logger One of the loggers that will be searched for the failing 43 * appender in view of replacement. 44 * @since 1.2 45 */ 46 void setLogger(Logger logger); 47 48 49 /** 50 * Equivalent to the {@link #error(String, Exception, int, 51 * LoggingEvent)} with the the event parameter set to 52 * <code>null</code>. 53 * 54 * @param message The message associated with the error. 55 * @param e The Exception that was thrown when the error occurred. 56 * @param errorCode The error code associated with the error. 57 */ 58 void error(String message, Exception e, int errorCode); 59 60 /** 61 * This method is normally used to just print the error message 62 * passed as a parameter. 63 * 64 * @param message The message associated with the error. 65 */ 66 void error(String message); 67 68 /** 69 * This method is invoked to handle the error. 70 * 71 * @param message The message associated with the error. 72 * @param e The Exception that was thrown when the error occurred. 73 * @param errorCode The error code associated with the error. 74 * @param event The logging event that the failing appender is asked 75 * to log. 76 * @since 1.2 77 */ 78 void error(String message, Exception e, int errorCode, LoggingEvent event); 79 80 /** 81 * Set the appender for which errors are handled. This method is 82 * usually called when the error handler is configured. 83 * 84 * @param appender The appender 85 * @since 1.2 86 */ 87 void setAppender(Appender appender); 88 89 /** 90 * Set the appender to fallback upon in case of failure. 91 * 92 * @param appender The backup appender 93 * @since 1.2 94 */ 95 void setBackupAppender(Appender appender); 96 } 97