mwomack 2002/06/11 00:04:54
Added: src/java/org/apache/log4j/filters package.html
NDCMatchFilter.java MDCMatchFilter.java
MatchFilterBase.java LevelMatchFilter.java
Log:
Added MatchFilterBase class to log4j.filters package and three subclasses to match
specific things: LevelMatchFilter, MDCMatchFilter, and NDCMatchFilter.
LevelMatchFilter and NDCMatchFilter are versions moved from the varia package, but
changed to subclass from MatchFilterBase.
Revision Changes Path
1.1 jakarta-log4j/src/java/org/apache/log4j/filters/package.html
Index: package.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html> <head>
<title></title>
</head>
<body>
<p>Contains various and useful filters.
<hr>
<address></address>
<!-- hhmts start -->
Last modified: Tue Mar 21 20:28:14 MET 2000
<!-- hhmts end -->
</body> </html>
1.1
jakarta-log4j/src/java/org/apache/log4j/filters/NDCMatchFilter.java
Index: NDCMatchFilter.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.NDC;
import org.apache.log4j.spi.Filter;
import org.apache.log4j.spi.LoggingEvent;
import org.apache.log4j.helpers.OptionConverter;
/**
The NDCMatchFilter matches a configured value against the
NDC value of a logging event.
<p>The filter admits two options <b>ValueToMatch</b> and
<b>ExactMatch</b>.
<p>As the name indicates, the value of <b>ValueToMatch</b> property
determines the string value to match. If <b>ExactMatch</b> is set
to true, a match will occur only when <b>ValueToMatch</b> exactly
matches the NDC value of the logging event. Otherwise, if the
<b>ExactMatch</b> property is set to <code>false</code>, a match
will occur when <b>ValueToMatch</b> is contained anywhere within the
NDC value. The <b>ExactMatch</b> property is set to
<code>false</code> by default.
<p>Note that by default <b>ValueToMatch</b> is set to
<code>null</code> and will only match an empty NDC stack.
<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 NDCMatchFilter extends MatchFilterBase {
/**
The value to match in the NDC value of the LoggingEvent. */
String valueToMatch;
/**
Do we look for an exact match or just a "contains" match? */
boolean exactMatch = false;
/**
Sets the value to match in the NDC value of the LoggingEvent. */
public
void setValueToMatch(String value) {
valueToMatch = value;
}
/**
Gets the value to match in the NDC value of the LoggingEvent. */
public
String getValueToMatch() {
return valueToMatch;
}
/**
Set to true if configured value must exactly match the NDC
value of the LoggingEvent. Set to false if the configured
value must only be contained in the NDC 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>ValueToMatch</b> exactly matches the NDC value of the
logging event. If the <b>ExactMatch</b> property
is set to <code>false</code>, returns true when
<b>ValueToMatch</b> is contained anywhere within the NDC
value. Otherwise, false is returned. */
protected
boolean match(LoggingEvent event) {
// get the ndc value for the event
String eventNDC = event.getNDC();
// check for a match
boolean matchOccured = false;
// if the NDC stack is empty
if (eventNDC == null) {
// return true if are we matching a null
if (valueToMatch == null) {
return true;
// else return false
} else {
return false;
}
} else {
// try to match the configured non-null value
if (valueToMatch != null) {
if (exactMatch) {
return eventNDC.equals(valueToMatch);
} else {
return (eventNDC.indexOf(valueToMatch) != -1);
}
// else the value to match is null, so return false
} else {
return false;
}
}
}
}
1.1
jakarta-log4j/src/java/org/apache/log4j/filters/MDCMatchFilter.java
Index: MDCMatchFilter.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.MDC;
import org.apache.log4j.spi.Filter;
import org.apache.log4j.spi.LoggingEvent;
/**
The MDCMatchFilter matches a configured value against the
value of a configured key in the MDC of a logging event.
<p>The filter admits three options <b>KeyToMatch</b>,
<b>ValueToMatch</b>, and <b>ExactMatch</b>.
<p>The value of <b>KeyToMatch</b> property determines which
key is used to match against in the MDC. The value of that
key is used to test against the <b>ValueToMatch</b property.
The <b>KeyToMatch</b> property must be set before this filter
can function properly.
<p>The value of <b>ValueToMatch</b> property determines the
string value to match against. If <b>ExactMatch</b> is set
to true, a match will occur only when <b>ValueToMatch</b> exactly
matches the MDC value of the logging event. Otherwise, if the
<b>ExactMatch</b> property is set to <code>false</code>, a match
will occur if <b>ValueToMatch</b> is contained anywhere within the
MDC value. The <b>ExactMatch</b> property is set to
<code>false</code> by default.
<p>Note that by default the value to match is set to
<code>null</code> and will only match if the key is not contained
or the value is null in the MDC.
<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 MDCMatchFilter extends MatchFilterBase {
/**
The key to match in the MDC of the LoggingEvent. */
String keyToMatch;
/**
The value to match in the MDC value of the LoggingEvent. */
String valueToMatch;
/**
Do we look for an exact match or just a "contains" match? */
boolean exactMatch = false;
/**
Sets the key to match in the MDC of the LoggingEvent. */
public
void setKeyToMatch(String key) {
keyToMatch = key;
}
/**
Gets the key to match in the MDC of the LoggingEvent. */
public
String getKeyToMatch() {
return keyToMatch;
}
/**
Sets the value to match in the NDC value of the LoggingEvent. */
public
void setValueToMatch(String value) {
valueToMatch = value;
}
/**
Gets the value to match in the NDC value of the LoggingEvent. */
public
String getValueToMatch() {
return valueToMatch;
}
/**
Set to true if configured value must exactly match the MDC
value of the LoggingEvent. Set to false if the configured
value must only be contained in the MDC value of the
LoggingEvent. Default is false. */
public
void setExactMatch(boolean exact) {
exactMatch = exact;
}
public
boolean getExactMatch() {
return exactMatch;
}
protected
boolean canMatch() {
return (keyToMatch != null);
}
/**
If <b>ExactMatch</b> is set to true, returns true only when
<b>ValueToMatch</b> exactly matches the MDC value of the
logging event. If the <b>ExactMatch</b> property
is set to <code>false</code>, returns true when
<b>ValueToMatch</b> is contained anywhere within the MDC
value. Otherwise, false is returned. */
protected
boolean match(LoggingEvent event) {
// get the mdc value for the key from the event
// use the toString() value of the value object
Object mdcObject = event.getMDC(keyToMatch);
String mdcValue;
if (mdcObject != null) {
mdcValue = mdcObject.toString();
} else {
mdcValue = null;
}
// check for a match
boolean matchOccured = false;
if (mdcValue == null) {
if (valueToMatch == null) {
return true;
} else {
return false;
}
} else {
if (valueToMatch != null) {
if (exactMatch) {
return mdcValue.equals(valueToMatch);
} else {
return (mdcValue.indexOf(valueToMatch) != -1);
}
} else {
return false;
}
}
}
}
1.1
jakarta-log4j/src/java/org/apache/log4j/filters/MatchFilterBase.java
Index: MatchFilterBase.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;
import org.apache.log4j.helpers.LogLog;
/**
This is the abstract base class for many useful filters implemented
in the log4j.filter package. It extends the base {@link Filter}
class to allow a different return value for a match or a nomatch.
What is specifically tested for matching is implemented in specific
subclasses.
<p>Properties matchReturnValue and noMatchReturnValue can be
set programmitcally or from a configuration file. They set
the value that will be returned when there is match or when there
is not a match, respectively. By default matchReturnValue is
set to Filter.ACCEPT and noMatchReturnValue is set to Filter.DENY.
<p>In addition to being able to set the match and nomatch return
values directly, one can instead use the chainPolicy property.
Log4j allows for filters to be chained together, each filter
deciding whether the logging event should be accepted, denied,
or passed on to the next filter. However, for the event to passed
to the next filter, one of the return values must be set to
Filter.NEUTRAL. One can use chainPolicy to accomplish this, passing
it one of the four valid policies: ACCEPT_ON_MATCH (match =
Filter.ACCEPT/nomatch = Filter.NEUTRAL), DENY_ON_MATCH (match =
Filter.DENY/nomatch = Filter.NEUTRAL), ACCEPT_ON_NOMATCH
(match = Filter.NEUTRAL/nomatch = Filter.ACCEPT), and
DENY_ON_NOMATCH (match = Filter.NEUTRAL/nomatch = Filter.DENY).
Which policy is used can be set programmatically or from a
configuration file. If more than one filter will be attached
to a single appender, all but the last one should probably be
configured via the chainPolicy property.
<p>Subclasses are required to implement the match() method. The
implementation should test for a match, returning true if there
is a match and false if there is nomatch. Subclasses can also
implement their own version of the canMatch() method, but should
only do so if they will be unable to perform the match code
due to misconfiguration. By default, canMatch() will always
return true.
<p>Developers are encouraged to extend this base class when
implementing their own filters. For examples of how
to use and extend this base class, please see the various
filters implemented in the log4j.filters package.
@author Mark Womack
@since 1.3
*/
public
abstract
class MatchFilterBase extends Filter {
public static final String ACCEPT_ON_MATCH = "AcceptOnMatch";
public static final String DENY_ON_MATCH = "DenyOnMatch";
public static final String ACCEPT_ON_NOMATCH = "AcceptOnNomatch";
public static final String DENY_ON_NOMATCH = "DenyOnNomatch";
/**
The value that will be returned upon a successful match. */
protected int matchReturnValue = ACCEPT;
/**
The value that will be returned upon an unsuccessful match */
protected int noMatchReturnValue = DENY;
/**
Set the value to return upon a successful match. Valid
string values are "ACCEPT", "DENY", and "NEUTRAL". */
public
void setMatchReturnValue(String filterReturnValue) {
if (filterReturnValue.equalsIgnoreCase("accept")) {
matchReturnValue = ACCEPT;
} else if (filterReturnValue.equalsIgnoreCase("deny")) {
matchReturnValue = DENY;
} else if (filterReturnValue.equalsIgnoreCase("neutral")) {
matchReturnValue = NEUTRAL;
} else {
LogLog.error("invalid matchReturnValue: " + filterReturnValue);
}
}
/**
Set the value to return upon a successful match. Valid
int values come from the Filter base class, ACCEPT,
DENY, and NEUTRAL. */
public
void setMatchReturnValue(int filterReturnValue) {
if (filterReturnValue < DENY || filterReturnValue > ACCEPT) {
LogLog.error("invalid matchReturnValue: " + filterReturnValue);
return;
}
matchReturnValue = filterReturnValue;
}
/**
Gets the value that will be returned upon a successful
match. */
public
int getMatchReturnValue() {
return matchReturnValue;
}
/**
Set the value to return upon a successful match. Valid
string values are "ACCEPT", "DENY", and "NEUTRAL". */
public
void setNoMatchReturnValue(String filterReturnValue) {
if (filterReturnValue.equalsIgnoreCase("accept")) {
noMatchReturnValue = ACCEPT;
} else if (filterReturnValue.equalsIgnoreCase("deny")) {
noMatchReturnValue = DENY;
} else if (filterReturnValue.equalsIgnoreCase("neutral")) {
noMatchReturnValue = NEUTRAL;
} else {
LogLog.error("invalid noMatchReturnValue: " + filterReturnValue);
}
}
/**
Set the value to return upon an unsuccessful match. Valid
int values come from the Filter base class, ACCEPT,
DENY, and NEUTRAL. */
public
void setNoMatchReturnValue(int filterReturnValue) {
if (filterReturnValue < DENY || filterReturnValue > ACCEPT) {
LogLog.error("invalid noMatchReturnValue: " + filterReturnValue);
return;
}
noMatchReturnValue = filterReturnValue;
}
/**
Gets the value that will be returned upon an unsuccessful
match. */
public
int getNoMatchReturnValue() {
return noMatchReturnValue;
}
/**
Sets the match and nomatch return values based on a "policy"
string. Valid values for the policy string are defined as
constants for this class: ACCEPT_ON_MATCH, DENY_ON_MATCH,
ACCEPT_ON_NOMATCH, DENY_ON_NOMATCH. */
public
void setChainPolicy(String policyStr) {
if (policyStr.equalsIgnoreCase(ACCEPT_ON_MATCH)) {
matchReturnValue = ACCEPT;
noMatchReturnValue = NEUTRAL;
} else if (policyStr.equalsIgnoreCase(DENY_ON_MATCH)) {
matchReturnValue = DENY;
noMatchReturnValue = NEUTRAL;
} else if (policyStr.equalsIgnoreCase(ACCEPT_ON_NOMATCH)) {
matchReturnValue = NEUTRAL;
noMatchReturnValue = ACCEPT;
} else if (policyStr.equalsIgnoreCase(DENY_ON_NOMATCH)) {
matchReturnValue = NEUTRAL;
noMatchReturnValue = DENY;
} else {
LogLog.error("invalid chainPolicy: " + policyStr);
}
}
/**
Implementation that calls the canMatch() and match() methods
of subclasses. If a match test can be performed (canMatch()
returned true), then either the configured matchReturnValue
or noMatchReturnValue will be returned. If no match test can
be performed (canMatch() returned false), then Filter.NEUTRAL
is returned. */
public
int decide(LoggingEvent event) {
if (canMatch()) {
if (match(event)) {
return matchReturnValue;
} else {
return noMatchReturnValue;
}
}
else
return NEUTRAL;
}
/**
Subclasses can override this method with their own version if
it is possible that no match test can/should be performed due
to a misconfiguration. This method should return true if a match
test can be performed, and false if it cannot be performed. The
default version always returns true. */
protected
boolean canMatch() {
return true;
}
/**
Subclasses must implement this method to perform the specific
match test that they require. This method should return true
if a match is made, and false if no match is made. */
abstract
protected
boolean match(LoggingEvent event);
}
1.1
jakarta-log4j/src/java/org/apache/log4j/filters/LevelMatchFilter.java
Index: LevelMatchFilter.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;
/**
LevelMatchFilter is a very simple filter that matches a
configured log level against the log level of a logging event.
If they levels are the same, then the match() method returns
true, else it returns false.
<p>If a LevelMatchFilter is not configured with a level to match,
then the canMatch() method will return false.
<p>For more information about how the logging event will be
passed to the appender for reporting, please see
the {@link MatchFilterBase} class.
@author Ceki Gülcü
@author Mark Womack;
@since 1.3
*/
public
class LevelMatchFilter extends MatchFilterBase {
/**
The level to match against. */
Level levelToMatch;
/**
Sets the level to match against. */
public
void setLevelToMatch(String level) {
levelToMatch = OptionConverter.toLevel(level, null);
}
/**
Gets the level that will be matched against. */
public
String getLevelToMatch() {
return levelToMatch == null ? null : levelToMatch.toString();
}
/**
Overrides the implementation from the base class to return
false if the levelToMatch has not been configured. */
protected
boolean canMatch() {
return (levelToMatch != null);
}
/**
Returns true if the levelToMatch matches the level of the
logging event. */
protected
boolean match(LoggingEvent event) {
return (levelToMatch.equals(event.level));
}
}
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
