1 // Module: Log4CPLUS
2 // File: filter.h
3 // Created: 5/2003
4 // Author: Tad E. Smith
5 //
6 //
7 // Copyright (C) Tad E. Smith All rights reserved.
8 //
9 // This software is published under the terms of the Apache Software
10 // License version 1.1, a copy of which has been included with this
11 // distribution in the LICENSE.APL file.
12 //
13
14 /** @file
15 * This header defines Filter and all of it's subclasses. */
16
17 #ifndef LOG4CPLUS_SPI_FILTER_HEADER_
18 #define LOG4CPLUS_SPI_FILTER_HEADER_
19
20 #include <log4cplus/config.h>
21 #include <log4cplus/helpers/pointer.h>
22 #include <log4cplus/helpers/property.h>
23 #include <log4cplus/spi/loggingevent.h>
24
25
26 namespace log4cplus {
27 namespace spi {
28
29
30 enum FilterResult { DENY, /**< The log event must be dropped immediately
31 * without consulting with the remaining
32 * filters, if any, in the chain. */
33 NEUTRAL, /**< This filter is neutral with respect to
34 * the log event; the remaining filters, if
35 * if any, should be consulted for a final
36 * decision. */
37 ACCEPT /**< The log event must be logged immediately
38 * without consulting with the remaining
39 * filters, if any, in the chain. */
40 };
41
42 // Forward Declarations
43 class Filter;
44
45
46 /**
47 * This method is used to filter an InternalLoggingEvent.
48 *
49 * <p>Note: <code>filter</code> can be NULL.
50 */
51 LOG4CPLUS_EXPORT FilterResult checkFilter(const Filter* filter,
52 const InternalLoggingEvent& event);
53
54 typedef helpers::SharedObjectPtr<Filter> FilterPtr;
55
56
57 /**
58 * Users should extend this class to implement customized logging
59 * event filtering. Note that the {@link Logger} and {@link
60 * Appender} classes have built-in filtering rules. It is suggested
61 * that you first use and understand the built-in rules before rushing
62 * to write your own custom filters.
63 *
64 * <p>This abstract class assumes and also imposes that filters be
65 * organized in a linear chain. The {@link #decide
66 * decide(LoggingEvent)} method of each filter is called sequentially,
67 * in the order of their addition to the chain.
68 *
69 * <p>If the value {@link #DENY} is returned, then the log event is
70 * dropped immediately without consulting with the remaining
71 * filters.
72 *
73 * <p>If the value {@link #NEUTRAL} is returned, then the next filter
74 * in the chain is consulted. If there are no more filters in the
75 * chain, then the log event is logged. Thus, in the presence of no
76 * filters, the default behaviour is to log all logging events.
77 *
78 * <p>If the value {@link #ACCEPT} is returned, then the log
79 * event is logged without consulting the remaining filters.
80 *
81 * <p>The philosophy of log4cplus filters is largely inspired from the
82 * Linux ipchains.
83 */
84 class LOG4CPLUS_EXPORT Filter : public log4cplus::helpers::SharedObject {
85 public:
86 // ctor and dtor
87 Filter();
88 virtual ~Filter();
89
90 // Methods
91 /**
92 * Appends <code>filter</code> to the end of this filter chain.
93 */
94 void appendFilter(FilterPtr filter);
95
96 /**
97 * <p>If the decision is <code>DENY</code>, then the event will be
98 * dropped. If the decision is <code>NEUTRAL</code>, then the next
99 * filter, if any, will be invoked. If the decision is ACCEPT then
100 * the event will be logged without consulting with other filters in
101 * the chain.
102 *
103 * @param event The LoggingEvent to decide upon.
104 * @param decision The decision of the filter.
105 */
106 virtual FilterResult decide(const InternalLoggingEvent& event) const = 0;
107
108 // Data
109 /**
110 * Points to the next filter in the filter chain.
111 */
112 FilterPtr next;
113 };
114
115
116
117 /**
118 * This filter drops all logging events.
119 *
120 * <p>You can add this filter to the end of a filter chain to
121 * switch from the default "accept all unless instructed otherwise"
122 * filtering behaviour to a "deny all unless instructed otherwise"
123 * behaviour.
124 */
125 class LOG4CPLUS_EXPORT DenyAllFilter : public Filter {
126 public:
127 /**
128 * Always returns the {@link DENY} regardless of the
129 * {@link InternalLoggingEvent} parameter.
130 */
131 virtual FilterResult decide(const InternalLoggingEvent& event) const;
132 };
133
134
135 /**
136 * This is a very simple filter based on LogLevel matching.
137 *
138 * <p>The filter admits two options <b>LogLevelToMatch</b> and
139 * <b>AcceptOnMatch</b>. If there is an exact match between the value
140 * of the LogLevelToMatch option and the LogLevel of the {@link
141 * LoggingEvent}, then the {@link #decide} method returns
142 * {@link #ACCEPT} in case the <b>AcceptOnMatch</b> option value is set
143 * to <code>true</code>, if it is <code>false</code> then {@link #DENY}
144 * is returned. If there is no match, {@link #NEUTRAL} is returned.
145 */
146 class LOG4CPLUS_EXPORT LogLevelMatchFilter : public Filter {
147 public:
148 LogLevelMatchFilter();
149 LogLevelMatchFilter(const log4cplus::helpers::Properties& p);
150
151 /**
152 * Return the decision of this filter.
153 *
154 * Returns {@link #NEUTRAL} if the <b>LogLevelToMatch</b>
155 * option is not set or if there is no match. Otherwise, if
156 * there is a match, then the returned decision is {@link #ACCEPT}
157 * if the <b>AcceptOnMatch</b> property is set to <code>true</code>.
158 * The returned decision is {@link #DENY} if the <b>AcceptOnMatch</b>
159 * property is set to <code>false</code>.
160 */
161 virtual FilterResult decide(const InternalLoggingEvent& event) const;
162
163 private:
164 // Methods
165 void init();
166
167 // Data
168 /** Do we return ACCEPT when a match occurs. Default is <code>true</code>. */
169 bool acceptOnMatch;
170 LogLevel logLevelToMatch;
171 };
172
173
174
175 /**
176 * This is a very simple filter based on LogLevel matching, which can be
177 * used to reject messages with LogLevels outside a certain range.
178 *
179 * <p>The filter admits three options <b>LogLevelMin</b>, <b>LogLevelMax</b>
180 * and <b>AcceptOnMatch</b>.
181 *
182 * <p>If the LogLevel of the Logging event is not between Min and Max
183 * (inclusive), then {@link #DENY} is returned.
184 *
185 * <p> If the Logging event LogLevel is within the specified range, then if
186 * <b>AcceptOnMatch</b> is true, {@link #ACCEPT} is returned, and if
187 * <b>AcceptOnMatch</b> is false, {@link #NEUTRAL} is returned.
188 *
189 * <p>If <code>LogLevelMin</code> is not defined, then there is no
190 * minimum acceptable LogLevel (ie a LogLevel is never rejected for
191 * being too "low"/unimportant). If <code>LogLevelMax</code> is not
192 * defined, then there is no maximum acceptable LogLevel (ie a
193 * LogLevel is never rejected for beeing too "high"/important).
194 *
195 * <p>Refer to the {@link
196 * Appender#setThreshold setThreshold} method
197 * available to <code>all</code> appenders for a more convenient way to
198 * filter out events by LogLevel.
199 */
200 class LOG4CPLUS_EXPORT LogLevelRangeFilter : public Filter {
201 public:
202 // ctors
203 LogLevelRangeFilter();
204 LogLevelRangeFilter(const log4cplus::helpers::Properties& p);
205
206 /**
207 * Return the decision of this filter.
208 */
209 virtual FilterResult decide(const InternalLoggingEvent& event) const;
210
211 private:
212 // Methods
213 void init();
214
215 // Data
216 /** Do we return ACCEPT when a match occurs. Default is <code>true</code>. */
217 bool acceptOnMatch;
218 LogLevel logLevelMin;
219 LogLevel logLevelMax;
220 };
221
222
223
224 /**
225 * This is a very simple filter based on string matching.
226 *
227 * <p>The filter admits two options <b>StringToMatch</b> and
228 * <b>AcceptOnMatch</b>. If there is a match between the value of the
229 * StringToMatch option and the message of the Logging event,
230 * then the {@link #decide} method returns {@link #ACCEPT} if
231 * the <b>AcceptOnMatch</b> option value is true, if it is false then
232 * {@link #DENY} is returned. If there is no match, {@link #NEUTRAL}
233 * is returned.
234 */
235 class LOG4CPLUS_EXPORT StringMatchFilter : public Filter {
236 public:
237 // ctors
238 StringMatchFilter();
239 StringMatchFilter(const log4cplus::helpers::Properties& p);
240
241 /**
242 * Returns {@link #NEUTRAL} is there is no string match.
243 */
244 virtual FilterResult decide(const InternalLoggingEvent& event) const;
245
246 private:
247 // Methods
248 void init();
249
250 // Data
251 /** Do we return ACCEPT when a match occurs. Default is <code>true</code>. */
252 bool acceptOnMatch;
253 log4cplus::tstring stringToMatch;
254 };
255
256 } // end namespace spi
257 } // end namespace log4cplus
258
259 #endif /* LOG4CPLUS_SPI_FILTER_HEADER_ */
syntax highlighted by Code2HTML, v. 0.9.1