cvs commit: jakarta-log4j/src/java/org/apache/log4j/filters SetLocationInfoFilter.java MessageMatchFilter.java LevelRangeMatchFilter.java

mwomack     2002/06/15 21:47:46

  Added:       src/java/org/apache/log4j/filters SetLocationInfoFilter.java
                        MessageMatchFilter.java LevelRangeMatchFilter.java
  Log:
  Added LevelRangeFilter.java, copied functionality from varia version.
  Added MessageMatchFilter.java to match string values in event messages.
  Added SetLocationInfoFilter to optimize setting of location info for appenders like SocketAppender.  Included javadoc explanation as to when this filter should be used.
  
  Revision  Changes    Path
  1.1                  jakarta-log4j/src/java/org/apache/log4j/filters/SetLocationInfoFilter.java
  
  Index: SetLocationInfoFilter.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software
   * License version 1.1, a copy of which has been included with this
   * distribution in the LICENSE.txt file.  */
  
  package org.apache.log4j.filters;
  
  import org.apache.log4j.spi.Filter;
  import org.apache.log4j.spi.LoggingEvent;
  
  /**
    SetLocationInfoFilter is pass through filter that simply calls
    {@link LoggingEvent#getLocationInformation} method of every 
    LoggingEvent that is sent to it. After calling the method, it 
    returns {@link Filter#NEUTRAL} to send the event to the next 
    filter.
    
    <p><bold>Use of this filter is probably not typical.</bold>
    Its primary purpose is to increase throughput performance for 
    appenders like SocketAppender and SocketHubAppender that send
    logging events to remote clients. These appenders have the option 
    to set the location info for every event appended to them so that
    the client can see where the event was logged in the code. 
    However, resolving the location info for every event can be costly 
    performance-wise, and will reduce the number of events per second 
    that can be appended. This can affect performance in the 
    application that is logging the event. Chances are that one does 
    not want the location info for every event, but rather for a smaller
    set of events that are of interest.
    
    <p>SetLocationInfoFilter can be placed at the end of a filter
    chain configured for an appender. After the event has been 
    filtered through the chain, it will pass through the 
    SetLocationInfoFilter, thus setting the location info for just 
    that event (this assumes that the location info setting of the 
    appender has been set to false).  Using subclasses of the 
    MatchFilterBase class, one can configure the filter chain to 
    accept all events sent to the appender, while only setting the 
    location info for a select set of events. Please see the examples
    for information on how to do this.
    
    <p>Please review the available filters in the 
    org.apache.log4j.filters package. Most of these subclass the
    MatchFilterBase class and are easily configurable for use in
    log4j filter chains. 
    
    <p>(Note that any log4j filter can be used in an appender filter 
    chain, but it needs to support the return of the
    {@link Filter#NEUTRAL} value from its decide method.
    MatchFilterBase subclasses simply expose this functionality 
    directly as part of their configuration.)
    
    @author Mark Womack
    
    @since 1.3
  */
  public class SetLocationInfoFilter extends Filter {
    
    /**
      Sets the LocationInfo for the event and returns 
      {@link Filter#NEUTRAL} to pass the event to the next filter. */
    public int decide(LoggingEvent event) {
      event.getLocationInformation();
      return Filter.NEUTRAL;
    }
  }
  
  
  1.1                  jakarta-log4j/src/java/org/apache/log4j/filters/MessageMatchFilter.java
  
  Index: MessageMatchFilter.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software
   * License version 1.1, a copy of which has been included with this
   * distribution in the LICENSE.txt file.  */
  
  package org.apache.log4j.filters;
  
  import org.apache.log4j.Level;
  import org.apache.log4j.spi.LoggingEvent;
  import org.apache.log4j.helpers.OptionConverter;
  
  /**
    MessageMatchFilter is a very simple filter that matches a 
    configured value against the message value of a logging event.
    
    <p>The filter admits two options <b>MessageToMatch</b> and
    <b>ExactMatch</b>.
    
    <p>As the name indicates, the value of <b>MessageToMatch</b> property
    determines the string value to match. If <b>ExactMatch</b> is set
    to true, a match will occur only when <b>MessageToMatch</b> exactly
    matches the message value of the logging event.  Otherwise, if the
    <b>ExactMatch</b> property is set to <code>false</code>, a match
    will occur when <b>MessageToMatch</b> is contained anywhere within the
    message value. The <b>ExactMatch</b> property is set to
    <code>false</code> by default.
    
    <p>Note that by default <b>MessageToMatch</b> is set to
    <code>null</code> and will only match a null message.
  
    <p>For more information about how the logging event will be
    passed to the appender for reporting, please see 
    the {@link MatchFilterBase} class.
  
    @author Mark Womack;
  
    @since 1.3
  */
  public class MessageMatchFilter extends MatchFilterBase {
  
    /**
      The message match against. */
    String messageToMatch;
  
    /**
      Do we look for an exact match or just a "contains" match? */
    boolean exactMatch = false;
  
    /**
      Sets the string to match against the logging event message. */
    public void setMessageToMatch(String _message) {
      messageToMatch = _message;
    }
    
    public String getMessageToMatch() {
      return messageToMatch;
    }
  
    /**
      Set to true if configured value must exactly match the message
      value of the LoggingEvent. Set to false if the configured
      value must only be contained in the message value of the
      LoggingEvent. Default is false. */
    public void setExactMatch(boolean exact) {
      exactMatch = exact;
    }
    
    public boolean getExactMatch() {
      return exactMatch;
    }
    
    /**
      If <b>ExactMatch</b> is set to true, returns true only when
      <b>MessageToMatch</b> exactly matches the message value of the 
      logging event. If the <b>ExactMatch</b> property
      is set to <code>false</code>, returns true when 
      <b>MessageToMatch</b> is contained anywhere within the message
      value. Otherwise, false is returned. */
    protected boolean match(LoggingEvent event) {
      String msg = event.getRenderedMessage();
      if (msg == null) {
        return (messageToMatch == null);
      } else {
        if (messageToMatch != null) {
          if (exactMatch) {
            return messageToMatch.equals(msg);
          } else {
            return (msg.indexOf(messageToMatch) != -1);
          }
        }
      }
      
      return false;
    }
  }
  
  
  1.1                  jakarta-log4j/src/java/org/apache/log4j/filters/LevelRangeMatchFilter.java
  
  Index: LevelRangeMatchFilter.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software
   * License version 1.1, a copy of which has been included with this
   * distribution in the LICENSE.txt file.  */
  
  package org.apache.log4j.filters;
  
  import org.apache.log4j.Level;
  import org.apache.log4j.spi.LoggingEvent;
  
  /**
    LevelMatchFilter is a very simple filter based on level matching, 
    which can be used to reject logging events with levels outside a 
    certain range. If they levels are within the range, then the 
    match() method returns true, else it returns false.
      
    <p>If <code>LevelMin</code> is not defined, then there is no
    minimum acceptable level (ie a level is never rejected for
    being too "low"/unimportant).  If <code>LevelMax</code> is not
    defined, then there is no maximum acceptable level (ie a
    level is never rejected for being too "high"/important).
    
    <p>Refer to the {@link
    org.apache.log4j.AppenderSkeleton#setThreshold setThreshold} method
    available to <code>all</code> appenders extending {@link
    org.apache.log4j.AppenderSkeleton} for a more convenient way to
    filter out events by level.
  
    <p>For more information about how the logging event will be
    passed to the appender for reporting, please see 
    the {@link MatchFilterBase} class.
    
    @author Simon Kitching
    @author based on code by Ceki G&uuml;lc&uuml; 
    @author Mark Womack;
  
    @since 1.3
  */
  public class LevelRangeMatchFilter extends MatchFilterBase {
  
    /**
      Minimum level to match against. */
    Level levelMin;
    
    /**
      Maximum level to match against. */
    Level levelMax;
  
    /**
      Set the <code>LevelMax</code> option. */
    public void setLevelMax(Level levelMax) {
      this.levelMax = levelMax;
    }
  
    /**
      Get the value of the <code>LevelMax</code> option. */
    public Level getLevelMax() {
      return levelMax;
    }
  
    /**
      Set the <code>LevelMin</code> option. */
    public void setLevelMin(Level levelMin) {
      this.levelMin = levelMin;
    }
  
    /**
      Get the value of the <code>LevelMin</code> option. */
    public Level getLevelMin() {
      return levelMin;
    }
    
    /**
      Returns true if the the level of the logging event is in
      the configured range of <code>LevelMin</code> and
      <code>LevelMax</code>. */
    protected boolean match(LoggingEvent event) {
      if(this.levelMin != null) {
        if (event.level.isGreaterOrEqual(levelMin) == false) {
          // level of event is less than minimum
          return false;
        }
      }
  
      if(this.levelMax != null) {
        if (event.level.toInt() > levelMax.toInt()) {
          // level of event is greater than maximum
          // Alas, there is no Level.isGreater method. and using
          // a combo of isGreaterOrEqual && !Equal seems worse than
          // checking the int values of the level objects..
          return false;
        }
      }
  
      // return true match
      return true;
    }
  }