Author: seb Date: Mon Dec 4 11:55:59 2006 New Revision: 1060 Added: logback/trunk/logback-examples/src/main/java/chapter6/ logback/trunk/logback-examples/src/main/java/chapter6/basicEventEvaluator.xml logback/trunk/logback-site/src/site/resources/manual/images/chapter6/ logback/trunk/logback-site/src/site/resources/manual/images/chapter6/filterChain.gif (contents, props changed) logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml Log: First draft of chapter 6 Added: logback/trunk/logback-examples/src/main/java/chapter6/basicEventEvaluator.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter6/basicEventEvaluator.xml Mon Dec 4 11:55:59 2006 @@ -0,0 +1,23 @@ +<configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> + <evaluator name="myEval"> + <expression>message.contains("important")</expression> + </evaluator> + <OnMismatch>NEUTRAL</OnMismatch> + <OnMatch>ACCEPT</OnMatch> + </filter> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern> + %-4relative [%thread] %-5level %logger - %msg%n + </pattern> + </layout> + </appender> + + <root> + <level value="INFO" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration> \ No newline at end of file Added: logback/trunk/logback-site/src/site/resources/manual/images/chapter6/filterChain.gif ============================================================================== Binary file. No diff available. Added: logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml Mon Dec 4 11:55:59 2006 @@ -0,0 +1,168 @@ +<document> +<!-- + + Warning: do not use any auto-format function on this file. + Since "source" divs use pre as white-space, it affects the + look of the code parts in this document. + + --> + + <body> + <h2>Chapter 6: Filters</h2> + <div class="author"> + Authors: Ceki Gülcü, Sébastien Pennec + </div> + + <table> + <tr> + <td valign="top" align="top"> + <a rel="license" + href="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + <img alt="Creative Commons License" + style="border-width: 0" + src="http://creativecommons.org/images/public/somerights20.png" /> + </a> + </td> + <td> + <p>Copyright © 2000-2006, QOS.ch</p> + + <p> + <!--Creative Commons License--> + This work is licensed under a + <a rel="license" + href="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + Creative Commons + Attribution-NonCommercial-ShareAlike 2.5 + License + </a>. + <!--/Creative Commons License--> + </p> + </td> + </tr> + </table> + + <p> + As we have seen, logback has several built-in ways for filtering log requests, + including the context-wide filter, logger-level selection rule and appender filters. + These provide high performance filtering for the most commonly encountered + cases. These filters are largely inspired from Linux ipchains or + iptables as they are called in more recent Linux kernels. + Logback filters are based on ternary logic allowing them to be assembled or chained + together to compose an arbitrarily complex filtering policy. + </p> + + <p> + There are two main types of filters, namely <code>Filter</code> and + <code>TurboFilter</code>. + </p> + + <a name="Filter" /> + <p><code>Filter</code> subclasses all implement the + <a href="../xref/ch/qos/logback/core/filter/Filter.html"><code>Filter</code></a> + abscract class. + </p> + + <h2>Filter chains</h2> + <p> + This abstract class assumes that filters be organized in a linear chain. + Its member field next points to the next filter in the chain, or + <code>null</code> if there are no further filters in the chain. + Figure 6.1 depicts a sample filter chain consisting of three filters. + </p> + + <img src="images/chapter6/filterChain.gif" alt="A sample filter chain"/> + + <p> + Filters are based on ternary logic. The <code>decide(Object event)</code> + method of each filter is called in sequence. This method returns one of the + enumerations <code>FilterReply.DENY</code>, <code>FilterReply.NEUTRAL</code> or + <code>FilterReply.ACCEPT</code>. If the returned value is <code>FilterReply.DENY</code>, + then the log event is dropped immediately without consulting the + remaining filters. If the value returned is <code>FilterReply.NEUTRAL</code>, + then the next filter in the chain is consulted. If there are no further filters + to consult, then the logging event is processed normally. + If the returned value is <code>FilterReply.ACCEPT</code>, then the logging + event is processed immediately skipping the remaining filters. + </p> + + <p> + In logback, <code>Filter</code> objects can only be added to <code>Appender</code> + instances. By adding filters to an appender you can filter events by various + criteria, such as the contents of the log message, the contents of the NDC, + the time of day or any other part of the logging event. + </p> + + <p> + The criteria can be specified using an expression evaluator. The + <a href="../xref/ch/qos/logback/core/filter/EvaluatorFilter.html"> + <code>EvaluatorFilter</code></a> class uses an + <a href="../xref/ch/qos/logback/core/boolex/EventEvaluator.html"> + <code>EventEvaluator</code></a> + to decide wether to accept or deny the request. This allows unprecedented + flexibility in the way that you can affect the logging event's filtering. + </p> + + <h3>Event Evaluators</h3> + + <p> + Events evaluators allow the user to enter java expressions, using + components of a logging event, and to check each logging event + against the compiled expression. + </p> + + <p> + Let's see a sample configuration. + </p> + +<em>Example 6.1: Basic event evaluator usage</em> +<div class="source"><pre><configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <b><filter class="ch.qos.logback.core.filter.EvaluatorFilter"> + <evaluator name="myEval"> + <expression>message.contains("important")</expression> + </evaluator> + <OnMismatch>NEUTRAL</OnMismatch> + <OnMatch>ACCEPT</OnMatch> + </filter></b> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern> + %-4relative [%thread] %-5level %logger - %msg%n + </pattern> + </layout> + </appender> + + <root> + <level value="INFO" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> + + <p> + The bold part in the previous configuration adds an <code>EvaluatorFilter</code> + to a <code>ConsoleAppender</code>. An <code>EventEvaluator</code> is then given to + the filter. The <em>expression</em> element contains a recognizable java expression. + Notice that the <em>message</em> variable is not defined anywhere. Logback provides + access to the internal components of a logging event and lets the user build her + expression at will. + </p> + + <p> + The behaviour of the filter is also defined by its <span class="option">OnMatch</span> + and <span class="option">OnMismatch</span> options. The configuration specifies thanks + to these elements the replies that the <code>EvaluatorFilter</code> must give once its + expression has been evaluated. The example above returns a positive reply when the + message of the logging event contains the String <em>important</em>. If this String is + not found in the message, then the filter lets the next filter evaluate whether this + logging event should be accepted, or rejected. + </p> + + + + + + + + </body> +</document> \ No newline at end of file