The branch, master has been updated via 93098a6ca9cfb47dc87cd10e035d5f678723b1f5 (commit) via 9700a02ae011baf8d9404f8417485105f0ec5a02 (commit) via 1d9a3a816478905ffb518fbd0603c7ec1e0f5e02 (commit) via 5a457959b54a496b8d4a01c73ba1443edab66c20 (commit) from 61bfd0d0ba8d095ce395ab763f8047307a58c418 (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=93098a6ca9cfb47dc87cd10e0... http://github.com/ceki/logback/commit/93098a6ca9cfb47dc87cd10e035d5f678723b1... commit 93098a6ca9cfb47dc87cd10e035d5f678723b1f5 Author: Ceki Gulcu <ceki@qos.ch> Date: Sun Nov 8 22:30:41 2009 +0100 - edits in filters.html diff --git a/logback-site/src/site/pages/manual/filters.html b/logback-site/src/site/pages/manual/filters.html index 6127521..3d0ebb9 100644 --- a/logback-site/src/site/pages/manual/filters.html +++ b/logback-site/src/site/pages/manual/filters.html @@ -37,67 +37,61 @@ <script src="../templates/creative.js" type="text/javascript"></script> - <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>In the preceding chapters, the <a + href="architecture.html#basic_selection">basic selection rule</a>, + which lies at the heart of logback-classic, has been presented. In + this chapter, additional filtering methods will be introduced. + </p> + + + <p>Logback filters are based on ternary logic allowing them to be + assembled or chained together to compose an arbitrarily complex + filtering policy. They are largely inspired by Linux's iptables. </p> <script src="../templates/setup.js" type="text/javascript"></script> - <p> - There are two main types of filters, namely <code>Filter</code> and - <code>TurboFilter</code>. + <h2>In logback-classic</h2> + + + <p>Logback-classic offers two types of filters, regular filters + and turbo filters. </p> - <h2>Logback Classic</h2> - - <a name="Filter"></a> + <h3><a name="filter" href="#filter">Regular filters</a></h3> - <p><code>Filter</code> objects all extend the <a + <p>Any regular logback-classic filter extends the <a href="../xref/ch/qos/logback/core/filter/Filter.html"><code>Filter</code></a> - abstract class. The <code>decide(Object event)</code> method is - passed a newly created <code>ILoggingEvent</code> instance. + abstract class which consists of the <code>decide(Object + event)</code> method taking an <code>ILoggingEvent</code> instance + as parameter. Logback-classic will ask any given filter to decide + what to do with newly created events. </p> - <h3>Filter chains</h3> - <p>This abstract class assumes that filters are 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 <a - href="../xref/ch/qos/logback/core/spi/FilterReply.html"><code>FilterReply</code></a> - enumeration values, i.e. one of <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>Filters are organized as an ordered list and 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 + <a + href="../xref/ch/qos/logback/core/spi/FilterReply.html"><code>FilterReply</code></a> + enumeration values, i.e. one of <code>FilterReply.DENY</code>, + <code>FilterReply.NEUTRAL</code> or + <code>FilterReply.ACCEPT</code>. If the value returned by + <code>decide</code>() 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-classic <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 MDC, the time of - day or any other part of the logging event. + <p>In logback-classic <code>Filter</code> objects can 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 MDC, the time of day or any + other part of the logging event. </p> <h3>Implementing your own Filter</h3> @@ -745,7 +739,7 @@ configuration (logback-examples/src/main/java/chapter6/duplicateMessage.xml)</em because only 5 repetitions are allowed by default. </p> - <h2>Logback-access</h2> + <h2>In logback-access</h2> <p>Logback-access offers most of the features available with logback-classic. <code>Filter</code> objects are available and http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=9700a02ae011baf8d9404f841... http://github.com/ceki/logback/commit/9700a02ae011baf8d9404f8417485105f0ec5a... commit 9700a02ae011baf8d9404f8417485105f0ec5a02 Merge: 61bfd0d 1d9a3a8 Author: Ceki Gulcu <ceki@qos.ch> Date: Sun Nov 8 20:01:40 2009 +0100 Merge branch 'master' of github.com:ceki/logback http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=1d9a3a816478905ffb518fbd0... http://github.com/ceki/logback/commit/1d9a3a816478905ffb518fbd0603c7ec1e0f5e... commit 1d9a3a816478905ffb518fbd0603c7ec1e0f5e02 Author: Ceki Gulcu <ceki@qos.ch> Date: Fri Nov 6 23:32:32 2009 +0100 - applied Charles changes on mdc.html diff --git a/logback-examples/src/main/java/chapter7/NumberCruncherServer.java b/logback-examples/src/main/java/chapter7/NumberCruncherServer.java index bc78a14..f952706 100644 --- a/logback-examples/src/main/java/chapter7/NumberCruncherServer.java +++ b/logback-examples/src/main/java/chapter7/NumberCruncherServer.java @@ -86,7 +86,7 @@ public class NumberCruncherServer extends UnicastRemoteObject } while ((n % i) == 0); } - // Placing artificial delays in tight-loops will also lead to + // Placing artificial delays in tight loops will also lead to // sub-optimal resuts. :-) delay(100); } diff --git a/logback-site/src/site/pages/manual/mdc.html b/logback-site/src/site/pages/manual/mdc.html index b22e43a..f9c7437 100644 --- a/logback-site/src/site/pages/manual/mdc.html +++ b/logback-site/src/site/pages/manual/mdc.html @@ -145,7 +145,7 @@ public class SimpleMDC { same key will overwrite older values. The code then proceeds to configure logback.</p> - <p>For the sake of consiceness, we have the omitted the code that + <p>For the sake of conciseness, we have the omitted the code that configures logback with the configuration file <a href="http://tinyurl.com/4gy542">simpleMDC.xml</a>. Here is the relevant section from that file. @@ -186,32 +186,31 @@ Richard Nixon - Attributed to the former US president. 17 Nov 1973.</pre></div> <h3>Advanced Use</h3> - <p> - Mapped Diagnostic Contexts shine brightest within client server - architectures. Typically, multiple clients will be served by - multiple threads on the server. Although the methods in the - <code>MDC</code> class are static, the diagnostic context is - managed on a per thread basis, allowing each server thread to - bear a distinct <code>MDC</code> stamp. <code>MDC</code> - operations such as <code>put()</code> and <code>get()</code> - affect only the <code>MDC</code> of the <em>current</em> thread, - and the children of the current thread. The <code>MDC</code> in - other threads remain unaffected. Given that <code>MDC</code> - information is managed on a per thread basis, each thread will - have its own copy of the <code>MDC</code>. Thus, there is no - need for the developer to worry about thread-safety or - synchronization when programming with the <code>MDC</code> - because it safely and transparently handles these issues. + <p>Mapped Diagnostic Contexts shine brightest within client server + architectures. Typically, multiple clients will be served by + multiple threads on the server. Although the methods in the + <code>MDC</code> class are static, the diagnostic context is + managed on a per thread basis, allowing each server thread to bear + a distinct <code>MDC</code> stamp. <code>MDC</code> operations + such as <code>put()</code> and <code>get()</code> affect only the + <code>MDC</code> of the <em>current</em> thread, and the children + of the current thread. The <code>MDC</code> in other threads + remain unaffected. Given that <code>MDC</code> information is + managed on a per thread basis, each thread will have its own copy + of the <code>MDC</code>. Thus, there is no need for the developer + to worry about thread-safety or synchronization when programming + with the <code>MDC</code> because it handles these issues safely + and transparently. </p> - <p> - The next example is somewhat more advanced. - It shows how the <code>MDC</code> can be used in a client-server setting. - The server-side implements the <code>NumberCruncher</code> interface shown in - Example 7.2 below. <code>The NumberCruncher</code> interface contains a single - method named <code>factor()</code>. Using RMI technology, client invokes the - <code>factor()</code> method of the server application to retrieve the distinct - factors of an integer. + <p>The next example is somewhat more advanced. It shows how the + <code>MDC</code> can be used in a client-server setting. The + server-side implements the <code>NumberCruncher</code> interface + shown in Example 7.2 below. <code>The NumberCruncher</code> + interface contains a single method named + <code>factor()</code>. Using RMI technology, the client invokes + the <code>factor()</code> method of the server application to + retrieve the distinct factors of an integer. </p> <em>Example 7.2: The service interface (<a href="../xref/chapter7/NumberCruncher.html"> @@ -315,7 +314,7 @@ public class NumberCruncherServer extends UnicastRemoteObject } while ((n % i) == 0); } - // Placing artificial delays in tight-loops will also lead to + // Placing artificial delays in tight loops will also lead to // sub-optimal resuts. :-) delay(100); } @@ -390,20 +389,22 @@ public class NumberCruncherServer extends UnicastRemoteObject } }</pre> - <p> - The implementation of the <code>factor(int number)</code> method is - of particular relevance. It starts by putting the client's hostname into the - <code>MDC</code> under the key <em>client</em>. The number to factor, - as requested by the client, is put into the <code>MDC</code> under the key - <em>number</em>. After computing the distinct factors of the integer - parameter, the result is returned to the client. Before returning the - result however, the values for the <em>client</em> and <em>number</em> are - cleared by calling the <code>MDC.remove()</code> method. Normally, - a <code>put()</code> operation should be balanced by the corresponding - <code>remove()</code> operation. Otherwise, the <code>MDC</code> will - contain stale values for certain keys. We would recommend that whenever - possible <code>remove()</code> operations be performed within finally blocks, - ensuring their invocation regardless of the execution path of the code. + <p>The implementation of the <code>factor(int number)</code> + method is of particular relevance. It starts by putting the + client's hostname into the <code>MDC</code> under the key + <em>client</em>. The number to factor, as requested by the client, + is put into the <code>MDC</code> under the key + <em>number</em>. After computing the distinct factors of the + integer parameter, the result is returned to the client. Before + returning the result however, the values for the <em>client</em> + and <em>number</em> are cleared by calling the + <code>MDC.remove()</code> method. Normally, a <code>put()</code> + operation should be balanced by the corresponding + <code>remove()</code> operation. Otherwise, the <code>MDC</code> + will contain stale values for certain keys. We would recommend + that whenever possible, <code>remove()</code> operations be + performed within finally blocks, ensuring their invocation + regardless of the execution path of the code. </p> <p> @@ -519,12 +520,12 @@ public class NumberCruncherServer extends UnicastRemoteObject </p> <p>Within the servlet filter's <code>doFilter</code> method, we - can retreive the relevant user data through the request (or a - cookie threin), store it the <code>MDC</code>. Subsequent - processing by other filters and servlets will automatically - benefit from the MDC data that was stored previously. Finally, - when our servlet filter ragains control, we have an oppurtunity - to clean MDC data. + can retrieve the relevant user data through the request (or a + cookie therein), store it the <code>MDC</code>. Subsequent + processing by other filters and servlets will automatically + benefit from the MDC data that was stored previously. Finally, + when our servlet filter regains control, we have an opportunity to + clean MDC data. </p> <p>Here is an implementation of such a filter:</p> @@ -563,7 +564,7 @@ public class UserServletFilter implements Filter { Principal principal = req.getUserPrincipal(); // Please note that we could have also used a cookie to - // retreive the user name + // retrieve the user name if (principal != null) { String username = principal.getName(); @@ -594,12 +595,13 @@ public class UserServletFilter implements Filter { } }</pre> - <p> - When the filter's <code>doFilter()</code> method is called, is first looks for a - <code>java.security.Principal</code> object in the request. This object contains - the name of the currently authenticated user. In case the user principal is not set, - the filter looks for a session attribute matching a given key (here <em>username</em>). - If a user information is found, it is registered in the <code>MDC</code>. + <p>When the filter's <code>doFilter()</code> method is called, it + first looks for a <code>java.security.Principal</code> object in the + request. This object contains the name of the currently + authenticated user. In case the user principal is not set, the + filter looks for a session attribute matching a given key (here + <em>username</em>). If a user information is found, it is + registered in the <code>MDC</code>. </p> <p>Once the filter chain has completed, the filter removes the user @@ -609,18 +611,18 @@ public class UserServletFilter implements Filter { <p>The approach we just outlined sets MDC data only for the duration of the request and only for the thread processing it. Other threads are unaffected. Furthermore, any given thread will contain correct - MDC data any point in time.</p> + MDC data at any point in time.</p> <h3>MDC And Managed Threads</h3> - <p>A copy of mapped diagnostic context can not always be inherited - by worker thread from the initiating thread. This is the case when - <code>java.util.concurrent.Executors</code> is used for thread - management. For instance, <code>newCachedThreadPool</code> method - creates a <code>ThreadPoolExecutor</code> and like other thread - pooling code it has intricate thread creation logic. + <p>A copy of the mapped diagnostic context can not always be + inherited by worker threads from the initiating thread. This is the + case when <code>java.util.concurrent.Executors</code> is used for + thread management. For instance, <code>newCachedThreadPool</code> + method creates a <code>ThreadPoolExecutor</code> and like other + thread pooling code, it has intricate thread creation logic. </p> <p>In such cases, it is recommended that @@ -628,8 +630,8 @@ public class UserServletFilter implements Filter { (master) thread before submitting a task to the executor. When the task runs, as its first action, it should invoke <code>MDC.setContextMapValues()</code> to associate the stored copy - of the orinal MDC values with the new <code>Executor</code> managed - thread. + of the original MDC values with the new <code>Executor</code> + managed thread. </p> http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=5a457959b54a496b8d4a01c73... http://github.com/ceki/logback/commit/5a457959b54a496b8d4a01c73ba1443edab66c... commit 5a457959b54a496b8d4a01c73ba1443edab66c20 Author: Ceki Gulcu <ceki@qos.ch> Date: Fri Nov 6 23:17:08 2009 +0100 Applies Charles proof-reading of filters.html diff --git a/logback-site/src/site/pages/manual/filters.html b/logback-site/src/site/pages/manual/filters.html index e15f902..6127521 100644 --- a/logback-site/src/site/pages/manual/filters.html +++ b/logback-site/src/site/pages/manual/filters.html @@ -105,14 +105,14 @@ <p>Creating your own filter is not difficult. 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 + method, allowing you to concentrate 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 + neutral response to any logging event whose message does not contain this String. </p> @@ -246,7 +246,7 @@ public class SampleFilter extends Filter { href="../xref/ch/qos/logback/core/filter/EvaluatorFilter.html"> <code>EvaluatorFilter</code></a> class. These filters use an <a href="../xref/ch/qos/logback/core/boolex/EventEvaluator.html"> - <code>EventEvaluator</code></a> object to decide wether to accept + <code>EventEvaluator</code></a> object to decide whether to accept or deny a request. This allows unprecedented flexibility in the way that you can affect filtering of logging events. </p> @@ -256,7 +256,7 @@ public class SampleFilter extends Filter { and to specify an <em>evaluation expression</em>, that is a boolean expression in regular Java syntax. These evaluation expressions are compiled on-the-fly during the interpretation of - the configration file. It is the users reponsibility to ensure + the configuration file. It is the users reponsibility to ensure that the expression is boolean, that it evaluates to true or false. In evaluation expressions, logback implicitly exposes various fields of a logging event as variables. The list of these @@ -327,9 +327,9 @@ public class SampleFilter extends Filter { <td>mdc </td> <td><code>Map</code></td> - <td>A map containing all the MDC values at the time of the - creation of the logging event. A value can be access by using the - following expression: <em>mdc.get("myKey")</em>. + <td>A map containing all the MDC values at the time of the + creation of the logging event. A value can be accessed by + using the following expression: <em>mdc.get("myKey")</em>. </td> </tr> <tr class="alt"> @@ -391,7 +391,7 @@ public class SampleFilter extends Filter { <p>The <a href="../xref/chapter6/FilterEvents.html"><code>FilterEvents</code></a> application issues ten logging requests, numbered 0 to 9. Let us - rist run <code>FilterEvents</code> class without any filters: + first run <code>FilterEvents</code> class without any filters: </p> <div class="source"><pre> @@ -415,7 +415,7 @@ java chapter6.FilterEvents src/main/java/chapter6/basicConfiguration.xml <p>Suppose that we want to get rid of the billing information. The <em>basicEventEvaluator.xml</em> configuration file just - desribed, does exactly what we want.</p> + described, does exactly what we want.</p> <p>Running with filters:</p> <p class="source">java chapter6.FilterEvents src/main/java/chapter6/basicEventEvaluator.xml</p> @@ -442,7 +442,7 @@ java chapter6.FilterEvents src/main/java/chapter6/basicConfiguration.xml the logging event. </p> - <p>Overall, they work much like the previously mentionned + <p>Overall, they work much like the previously mentioned filters. However, there are two main differences between <code>Filter</code> and <code>TurboFilter</code> objects. </p> @@ -458,18 +458,18 @@ java chapter6.FilterEvents src/main/java/chapter6/basicConfiguration.xml <code>TurboFilter</code> objects do not require the instantiation of a logging event to filter a logging request. As such, turbo filters are intended for high performance filtering of logging - event, even before they are created. + events, even before they are created. </p> <h3>Implementing your own TurboFilter</h3> - <p> - To create your own <code>TurboFilter</code> component, just extend the - <code>TurboFilter</code> abstract class. As previously, when implementing - a custumized filter object, developing a custom <code>TurboFilter</code> only - ask that one implement the <code>decide()</code> method. In the next example, we - create a slightly more complex filter: + <p>To create your own <code>TurboFilter</code> component, just + extend the <code>TurboFilter</code> abstract class. As previously, + when implementing a customized filter object, developing a custom + <code>TurboFilter</code> only asks that one implement the + <code>decide()</code> method. In the next example, we create a + slightly more complex filter: </p> <em>Example 6.6: Basic custom <code>TurboFilter</code> (<a href="../xref/chapter6/SampleTurboFilter.html">logback-examples/src/main/java/chapter6/SampleTurboFilter.java</a>)</em> @@ -560,9 +560,9 @@ public class SampleTurboFilter extends TurboFilter { <p>Logback classic ships with several <code>TurboFilter</code> classes ready for use. The <a href="../xref/ch/qos/logback/classic/turbo/MDCFilter.html"><code>MDCFilter</code></a> - check the presence of a given value in the MDC whereas <a + checks the presence of a given value in the MDC whereas <a href="../apidocs/ch/qos/logback/classic/turbo/DynamicThresholdFilter.html"><code>DynamicThresholdFilter</code></a> - allows filtering based on MDC key/level thresold associations. On + allows filtering based on MDC key/level threshold associations. On the other hand, <a href="../xref/ch/qos/logback/classic/turbo/MarkerFilter.html"><code>MarkerFilter</code></a> checks for the presence of a specific marker associated with the @@ -641,7 +641,7 @@ configuration (logback-examples/src/main/java/chapter6/turboFilters.xml)</em> requirements and was accepted. </p> - <p>On the other hand, the 6th request, that is a <em>ERROR</em> + <p>On the other hand, the 6th request, that is an <em>ERROR</em> level request should have been displayed. But it satisfied the second <code>TurboFilter</code> whose <span class="option">OnMatch</span> option is set to <em>DENY</em>. @@ -753,7 +753,7 @@ configuration (logback-examples/src/main/java/chapter6/duplicateMessage.xml)</em handle access' implementation of logging events: <code>AccessEvent</code>. Thus, a customized filter for logback access follows strictly the same rules as those for - logback-classic, except for the event type recieved as parameter. + logback-classic, except for the event type received as parameter. On the other hand, <code>TurboFilter</code> objects are supported by logback-access. </p> ----------------------------------------------------------------------- Summary of changes: .../main/java/chapter7/NumberCruncherServer.java | 2 +- logback-site/src/site/pages/manual/filters.html | 134 ++++++++++---------- logback-site/src/site/pages/manual/mdc.html | 126 ++++++++++--------- 3 files changed, 129 insertions(+), 133 deletions(-) hooks/post-receive -- Logback: the generic, reliable, fast and flexible logging framework.