Author: seb Date: Tue Dec 12 16:25:09 2006 New Revision: 1075 Added: logback/trunk/logback-examples/src/main/java/chapter6/SampleFilter.java logback/trunk/logback-examples/src/main/java/chapter6/SampleTurboFilter.java logback/trunk/logback-examples/src/main/java/chapter6/sampleFilterConfig.xml Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml Log: On going work in filters documentation Added: logback/trunk/logback-examples/src/main/java/chapter6/SampleFilter.java ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter6/SampleFilter.java Tue Dec 12 16:25:09 2006 @@ -0,0 +1,18 @@ +package chapter6; + +import ch.qos.logback.classic.spi.LoggingEvent; +import ch.qos.logback.core.filter.Filter; +import ch.qos.logback.core.spi.FilterReply; + +public class SampleFilter extends Filter { + + @Override + public FilterReply decide(Object eventObject) { + LoggingEvent event = (LoggingEvent)eventObject; + if (event.getMessage().contains("sample")) { + return FilterReply.ACCEPT; + } else { + return FilterReply.NEUTRAL; + } + } +} Added: logback/trunk/logback-examples/src/main/java/chapter6/SampleTurboFilter.java ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter6/SampleTurboFilter.java Tue Dec 12 16:25:09 2006 @@ -0,0 +1,22 @@ +package chapter6; + +import org.slf4j.Marker; +import org.slf4j.MarkerFactory; + +import ch.qos.logback.classic.Level; +import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.turbo.TurboFilter; +import ch.qos.logback.core.spi.FilterReply; + +public class SampleTurboFilter extends TurboFilter { + + @Override + public FilterReply decide(Marker marker, Logger logger, Level level, + String format, Object[] params, Throwable t) { + if ((MarkerFactory.getMarker("sample").equals(marker))) { + return FilterReply.ACCEPT; + } else { + return FilterReply.NEUTRAL; + } + } +} Added: logback/trunk/logback-examples/src/main/java/chapter6/sampleFilterConfig.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter6/sampleFilterConfig.xml Tue Dec 12 16:25:09 2006 @@ -0,0 +1,17 @@ +<configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <Filter class="chapter6.SampleFilter" /> + + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern> + %-4relative [%thread] %-5level %logger - %msg%n + </pattern> + </layout> + </appender> + + <root> + <appender-ref ref="STDOUT" /> + </root> +</configuration> \ No newline at end of file Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml Tue Dec 12 16:25:09 2006 @@ -1488,7 +1488,7 @@ <td><code>String</code></td> <td> The email address of the recipient. Multiple recipients can - be specified by separating each recipient with a comma. + be specified by using several <To> elements. </td> </tr> <tr> Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml Tue Dec 12 16:25:09 2006 @@ -239,6 +239,79 @@ logging event should be accepted, or rejected. </p> + <h2>Implementing your own Filter</h2> + + <p> + Creating your own filter is not difficult. If your filter doesn't need any evaluation + functionnalities, then all you have to do is extend the <code>Filter</code> abstract class. + The only method that you will have to implement is the <code>decide()</code> method, allowing + you to contentrate only on the behaviour of your filter. + </p> + + <p> + The next class is all it takes to implement one's own filter. All it does is accept + logging events who's message contains the String <em>sample</em>. The filter will give a + neutral response to any logging event who's message does not contain this String. + </p> + +<em>Example 6.2: Basic custom filter (<a href="../xref/chapter6/SampleFilter.html">logback-examples/src/main/java/chapter6/SampleFilter.java</a>)</em> +<div class="source"><pre>package chapter6; + +import ch.qos.logback.classic.spi.LoggingEvent; +import ch.qos.logback.core.filter.Filter; +import ch.qos.logback.core.spi.FilterReply; + +public class SampleFilter extends Filter { + + @Override + public FilterReply decide(Object eventObject) { + LoggingEvent event = (LoggingEvent)eventObject; + + if (event.getMessage().contains("sample")) { + return FilterReply.ACCEPT; + } else { + return FilterReply.NEUTRAL; + } + } +}</pre></div> + + <p> + What is shown above might be the simplest filter. Like any filter, it + can be attached to any appender using the <Filter> element, as + shown below: + </p> + +<em>Example 6.3: SampleFilter configuration (logback-examples/src/main/java/chapter6/SampleFilterConfig.xml)</em> +<div class="source"><pre><configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <b><Filter class="chapter6.SampleFilter" /></b> + + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern> + %-4relative [%thread] %-5level %logger - %msg%n + </pattern> + </layout> + </appender> + + <root> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> + + <p> + Thanks to Joran, logback's powerful configuration framework, adding + an option to such a filter is very easy. Just add the corresponding + getter and setter methods in the class, and you can specify the + option's value in a xml element, nested in the filter element. + </p> + + <p> + Creating a filter that makes use of <code>EventEvaluator</code> objects + works the same way, except that one must extend the <code>EvaluatorFilter</code> + class, instead of the <code>Filter</code> class. + </p> <a name="TurboFilter" /> <h3>TurboFilters</h3> @@ -284,7 +357,7 @@ <code>MarkerFilter</code>. </p> -<em>Example 6.2: <code>MDCFilter</code> and <code>MarkerFilter</code> +<em>Example 6.4: <code>MDCFilter</code> and <code>MarkerFilter</code> configuration (logback-examples/src/main/java/chapter6/turboFilters.xml)</em> <div class="source"><pre><configuration> @@ -359,6 +432,52 @@ whose <span class="option">OnMatch</span> option is set to <em>DENY</em>. Thus, the 6th request was not displayed. </p> + + + <h2>Implementing your own TurboFilter</h2> + + <p> + To create your own <code>TurboFilter</code> component, just extend the + <code>TurboFilter</code> abstract class. Like previously, when implementing + a custumized filter object, developing a custom <code>TurboFilter</code> only + ask that one implement the <code>decide()</code> method, as shown below: + </p> + +<em>Example 6.5: Basic custom <code>TurboFilter</code> (<a href="../xref/chapter6/SampleTurboFilter.html">logback-examples/src/main/java/chapter6/SampleFilter.java</a>)</em> +<div class="source"><pre>package chapter6; + +import org.slf4j.Marker; +import org.slf4j.MarkerFactory; + +import ch.qos.logback.classic.Level; +import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.turbo.TurboFilter; +import ch.qos.logback.core.spi.FilterReply; + +public class SampleTurboFilter extends TurboFilter { + + @Override + public FilterReply decide(Marker marker, Logger logger, Level level, + String format, Object[] params, Throwable t) { + if ((MarkerFactory.getMarker("sample").equals(marker))) { + return FilterReply.ACCEPT; + } else { + return FilterReply.NEUTRAL; + } + } +}</pre></div> + + <p> + The <code>TurboFilter</code> above accepts events that contain a specific marker. + If said marker is not found, then the filter passes the responsability to + the next filter in the chain. + </p> + + <p> + + </p> + + <h2>Logback Access</h2> @@ -386,7 +505,7 @@ Here is a sample configuration that will ensure that any 404 error will be displayed: </p> -<em>Example 6.3: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator.xml)</em> +<em>Example 6.6: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator.xml)</em> <div class="source"><pre><configuration> <appender name="STDOUT" @@ -414,7 +533,7 @@ would look like: </p> -<em>Example 6.4: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator2.xml)</em> +<em>Example 6.7: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator2.xml)</em> <div class="source"><pre><configuration> <appender name="STDOUT"