public abstract class MatchFilterBase
extends org.apache.log4j.spi.Filter
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.
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.
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.
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.
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.
Modifier and Type | Field and Description |
---|---|
static String |
ACCEPT_ON_MATCH
Chain policy constant = AcceptOnMatch.
|
static String |
ACCEPT_ON_NOMATCH
Chain policy constant = AcceptOnNomatch.
|
static String |
DENY_ON_MATCH
Chain policy constant = DenyOnMatch.
|
static String |
DENY_ON_NOMATCH
Chain policy constant = DenyOnNomatch.
|
protected int |
matchReturnValue
The value that will be returned upon a successful match.
|
protected int |
noMatchReturnValue
The value that will be returned upon an unsuccessful match
|
static String |
UNKNOWN_POLICY
Chain policy constant = UnknownPolicy.
|
Constructor and Description |
---|
MatchFilterBase() |
Modifier and Type | Method and Description |
---|---|
protected boolean |
canMatch()
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.
|
int |
decide(org.apache.log4j.spi.LoggingEvent event)
Implementation that calls the canMatch() and match() methods
of subclasses.
|
String |
getChainPolicy()
Gets the chain policy string value that matches the current
settings of matchReturnValue and noMatchReturn value.
|
String |
getMatchReturnValue()
Gets the value that will be returned upon a successful
match.
|
String |
getNoMatchReturnValue()
Gets the value that will be returned upon an unsuccessful
match.
|
protected abstract boolean |
match(org.apache.log4j.spi.LoggingEvent event)
Subclasses must implement this method to perform the specific
match test that they require.
|
void |
setChainPolicy(String policyStr)
Sets the match and nomatch return values based on a "policy"
string.
|
void |
setMatchReturnValue(String filterReturnValue)
Set the value to return upon a successful match.
|
void |
setNoMatchReturnValue(String filterReturnValue)
Set the value to return upon a successful match.
|
public static final String ACCEPT_ON_MATCH
public static final String DENY_ON_MATCH
public static final String ACCEPT_ON_NOMATCH
public static final String DENY_ON_NOMATCH
public static final String UNKNOWN_POLICY
protected int matchReturnValue
protected int noMatchReturnValue
public void setMatchReturnValue(String filterReturnValue)
filterReturnValue
- The return value if there is a match.public String getMatchReturnValue()
public void setNoMatchReturnValue(String filterReturnValue)
filterReturnValue
- The return value if there is no match.public String getNoMatchReturnValue()
public void setChainPolicy(String policyStr)
policyStr
- The policy to use.public String getChainPolicy()
public int decide(org.apache.log4j.spi.LoggingEvent event)
decide
in class org.apache.log4j.spi.Filter
event
- The event to filter.protected boolean canMatch()
protected abstract boolean match(org.apache.log4j.spi.LoggingEvent event)
event
- The event to match against.Copyright © 2006–2019 OPS4J - Open Participation Software for Java. All rights reserved.