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 | #ifndef _LOG4CXX_SPI_FILTER_H
|
---|
19 | #define _LOG4CXX_SPI_FILTER_H
|
---|
20 |
|
---|
21 | #include <log4cxx/helpers/objectptr.h>
|
---|
22 | #include <log4cxx/helpers/objectimpl.h>
|
---|
23 | #include <log4cxx/spi/optionhandler.h>
|
---|
24 | #include <log4cxx/spi/loggingevent.h>
|
---|
25 |
|
---|
26 | namespace log4cxx
|
---|
27 | {
|
---|
28 | namespace spi
|
---|
29 | {
|
---|
30 | class Filter;
|
---|
31 | LOG4CXX_PTR_DEF(Filter);
|
---|
32 |
|
---|
33 |
|
---|
34 | /**
|
---|
35 | Users should extend this class to implement customized logging
|
---|
36 | event filtering. Note that Logger and
|
---|
37 | AppenderSkeleton, the parent class of all standard
|
---|
38 | appenders, have built-in filtering rules. It is suggested that you
|
---|
39 | first use and understand the built-in rules before rushing to write
|
---|
40 | your own custom filters.
|
---|
41 |
|
---|
42 | <p>This abstract class assumes and also imposes that filters be
|
---|
43 | organized in a linear chain. The {@link #decide
|
---|
44 | decide(LoggingEvent)} method of each filter is called sequentially,
|
---|
45 | in the order of their addition to the chain.
|
---|
46 |
|
---|
47 | <p>The {@link #decide decide(LoggingEvent)} method must return one
|
---|
48 | of the integer constants #DENY, #NEUTRAL or
|
---|
49 | #ACCEPT.
|
---|
50 |
|
---|
51 | <p>If the value #DENY is returned, then the log event is
|
---|
52 | dropped immediately without consulting with the remaining
|
---|
53 | filters.
|
---|
54 |
|
---|
55 | <p>If the value #NEUTRAL is returned, then the next filter
|
---|
56 | in the chain is consulted. If there are no more filters in the
|
---|
57 | chain, then the log event is logged. Thus, in the presence of no
|
---|
58 | filters, the default behaviour is to log all logging events.
|
---|
59 |
|
---|
60 | <p>If the value #ACCEPT is returned, then the log
|
---|
61 | event is logged without consulting the remaining filters.
|
---|
62 |
|
---|
63 | <p>The philosophy of log4cxx filters is largely inspired from the
|
---|
64 | Linux ipchains.
|
---|
65 |
|
---|
66 | <p>Note that filtering is only supported by the {@link
|
---|
67 | xml::DOMConfigurator DOMConfigurator}.
|
---|
68 | */
|
---|
69 | class LOG4CXX_EXPORT Filter : public virtual OptionHandler,
|
---|
70 | public virtual helpers::ObjectImpl
|
---|
71 | {
|
---|
72 | /**
|
---|
73 | Points to the next filter in the filter chain.
|
---|
74 | */
|
---|
75 | FilterPtr next;
|
---|
76 | public:
|
---|
77 | Filter();
|
---|
78 |
|
---|
79 | void addRef() const;
|
---|
80 | void releaseRef() const;
|
---|
81 |
|
---|
82 | DECLARE_ABSTRACT_LOG4CXX_OBJECT(Filter)
|
---|
83 | BEGIN_LOG4CXX_CAST_MAP()
|
---|
84 | LOG4CXX_CAST_ENTRY(Filter)
|
---|
85 | LOG4CXX_CAST_ENTRY(spi::OptionHandler)
|
---|
86 | END_LOG4CXX_CAST_MAP()
|
---|
87 |
|
---|
88 | log4cxx::spi::FilterPtr getNext() const;
|
---|
89 | void setNext(const log4cxx::spi::FilterPtr& newNext);
|
---|
90 |
|
---|
91 | enum FilterDecision
|
---|
92 | {
|
---|
93 | /**
|
---|
94 | The log event must be dropped immediately without consulting
|
---|
95 | with the remaining filters, if any, in the chain. */
|
---|
96 | DENY = -1,
|
---|
97 | /**
|
---|
98 | This filter is neutral with respect to the log event. The
|
---|
99 | remaining filters, if any, should be consulted for a final decision.
|
---|
100 | */
|
---|
101 | NEUTRAL = 0,
|
---|
102 | /**
|
---|
103 | The log event must be logged immediately without consulting with
|
---|
104 | the remaining filters, if any, in the chain.
|
---|
105 | */
|
---|
106 | ACCEPT = 1
|
---|
107 |
|
---|
108 | };
|
---|
109 |
|
---|
110 |
|
---|
111 | /**
|
---|
112 | Usually filters options become active when set. We provide a
|
---|
113 |
|
---|
114 | default do-nothing implementation for convenience.
|
---|
115 | */
|
---|
116 | void activateOptions(log4cxx::helpers::Pool& p);
|
---|
117 | void setOption(const LogString& option, const LogString& value);
|
---|
118 |
|
---|
119 | /**
|
---|
120 | <p>If the decision is <code>DENY</code>, then the event will be
|
---|
121 | dropped. If the decision is <code>NEUTRAL</code>, then the next
|
---|
122 | filter, if any, will be invoked. If the decision is ACCEPT then
|
---|
123 | the event will be logged without consulting with other filters in
|
---|
124 | the chain.
|
---|
125 |
|
---|
126 | @param event The LoggingEvent to decide upon.
|
---|
127 | @return The decision of the filter. */
|
---|
128 | virtual FilterDecision decide(const LoggingEventPtr& event) const = 0;
|
---|
129 | };
|
---|
130 | }
|
---|
131 | }
|
---|
132 |
|
---|
133 | #endif //_LOG4CXX_SPI_FILTER_H
|
---|