[logback-dev] svn commit: r1165 - in logback/trunk: logback-examples/src/main/java/chapter7 logback-site/src/site/xdocTemplates logback-site/src/site/xdocTemplates/manual

noreply.seb at qos.ch noreply.seb at qos.ch
Fri Jan 5 19:38:36 CET 2007


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&eacute;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 &amp;&amp; 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



More information about the logback-dev mailing list