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
    18  package org.apache.log4j.plugins;
    19
    20  import org.apache.log4j.Level;
    21  import org.apache.log4j.Logger;
    22  import org.apache.log4j.spi.LoggingEvent;
    23  import org.apache.log4j.spi.Thresholdable;
    24
    25
    26  /**
    27   * Defines the base class for Receiver plugins.
    28   * <p></p>
    29   * <p>Just as Appenders send logging events outside of the log4j
    30   * environment (to files, to smtp, to sockets, etc), Receivers bring
    31   * logging events inside the log4j environment.
    32   * <p></p>
    33   * <p>Receivers are meant to support the receiving of
    34   * remote logging events from another process. For example,
    35   * SocketAppender "appends" a logging event to a socket, configured
    36   * for a specific host and port number.  On the receiving side of
    37   * the socket can be a SocketReceiver object.  The SocketReceiver
    38   * object receives the logging event, and then "posts" it to the
    39   * log4j environment (LoggerRepository) on the receiving machine, to
    40   * be handled by the configured appenders, etc.  The various
    41   * settings in this environment (Logger levels, Appender filters &amp;
    42   * thresholds) are applied to the received logging event.
    43   * <p></p>
    44   * <p>Receivers can also be used to "import" log messages from other
    45   * logging packages into the log4j environment.
    46   * <p></p>
    47   * <p>Receivers can be configured to post events to a given
    48   * LoggerRepository.
    49   * <p></p>
    50   * <p>Subclasses of Receiver must implement the isActive(),
    51   * activateOptions(), and shutdown() methods. The doPost() method
    52   * is provided to standardize the "import" of remote events into
    53   * the repository.
    54   *
    55   * @author Mark Womack
    56   * @author Ceki G&uuml;lc&uuml;
    57   * @author Paul Smith (psmith@apache.org)
    58   */
    59  public abstract class Receiver extends PluginSkeleton implements Thresholdable {
    60      /**
    61       * Threshold level.
    62       */
    63      protected Level thresholdLevel;
    64
    65      /**
    66       * Create new instance.
    67       */
    68      protected Receiver() {
    69          super();
    70      }
    71
    72      /**
    73       * Sets the receiver theshold to the given level.
    74       *
    75       * @param level The threshold level events must equal or be greater
    76       *              than before further processing can be done.
    77       */
    78      public void setThreshold(final Level level) {
    79          Level oldValue = this.thresholdLevel;
    80          thresholdLevel = level;
    81          firePropertyChange("threshold", oldValue, this.thresholdLevel);
    82      }
    83
    84      /**
    85       * Gets the current threshold setting of the receiver.
    86       *
    87       * @return Level The current threshold level of the receiver.
    88       */
    89      public Level getThreshold() {
    90          return thresholdLevel;
    91      }
    92
    93      /**
    94       * Returns true if the given level is equals or greater than the current
    95       * threshold value of the receiver.
    96       *
    97       * @param level The level to test against the receiver threshold.
    98       * @return boolean True if level is equal or greater than the
    99       *         receiver threshold.
    100      */
    101     public boolean isAsSevereAsThreshold(final Level level) {
    102         return ((thresholdLevel == null)
    103                 || level.isGreaterOrEqual(thresholdLevel));
    104     }
    105
    106     /**
    107      * Posts the logging event to a logger in the configured logger
    108      * repository.
    109      *
    110      * @param event the log event to post to the local log4j environment.
    111      */
    112     public void doPost(final LoggingEvent event) {
    113         // if event does not meet threshold, exit now
    114         if (!isAsSevereAsThreshold(event.getLevel())) {
    115             return;
    116         }
    117
    118         // get the "local" logger for this event from the
    119         // configured repository.
    120         Logger localLogger =
    121                 getLoggerRepository().getLogger(event.getLoggerName());
    122
    123         // if the logger level is greater or equal to the level
    124         // of the event, use the logger to append the event.
    125         if (event.getLevel()
    126                 .isGreaterOrEqual(localLogger.getEffectiveLevel())) {
    127             // call the loggers appenders to process the event
    128             localLogger.callAppenders(event);
    129         }
    130   }
    131 }