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