View Javadoc

    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   * 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   * 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   * </p>
    35   */
    36  public interface ErrorHandler {
    37
    38      /**
    39       * Add a reference to a logger to which the failing appender might
    40       * be attached to. The failing appender will be searched and
    41       * replaced only in the loggers you add through this method.
    42       *
    43       * @param logger One of the loggers that will be searched for the failing
    44       *               appender in view of replacement.
    45       * @since 1.2
    46       */
    47      void setLogger(Logger logger);
    48
    49
    50      /**
    51       * Equivalent to the {@link #error(String, Exception, int,
    52       * LoggingEvent)} with the the event parameter set to
    53       * <code>null</code>.
    54       *
    55       * @param message   The message associated with the error.
    56       * @param e         The Exception that was thrown when the error occurred.
    57       * @param errorCode The error code associated with the error.
    58       */
    59      void error(String message, Exception e, int errorCode);
    60
    61      /**
    62       * This method is normally used to just print the error message
    63       * passed as a parameter.
    64       *
    65       * @param message   The message associated with the error.
    66       */
    67      void error(String message);
    68
    69      /**
    70       * This method is invoked to handle the error.
    71       *
    72       * @param message   The message associated with the error.
    73       * @param e         The Exception that was thrown when the error occurred.
    74       * @param errorCode The error code associated with the error.
    75       * @param event     The logging event that the failing appender is asked
    76       *                  to log.
    77       * @since 1.2
    78       */
    79      void error(String message, Exception e, int errorCode, LoggingEvent event);
    80
    81      /**
    82       * Set the appender for which errors are handled. This method is
    83       * usually called when the error handler is configured.
    84       *
    85       * @param appender The appender
    86       * @since 1.2
    87       */
    88      void setAppender(Appender appender);
    89
    90      /**
    91       * Set the appender to fallback upon in case of failure.
    92       *
    93       * @param appender The backup appender
    94       * @since 1.2
    95       */
    96      void setBackupAppender(Appender appender);
    97  }
    98