[logback-dev] svn commit: r1293 - logback/trunk/logback-site/src/site/xdocTemplates/manual
noreply.seb at qos.ch
noreply.seb at qos.ch
Tue Jan 30 17:09:30 CET 2007
Author: seb
Date: Tue Jan 30 17:09:29 2007
New Revision: 1293
Added:
logback/trunk/logback-site/src/site/xdocTemplates/manual/contextSelector.xml
Modified:
logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml
Log:
Added a context selector document, as the 8th chapter of the manual
Added: logback/trunk/logback-site/src/site/xdocTemplates/manual/contextSelector.xml
==============================================================================
--- (empty file)
+++ logback/trunk/logback-site/src/site/xdocTemplates/manual/contextSelector.xml Tue Jan 30 17:09:29 2007
@@ -0,0 +1,246 @@
+<document>
+<!--
+
+ Warning: do not use any auto-format function on this file.
+ Since "source" divs use pre as white-space, it affects the
+ look of the code parts in this document.
+
+ -->
+
+ <body>
+ <h2>Chapter 8: Context Selector</h2>
+ <div class="author">
+ Authors: Ceki Gülcü, Sébastien Pennec
+ </div>
+
+ <table>
+ <tr>
+ <td valign="top" align="top">
+ <a rel="license"
+ href="http://creativecommons.org/licenses/by-nc-sa/2.5/">
+ <img alt="Creative Commons License"
+ style="border-width: 0"
+ src="http://creativecommons.org/images/public/somerights20.png" />
+ </a>
+ </td>
+ <td>
+ <p>Copyright © 2000-2006, QOS.ch</p>
+
+ <p>
+ <!--Creative Commons License-->
+ This work is licensed under a
+ <a rel="license"
+ href="http://creativecommons.org/licenses/by-nc-sa/2.5/">
+ Creative Commons
+ Attribution-NonCommercial-ShareAlike 2.5
+ License
+ </a>.
+ <!--/Creative Commons License-->
+ </p>
+ </td>
+ </tr>
+ </table>
+
+<h3>Introduction</h3>
+
+<p>
+When working with several Web applications, all running on one server, the
+multiplications of <code>LoggerContext</code> objects might reveal itself
+a tricky issue.
+</p>
+
+<p>
+Logback provides a simple yet powerful way of dealing with multiple
+contexts, without corruption of data, nor collusion between context
+instances.
+</p>
+
+<p>
+One thing we know for sure is that JNDI environments are independant. Thus
+setting environment variables in each application will allow a given component
+to know which application it is dealing with at the moment. This is basically
+the mechanism that uses logback to provide easy access to the right
+<code>LoggerContext</code> instance.
+</p>
+
+<p>
+The component that manages the different contexts is the
+<a href="../xref/ch/qos/logback/classic/selector/ContextSelector.html">
+ContextSelector</a>
+implementation. The JNDI-specific implementation is called
+<a href="../xref/ch/qos/logback/classic/selector/ContextJNDISelector.html">
+ContextJNDISelector</a>. This
+object is instanciated at the very fist time a Web applications calls logback.
+</p>
+
+<p>
+Each Web application provides two environment variables. One that specifies
+the application's <code>LoggerContext</code> name, and one that provides the
+path to the xml file that will be used to configure the context.
+</p>
+
+
+<h3>Setting up the <code>ContextSelector</code>.</h3>
+
+<h4>The server side</h4>
+
+<p>
+First, place the logback jars (that is logback-classic-<em>VERSION</em>.jar,
+logback-core-<em>VERSION</em>.jar and slf4j-api-<em>VERSION</em>.jar) in the
+server's shared class directory. In Tomcat, this directory is
+<em>TOMCAT_HOME/common/lib/</em>. This directory might be different depending
+on the server you are using. For example, with Jetty, this directory is located
+at <em>JETTY_HOME/lib/</em>.
+</p>
+
+<p>
+The next step is to let logback know that it will have to use JNDI to manage
+the context instances. This is done thanks to a System Property. When launching
+the web server, make sure that the <em>logback.ContextSelector</em> property is
+linked with the <em>JNDI</em> value. In Tomcat, this can be done by editing the
+<em>TOMCAT_HOME/bin/catalina.sh</em> or <em>TOMCAT_HOME/bin/catalina.bat</em>
+file, and adding the following line to the java options:
+</p>
+
+<div class="source"><pre>-Dlogback.ContextSelector=JNDI</pre></div>
+
+<p>
+In Jetty, adding an environment variable is done by adding the following
+xml element in the <em>JETTY_HOME/etc/jetty.xml</em> configuration file:
+</p>
+
+<div class="source"><pre><Call class="java.lang.System" name="setProperty">
+ <Arg>logback.ContextSelector</Arg>
+ <Arg>JNDI</Arg>
+</Call></pre></div>
+
+<h4>Configuring each Web application</h4>
+
+<p>
+While each Web application will need the logback jars to compile, they need not
+nor should be placed within the Web application's WAR file.
+</p>
+
+<p>
+In each Web application's <em>web.xml</em> file, two JNDI environment entries
+are needed. The first one specifies the desired name of the application's
+<code>LoggerContext</code>. It takes the following form:
+</p>
+
+<div class="source"><pre><env-entry>
+ <description>JNDI logging context for this app</description>
+ <env-entry-name>logback/context-name</env-entry-name>
+ <env-entry-type>java.lang.String</env-entry-type>
+ <env-entry-value>ContextApp-A</env-entry-value>
+</env-entry></pre></div>
+
+<p>
+The second JNDI entry will lead logback to the application's own xml configuration
+file. It can be declared as shown below:
+</p>
+
+<div class="source"><pre><env-entry>
+ <description>URL for configuring logback context</description>
+ <env-entry-name>logback/configuration-resource</env-entry-name>
+ <env-entry-type>java.lang.String</env-entry-type>
+ <env-entry-value>logback-app-A.xml</env-entry-value>
+</env-entry></pre></div>
+
+<p>
+Specifying only the name of the file will lead logback to search for it in
+the Web application's <em>WEB-INF/classes/</em> directory.
+</p>
+
+<p>
+When the Web application is recycled or shutdown, it is very often
+useful to recycle the associated <code>LoggerContext</code>. This can
+be done by installing a <code>ServletContextListener</code> which will
+detach the context from the <code>ContextSelector</code> and shut it down.
+</p>
+
+<p>
+The <a href="../xref/ch/qos/logback/classic/selector/servlet/ContextDetachingSCL.html
+"><code>ContextDetachingSCL</code></a> class which
+ships with logback does exactly that. To use it, add the following
+lines to your Web application's <em>web.xml</em> file.
+</p>
+
+<div class="source"><pre><listener>
+ <listener-class>ch.qos.logback.classic.selector.servlet.ContextDetachingSCL</listener-class>
+</listener</pre></div>
+
+
+<p>
+Using the <code>ContextJNDISelector</code> might slow down your
+application a bit, because of the JNDI call that is issued each time
+a <code>LoggerContext</code> is required. To prevent the cost
+of this call, logback ships with a <code>LoggerContextFilter</code>
+component. This filter is a <code>javax.servlet.Filter</code> implementation
+that gets the environment-specific <code>LoggerContext</code> and sets it
+in a <code>ThreadLocal</code> variable. Each time
+the <code>ContextSelector</code> will be called to provide the
+Web application's own <code>LoggerContext</code>, it will first check
+if the <code>ThreadLocal</code> variable is set. If it is, then the call
+to the JNDI environment will not be issued.
+</p>
+
+<p>
+Like all servlet filters, the
+<a href="../xref/ch/qos/logback/classic/selector/servlet/LoggerContextFilter.html">
+<code>LoggerContextFilter</code></a> can act
+before and after the Web application's process. This allows the filter
+to set the <code>ThreadLocal</code> variable at the beginning of the process
+and to remove it once the Web application has finished processing the request.
+This behaviour permits the thread to be recycled for use by another Web
+application and still provide the correct <code>LoggerContext</code>.
+</p>
+
+<p>The <code>LoggerContextFilter</code> can be used by adding the following
+lines to your Web application's <em>web.xml</em> file.
+</p>
+
+<div class="source"><pre><filter>
+ <filter-name>LoggerContextFilter</filter-name>
+ <filter-class>ch.qos.logback.classic.selector.servlet.LoggerContextFilter</filter-class>
+</filter>
+<filter-mapping>
+ <filter-name>LoggerContextFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+</filter-mapping></pre></div>
+
+<h4>Some recommandations</h4>
+
+<p>
+To avoid confusion, it is prudent to name each Web application
+in the <em>web.xml</em> file, as in:
+</p>
+
+<div class="source"><pre><display-name>Name_Of_My_WebApp</display-name></pre></div>
+
+<p>
+We recommend that you name logback configuration resources uniquely. In
+particualar, avoid naming the logback configuration resource as
+<em>logback.xml</em> for a non-default logger context.
+</p>
+
+<p>
+While trying to configure the Web application logback would search for
+the resource <em>logback.xml</em> using the thread context classloader. Thus,
+it would first attempt to locate <em>logback.xml</em> file using the
+classloader specific to the Web application. However, if the file
+<em>logback.xml</em> did not exist there (if you forgot to put a custom one in
+<em>WEB-INF/classes</em>), and if the file <em>logback.xml</em> existed higher up in the
+classloader tree, we could end up in a situation where the logger
+context for your Web application would be configured using the same
+file as that used to configure the default context. Such
+involuntary sharing of the same configuration by multiple repositories
+will result in corrupt log output.
+</p>
+
+
+
+
+
+
+</body>
+</document>
\ No newline at end of file
Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml
==============================================================================
--- logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml (original)
+++ logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml Tue Jan 30 17:09:29 2007
@@ -85,6 +85,11 @@
<li><p>
<a href="mdc.html"><b>Chapter 7: Diagnostic Context</b></a>
</p></li>
+
+ <li><p>
+ <a href="contextSelector.html"><b>Chapter 8: Context Selector</b></a>
+ </p></li>
+
</ul>
</div>
</body>
More information about the logback-dev
mailing list