[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é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
More information about the logback-dev
mailing list