Author: seb Date: Fri Jan 5 19:38:35 2007 New Revision: 1165 Added: logback/trunk/logback-examples/src/main/java/chapter7/UserServletFilter.java Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/joran.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/mdc.xml logback/trunk/logback-site/src/site/xdocTemplates/setup.xml logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml Log: Minor modifications in chapters and setup page Added an example in mdc page Added: logback/trunk/logback-examples/src/main/java/chapter7/UserServletFilter.java ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter7/UserServletFilter.java Fri Jan 5 19:38:35 2007 @@ -0,0 +1,93 @@ +/** + * Logback: the reliable, generic, fast and flexible logging framework. + * + * Copyright (C) 1999-2006, QOS.ch + * + * This library is free software, you can redistribute it and/or modify it under + * the terms of the GNU Lesser General Public License as published by the Free + * Software Foundation. + */ + +package chapter7; + +import java.io.IOException; +import java.security.Principal; + +import javax.servlet.Filter; +import javax.servlet.FilterChain; +import javax.servlet.FilterConfig; +import javax.servlet.ServletException; +import javax.servlet.ServletRequest; +import javax.servlet.ServletResponse; +import javax.servlet.http.HttpServletRequest; +import javax.servlet.http.HttpSession; + +import ch.qos.logback.classic.MDC; + +/** + * A simple servlet filter that puts the username + * found either in the Principle or as a session attribute + * in the MDC. + * + * The value is removed from the MDC once the request has been + * fully processed. + * + * To be used, add the following lines to a web.xml file + * + * <filter> + * <filter-name>User Servlet Filter</filter-name> + * <filter-class> + * chapter7.UserServletFilter + * </filter-class> + * </filter> + * <filter-mapping> + * <filter-name>User Servlet Filter</filter-name> + * <url-pattern>/*</url-pattern> + * </filter-mapping> + * + * @author Sébastien Pennec + */ +public class UserServletFilter implements Filter { + + boolean userRegistered = false; + + private final String userKey = "username"; + + public void destroy() { + } + + public void doFilter(ServletRequest request, ServletResponse response, + FilterChain chain) throws IOException, ServletException { + + HttpServletRequest req = (HttpServletRequest) request; + Principal principal = req.getUserPrincipal(); + + if (principal != null) { + String username = principal.getName(); + registerUsername(username); + } else { + HttpSession session = req.getSession(); + String username = (String)session.getAttribute(userKey); + registerUsername(username); + } + + try { + chain.doFilter(request, response); + } finally { + if (userRegistered) { + MDC.remove(userKey); + } + } + } + + public void init(FilterConfig arg0) throws ServletException { + } + + private void registerUsername(String username) { + if (username != null && username.trim().length() > 0) { + MDC.put(userKey, username); + userRegistered = true; + } + } + +} 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 Fri Jan 5 19:38:35 2007 @@ -44,13 +44,11 @@ <div class="highlight"> <p> - Running the examples provided with - the complete logback manual only requires - a few steps. - </p> - <p> - To set you up quickly, please visit - the <a href="../setup.html">dedicated page</a>. + In order to run the examples in this chapter, you need + to make sure that certain jar files are present on the + classpath. + Please refer to the <a href="../setup.html">setup page</a> + for further details. </p> </div> 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 Fri Jan 5 19:38:35 2007 @@ -53,13 +53,11 @@ <div class="highlight"> <p> - Running the examples provided with - the complete logback manual only requires - a few steps. - </p> - <p> - To set you up quickly, please visit - the <a href="../setup.html">dedicated page</a>. + In order to run the examples in this chapter, you need + to make sure that certain jar files are present on the + classpath. + Please refer to the <a href="../setup.html">setup page</a> + for further details. </p> </div> Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/joran.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/manual/joran.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/joran.xml Fri Jan 5 19:38:35 2007 @@ -42,15 +42,13 @@ </tr> </table> - <div class="highlight"> + <div class="highlight"> <p> - Running the examples provided with - the complete logback manual only requires - a few steps. - </p> - <p> - To set you up quickly, please visit - the <a href="../setup.html">dedicated page</a>. + In order to run the examples in this chapter, you need + to make sure that certain jar files are present on the + classpath. + Please refer to the <a href="../setup.html">setup page</a> + for further details. </p> </div> Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml Fri Jan 5 19:38:35 2007 @@ -44,15 +44,13 @@ </tr> </table> - <div class="highlight"> + <div class="highlight"> <p> - Running the examples provided with - the complete logback manual only requires - a few steps. - </p> - <p> - To set you up quickly, please visit - the <a href="../setup.html">dedicated page</a>. + In order to run the examples in this chapter, you need + to make sure that certain jar files are present on the + classpath. + Please refer to the <a href="../setup.html">setup page</a> + for further details. </p> </div> Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/mdc.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/manual/mdc.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/mdc.xml Fri Jan 5 19:38:35 2007 @@ -52,13 +52,11 @@ </p> <div class="highlight"> <p> - Running the examples provided with - the complete logback manual only requires - a few steps. - </p> - <p> - To set you up quickly, please visit - the <a href="../setup.html">dedicated page</a>. + In order to run the examples in this chapter, you need + to make sure that certain jar files are present on the + classpath. + Please refer to the <a href="../setup.html">setup page</a> + for further details. </p> </div> @@ -189,6 +187,8 @@ multiple logger invocations. </p> + <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. @@ -497,5 +497,124 @@ Because the <code>MDC</code> is under the control of the application developer, <code>MDC</code> stamps do not suffer from this problem. </p> + + + + <h3>Automating access to the <code>MDC</code></h3> + + <p> + As we've seen, the <code>MDC</code> is very useful when dealing with multiple + clients. In the case of a web application that manages user authentication, one + simple solution could be to set the user's name in the <code>MDC</code> and remove + it once the user logs out. Unfortunately, it is not always possible to achieve + reliable results using this technique. Since <code>MDC</code> is managing + information on a <em>per thread</em> basis, a server that recycles + threads might lead to false information contained in the <code>MDC</code>. + </p> + + <p> + To allow the information contained in the <code>MDC</code> to be correct + at all times when a request is processed, a solution might be to store the + username at the beginning of the process, and remove it at the end of + said process. A servlet + <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/Filter.html"> + <code>Filter</code></a> is a good tool to have at + hand in such case. + </p> + + <p> + By using a servlet filter, one can access the request, try to access + to relevant user information and store it in the <code>MDC</code>. + Then, after the process of creating the response, one just needs + to remove the user information from the <code>MDC</code>. + </p> + + <p> + Here is an implementation of such a filter: + </p> + +<em>Example 7.5: User servlet filter (<a href="../xref/chapter7/UserServletFilter.html"> +logback-examples/src/main/java/chapter7/UserServletFilter.java)</a></em> +<div class="source"><pre>package chapter7; + +import java.io.IOException; +import java.security.Principal; + +import javax.servlet.Filter; +import javax.servlet.FilterChain; +import javax.servlet.FilterConfig; +import javax.servlet.ServletException; +import javax.servlet.ServletRequest; +import javax.servlet.ServletResponse; +import javax.servlet.http.HttpServletRequest; +import javax.servlet.http.HttpSession; + +import ch.qos.logback.classic.MDC; + +public class UserServletFilter implements Filter { + + boolean userRegistered = false; + + private final String userKey = "username"; + + public void destroy() { + } + + public void doFilter(ServletRequest request, ServletResponse response, + FilterChain chain) throws IOException, ServletException { + + HttpServletRequest req = (HttpServletRequest) request; + Principal principal = req.getUserPrincipal(); + + if (principal != null) { + String username = principal.getName(); + registerUsername(username); + } else { + HttpSession session = req.getSession(); + String username = (String)session.getAttribute(userKey); + registerUsername(username); + } + + try { + chain.doFilter(request, response); + } finally { + if (userRegistered) { + MDC.remove(userKey); + } + } + } + + public void init(FilterConfig arg0) throws ServletException { + } + + private void registerUsername(String username) { + if (username != null && username.trim().length() > 0) { + MDC.put(userKey, username); + userRegistered = true; + } + } +}</pre></div> + + + <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> + + <p> + Once the filter chain has completed, the filter removes the user information + from the <code>MDC</code>. + </p> + + <p> + With this filter, the user information is present in the <code>MDC</code> only + the time it takes to process the request. The thread may be reused to process a + request for another user without risking to display false information in the + logs. + </p> + </body> </document> \ No newline at end of file Modified: logback/trunk/logback-site/src/site/xdocTemplates/setup.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/setup.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/setup.xml Fri Jan 5 19:38:35 2007 @@ -12,8 +12,8 @@ <h2>Classpath Setup</h2> <p> -Setting up an environment to run the logback examples mainly consists -of putting a few jars in your classpath. For most examples, these are: +In order to run the examples provided in the documentation, +you need to add the following jars to your class path: </p> <ul> @@ -23,6 +23,8 @@ <p>slf4j-api-${slf4j.version}.jar</p> </ul> +<h3>Example</h3> + <p> Assuming your current directory is <em>$LOGBACK_HOME/logback-examples</em>, where <em>$LOGBACK_HOME</em> is the @@ -38,21 +40,22 @@ chapter1.HelloWorld1</pre></div> <p> -Having to include the jars in each command you run is not practical, -to say the least. Two scripts are available to help you setup the jars -in your system's classpath. They are located in -<em>$LOGBACK_HOME/logback-examples</em>. +It is more convenient to set the CLASSPATH environment variable +once and for all before running the examples. </p> - -<p> -To run these scripts, you need to edit them and set the variable called -<em>LB_HOME</em> to the directory where you've installed logback. +<p>The <em>setClasspath.cmd</em> script located in the $LOGBACK_HOME/logback-examples +folder will configure the class path for the MS Windows platform. For Unix, the +equivalent script is <em>setClasspath.sh</em>. </p> +<p>Please remember to adapt the <em>LB_HOME</em> variable for your local environment.</p> + <p> -Unless specified differently, running the examples by using the command -provided in the manual will work if it is run from the -<em>$LOGBACK_HOME/logback-examples</em> directory. +Please be aware that many examples will launch java classes along +with configuration files. To access these files by using +the same commands as written in the documentation, you will need to +issue the commands in the <em>$LOGBACK_HOME/logback-examples</em> +directory. </p> Modified: logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml Fri Jan 5 19:38:35 2007 @@ -97,6 +97,16 @@ <h2>First Baby Step</h2> + <div class="highlight"> + <p> + In order to run the examples in this introduction, you need + to make sure that certain jar files are present on the + classpath. + Please refer to the <a href="setup.html">setup page</a> + for further details. + </p> + </div> + <h3>Requirements</h3> <p>Logback-classic module requires the presence