    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