[logback-dev] svn commit: r1310 - in logback/trunk/logback-site/src/site/resources: . manual

Author: seb Date: Mon Feb 5 14:28:49 2007 New Revision: 1310 Modified: logback/trunk/logback-site/src/site/resources/access.html logback/trunk/logback-site/src/site/resources/bridge.html logback/trunk/logback-site/src/site/resources/bugreport.html logback/trunk/logback-site/src/site/resources/demo.html logback/trunk/logback-site/src/site/resources/documentation.html logback/trunk/logback-site/src/site/resources/download.html logback/trunk/logback-site/src/site/resources/index.html logback/trunk/logback-site/src/site/resources/jmxConfig.html logback/trunk/logback-site/src/site/resources/license.html logback/trunk/logback-site/src/site/resources/mailinglist.html logback/trunk/logback-site/src/site/resources/manual/appenders.html logback/trunk/logback-site/src/site/resources/manual/architecture.html logback/trunk/logback-site/src/site/resources/manual/contextSelector.html logback/trunk/logback-site/src/site/resources/manual/filters.html logback/trunk/logback-site/src/site/resources/manual/index.html logback/trunk/logback-site/src/site/resources/manual/introduction.html logback/trunk/logback-site/src/site/resources/manual/joran.html logback/trunk/logback-site/src/site/resources/manual/layouts.html logback/trunk/logback-site/src/site/resources/manual/mdc.html logback/trunk/logback-site/src/site/resources/news.html logback/trunk/logback-site/src/site/resources/repos.html logback/trunk/logback-site/src/site/resources/setup.html logback/trunk/logback-site/src/site/resources/team.html Log: rebuild of the html pages Modified: logback/trunk/logback-site/src/site/resources/access.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/access.html (original) +++ logback/trunk/logback-site/src/site/resources/access.html Mon Feb 5 14:28:49 2007 @@ -19,33 +19,36 @@ </div> <div id="content"> - <h2>Access log with logback, Jetty and Tomcat</h2> <div class="author"> - Authors: Ceki G�lc�, S�bastien Pennec + Authors: Ceki Gülcü, Sébastien Pennec </div> - <table class="bodyTable"> - <tr class="a"> - <td> - <a 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"></img> + <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>Copyright © 2000-2006, QOS.ch</p> <p> - + <!--Creative Commons License--> This work is licensed under a - <a href="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + <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> @@ -82,7 +85,8 @@ <p> The <a href="xref/ch/qos/logback/access/tomcat/LogbackValve.html"> <code>ch.qos.logback.access.tomcat.LogbackValve</code></a> - class extends Tomcat's <code><a href="http://tomcat.apache.org/tomcat-5.5-doc/catalina/docs/api/org/apache/catalina/valves/ValveBase.html"> + class extends Tomcat's <code><a + href="http://tomcat.apache.org/tomcat-5.5-doc/catalina/docs/api/org/apache/catalina/valves/ValveBase.html"> ValveBase</a></code> class. This class is used to allow external components to be integrated into Tomcat. @@ -93,7 +97,7 @@ <code>LogbackValve</code>, add the following lines to the tomcat server configuration file, namely <em>$TOMCAT_HOME/conf/server.xml</em>: </p> - <div class="source"><pre><Valve className="ch.qos.logback.access.tomcat.LogbackValve"/></pre></div> + <div class="source"><pre><Valve className="ch.qos.logback.access.tomcat.LogbackValve"/></pre></div> <p> This line need to be nested in an <em>Engine</em> element. </p> @@ -124,7 +128,8 @@ <p> The <a href="xref/ch/qos/logback/access/jetty/RequestLogImpl.html"> <code>ch.qos.logback.access.jetty.RequestLogImpl</code></a> - class implements jetty's <code><a href="http://jetty.mortbay.org/apidocs/org/mortbay/jetty/RequestLog.html">RequestLog</a></code> + class implements jetty's <code><a + href="http://jetty.mortbay.org/apidocs/org/mortbay/jetty/RequestLog.html">RequestLog</a></code> interface. This interface is used by Jetty to allow external components to manage request logging. </p> @@ -140,10 +145,10 @@ <code>RequestLogImpl</code>, add the following lines to the jetty configuration file, namely <em>$JETTY_HOME/etc/jetty.xml</em>: </p> - <div class="source"><pre><Ref id="requestLog"> - <Set name="requestLog"> - <New id="requestLogImpl" - class="ch.qos.logback.access.jetty.RequestLogImpl"> + <div class="source"><pre><Ref id="requestLog"> + <Set name="requestLog"> + <New id="requestLogImpl" + class="ch.qos.logback.access.jetty.RequestLogImpl"> </New> </Set> </Ref></pre></div> @@ -165,12 +170,12 @@ jetty configuration file, with a path to the logback access configuration file. </p> - <div class="source"><pre><Ref id="requestLog"> - <Set name="requestLog"> - <New id="requestLogImpl" - class="ch.qos.logback.access.jetty.RequestLogImpl"> + <div class="source"><pre><Ref id="requestLog"> + <Set name="requestLog"> + <New id="requestLogImpl" + class="ch.qos.logback.access.jetty.RequestLogImpl"> </New> - <Set name="fileName">path/to/myaccess.xml</Set> + <Set name="fileName">path/to/myaccess.xml</Set> </Set> </Ref></pre></div> @@ -190,48 +195,49 @@ immediately put to use: </p> <div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> <layout - class="ch.qos.logback.access.PatternLayout"> - <Pattern>%h %l %u %user %date "%r" %s %b</Pattern> + class="ch.qos.logback.access.PatternLayout"> + <Pattern>%h %l %u %user %date "%r" %s %b</Pattern> </layout> </appender> - <appender-ref ref="STDOUT" /> + <appender-ref ref="STDOUT" /> </configuration></pre></div> <p> It declares a <code>ConsoleAppender</code> which directs its output at the console. The <code>ConsoleAppender</code> contains a <code>PatternLayout</code> format the output. The log format is - specied using the %h %l %u %user %date "%r" %s %b" pattern which + specied using the %h %l %u %user %date "%r" %s %b" pattern which is the Commong Log Format (CLF). This format is recognized by log - analysers such as <a href="http://www.analog.cx/">Analog</a> or <a href="http://awstats.sourceforge.net/">AWStats</a>. + analysers such as <a href="http://www.analog.cx/">Analog</a> or <a + href="http://awstats.sourceforge.net/">AWStats</a>. </p> - <p>Instead of specifying the complete pattern, the word "common" - or "clf" can be used as a shorthand. Thus, the following are all + <p>Instead of specifying the complete pattern, the word "common" + or "clf" can be used as a shorthand. Thus, the following are all equivalent </p> - <div class="source"><pre><Pattern>%h %l %u %user %date "%r" %s %b</Pattern> -<Pattern>common</Pattern> -<Pattern>clf</Pattern></pre></div> - - <p>The so called "combined" format is also widely recognized. It is - defined as the '%h %l %u %t "%r" %s %b "%i{Referer}" - "%i{User-Agent}"' pattern. As a facilitator, you can use the - "combined" as a shorthand. Thus, the following directive + <div class="source"><pre><Pattern>%h %l %u %user %date "%r" %s %b</Pattern> +<Pattern>common</Pattern> +<Pattern>clf</Pattern></pre></div> + + <p>The so called "combined" format is also widely recognized. It is + defined as the '%h %l %u %t "%r" %s %b "%i{Referer}" + "%i{User-Agent}"' pattern. As a facilitator, you can use the + "combined" as a shorthand. Thus, the following directive </p> - <div class="source"><pre><layout class="ch.qos.logback.access.PatternLayout"> - <Pattern>%h %l %u %t "%r" %s %b "%i{Referer}" "%i{User-Agent}"</Pattern> + <div class="source"><pre><layout class="ch.qos.logback.access.PatternLayout"> + <Pattern>%h %l %u %t "%r" %s %b "%i{Referer}" "%i{User-Agent}"</Pattern> </layout></pre></div> <p>is equivalent to:</p> - <div class="source"><pre><layout class="ch.qos.logback.access.PatternLayout"> - <Pattern>combined</Pattern> + <div class="source"><pre><layout class="ch.qos.logback.access.PatternLayout"> + <Pattern>combined</Pattern> </layout></pre></div> @@ -240,20 +246,20 @@ <p>Another configuration file, using logback' <code>RollingFileAppender</code>, could be:</p> <div class="source"><pre><configuration> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> - <File>access.log"</File> + <appender name="FILE" + class="ch.qos.logback.core.rolling.RollingFileAppender"> + <File>access.log"</File> <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> + class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> <FileNamePattern>access.%d{yyyy-MM-dd}.log.zip</FileNamePattern> </rollingPolicy> - <layout class="ch.qos.logback.access.PatternLayout"> - <Pattern">combined</Pattern"> + <layout class="ch.qos.logback.access.PatternLayout"> + <Pattern">combined</Pattern"> </layout> </appender> - <appender-ref ref="FILE" /> + <appender-ref ref="FILE" /> </configuration></pre></div> <p> @@ -276,7 +282,8 @@ <p> An http-specific implementation of <code>PatternLayout</code> is - included in the access module. The <a href="xref/ch/qos/logback/access/PatternLayout.html"> + included in the access module. The <a + href="xref/ch/qos/logback/access/PatternLayout.html"> <code>ch.qos.logback.access.PatternLayout</code></a> provides a way to format the logging output that is just as easy and flexible as the <code>PatternLayout</code> found in logback @@ -310,9 +317,9 @@ to the <em>$TOMCAT_HOME/bin/catalina.sh</em> configuration file: </p> -<div class="source"><pre>CATALINA_OPTS="-Dcom.sun.management.jmxremote" -CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.ssl=false" -CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"</pre></div> +<div class="source"><pre>CATALINA_OPTS="-Dcom.sun.management.jmxremote" +CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.ssl=false" +CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"</pre></div> <p> Once started with these options, Tomcat's JMX compoenents can be accessed @@ -336,24 +343,24 @@ <em>$TOMCAT_HOME/bin/catalina.sh</em> configuration file: </p> -<div class="source"><pre><!-- at the beginning of the file --> -CATALINA_OPTS="-Dcom.sun.management.jmxremote" -CATALINA_OPTS="$CATALINA_OPTS -Djavax.management.builder.initial=mx4j.server.MX4JMBeanServerBuilder" +<div class="source"><pre><!-- at the beginning of the file --> +CATALINA_OPTS="-Dcom.sun.management.jmxremote" +CATALINA_OPTS="$CATALINA_OPTS -Djavax.management.builder.initial=mx4j.server.MX4JMBeanServerBuilder" -<!-- in the "Add on extra jar files to CLASSPATH" section --> -CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-impl.jar</pre></div> +<!-- in the "Add on extra jar files to CLASSPATH" section --> +CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-impl.jar</pre></div> <p> Finally, declare a new <code>Connector</code> in the <em>$TOMCAT_HOME/conf/server.xml</em> file: </p> -<div class="source"><pre><Connector port="8050" - handler.list="mx" - mx.enabled="true" - mx.httpHost="localhost" - mx.httpPort="8082" - protocol="AJP/1.3" /></pre></div> +<div class="source"><pre><Connector port="8050" + handler.list="mx" + mx.enabled="true" + mx.httpHost="localhost" + mx.httpPort="8082" + protocol="AJP/1.3" /></pre></div> <p> Once Tomcat is started, you should be ableo to reach the JMX components by @@ -370,19 +377,19 @@ added: </p> -<div class="source"><pre><Call id="MBeanServer" class="java.lang.management.ManagementFactory" name="getPlatformMBeanServer"/> -<!-- initialize the Jetty MBean container --> -<Get id="Container" name="container"> - <Call name="addEventListener"> - <Arg> - <New class="org.mortbay.management.MBeanContainer"> - <Arg><Ref id="MBeanServer"/></Arg> - <Set name="managementPort">8082</Set> - <Call name="start" /> - </New> - </Arg> - </Call> -</Get></pre></div> +<div class="source"><pre><Call id="MBeanServer" class="java.lang.management.ManagementFactory" name="getPlatformMBeanServer"/> +<!-- initialize the Jetty MBean container --> +<Get id="Container" name="container"> + <Call name="addEventListener"> + <Arg> + <New class="org.mortbay.management.MBeanContainer"> + <Arg><Ref id="MBeanServer"/></Arg> + <Set name="managementPort">8082</Set> + <Call name="start" /> + </New> + </Arg> + </Call> +</Get></pre></div> <p> Once Jetty is started with this configuration, all available components can be reviewed @@ -408,20 +415,20 @@ other filter: </p> -<div class="source"><pre><configuration> - <b><filter class="ch.qos.logback.access.filter.CountingFilter"> - <name>countingFilter</name> - </filter></b> - - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.access.PatternLayout"> - <Pattern>%h %l %u %t \"%r\" %s %b</Pattern> - </layout> - </appender> +<div class="source"><pre><configuration> + <b><filter class="ch.qos.logback.access.filter.CountingFilter"> + <name>countingFilter</name> + </filter></b> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.access.PatternLayout"> + <Pattern>%h %l %u %t \"%r\" %s %b</Pattern> + </layout> + </appender> - <appender-ref ref="STDOUT" /> -</configuration></pre></div> + <appender-ref ref="STDOUT" /> +</configuration></pre></div> <p> This component registers itself to the JMX server and publishes Modified: logback/trunk/logback-site/src/site/resources/bridge.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/bridge.html (original) +++ logback/trunk/logback-site/src/site/resources/bridge.html Mon Feb 5 14:28:49 2007 @@ -63,31 +63,29 @@ </li> </ul> - + <p> This is what it takes to make logback your logging implementation when using log4j. It will use logback's automatic basic configuration, displaying the logging requests in the console. More advanced use will require a configuration file and other jars which are logback dependencies. A file called <em>logback.xml</em>, placed in the application's classpath, will be automatically loaded by logback. - + </p> <h3>When does it not work?</h3> - + <p> The <em>log4-bridge</em> module does not work when the application calls log4j components that are not present in the bridge. For examples, direct creation of log4j <code>Appenders</code> or <code>Filters</code> will not work. - - + </p> + <p> However, in most situations, log4j finds its configuration file and configures itself. In these cases, the application will only issue calls to the classes that are contained in the <em>log4j-bridge</em>. - - - - + </p> + Modified: logback/trunk/logback-site/src/site/resources/bugreport.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/bugreport.html (original) +++ logback/trunk/logback-site/src/site/resources/bugreport.html Mon Feb 5 14:28:49 2007 @@ -22,7 +22,7 @@ - <h2>Before you report a bug</h2> +<h2>Before you report a bug</h2> <p> The logback community consists of those who use logback and its modules, @@ -66,9 +66,9 @@ </ul> <h2>Reporting with Bugzilla</h2> - +<p> Only after you have exhausted the aforementioned steps, should you file a formal report in bugzilla. - +</p> <p> Please make sure you provide as much information as possible. Its very hard to fix a bug if the person looking into the problem can't reproduce it. @@ -77,10 +77,6 @@ <li><a href="http://bugzilla.qos.ch/enter_bug.cgi">Report new logback bug</a></li> </ul> - - - - <script src="templates/footer.js"></script> </div> </body> Modified: logback/trunk/logback-site/src/site/resources/demo.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/demo.html (original) +++ logback/trunk/logback-site/src/site/resources/demo.html Mon Feb 5 14:28:49 2007 @@ -20,7 +20,7 @@ <div id="content"> - <h2>Logback Demo</h2> +<h2>Logback Demo</h2> <p> Welcome to the logback demo! This document will take you to a tour @@ -118,16 +118,16 @@ Let's take a look at the filter we've just added: </p> -<div class="source"><pre><filter class="ch.qos.logback.core.filter.EvaluatorFilter"> - <evaluator name="loggingTaskEval"> - <expression> - logger.getName().contains("LoggingTask") &amp;&amp; - message.contains("Howdydy-diddly-ho") &amp;&amp; - (timeStamp - event.getStartTime()) >= 20000 - </expression> - </evaluator> - <OnMatch>DENY</OnMatch> -</filter></pre></div> +<div class="source"><pre><filter class="ch.qos.logback.core.filter.EvaluatorFilter"> + <evaluator name="loggingTaskEval"> + <expression> + logger.getName().contains("LoggingTask") &amp;&amp; + message.contains("Howdydy-diddly-ho") &amp;&amp; + (timeStamp - event.getStartTime()) >= 20000 + </expression> + </evaluator> + <OnMatch>DENY</OnMatch> +</filter></pre></div> <p> The expression element contains a familiar java statement. This expression @@ -194,7 +194,7 @@ system. Usually, a logging request is issued like this: </p> -<div class="source"><pre>logger.debug("Hello, my name is" + username + ", I am " + age + " years old.");</pre></div> +<div class="source"><pre>logger.debug("Hello, my name is" + username + ", I am " + age + " years old.");</pre></div> <p> By issuing this line, the cost of constructing the String cannot be saved when the @@ -208,7 +208,7 @@ Logback offers the following method: </p> -<div class="source"><pre>logger.debug("Hello, my name is {}, I am {} years old", username, age);</pre></div> +<div class="source"><pre>logger.debug("Hello, my name is {}, I am {} years old", username, age);</pre></div> <p> As you can see, the variables are not inserted in the message yet. Both the message @@ -234,7 +234,7 @@ <p> The durations should be obviously different. Remember that we had turned off all logging in the previous step of this demo. With the initial formatting method, -we were constructing the logging message (<em>"Trying "+i+" as a factor."</em>) +we were constructing the logging message (<em>"Trying "+i+" as a factor."</em>) a huge amount of times, actually each time a factor was tried for these big numbers. With the paramatrized logging, the construction of the message was postponed and, since logging was turned off, not processed. We see here that the cost of the <b>non-</b>logging @@ -275,18 +275,18 @@ The necessary configuration is listed below: </p> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.access.PatternLayout"> - <Pattern>%h %l %u %t \"%r\" %s %b</Pattern> - </layout> - </appender> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.access.PatternLayout"> + <Pattern>%h %l %u %t \"%r\" %s %b</Pattern> + </layout> + </appender> - <appender-ref ref="STDOUT" /> + <appender-ref ref="STDOUT" /> -</configuration></pre></div> +</configuration></pre></div> <p> To see more clearly the output produced by logback access, @@ -337,27 +337,27 @@ The configuration lines that are necessary are listed below. </p> -<div class="source"><pre><appender name="STDOUT_LOTTERY" - class="ch.qos.logback.core.ConsoleAppender"> - <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> - <evaluator name="lotto_eval"> - <Expression> +<div class="source"><pre><appender name="STDOUT_LOTTERY" + class="ch.qos.logback.core.ConsoleAppender"> + <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> + <evaluator name="lotto_eval"> + <Expression> url.matches(event.getRequestURL().toString()) - </Expression> - <matcher name="url"> - <regex>Lottery.do</regex> - <caseSensitive>false</caseSensitive> - </matcher> - </evaluator> - <OnMatch>ACCEPT</OnMatch> - <OnMismatch>DENY</OnMismatch> - </filter> - <layout class="ch.qos.logback.access.PatternLayout"> - <Pattern> + </Expression> + <matcher name="url"> + <regex>Lottery.do</regex> + <caseSensitive>false</caseSensitive> + </matcher> + </evaluator> + <OnMatch>ACCEPT</OnMatch> + <OnMismatch>DENY</OnMismatch> + </filter> + <layout class="ch.qos.logback.access.PatternLayout"> + <Pattern> LOTTERY: %A [%r] Guess=%reqParameter{guessed_number} - </Pattern> - </layout> -</appender></pre></div> + </Pattern> + </layout> +</appender></pre></div> <p> This appender will use a <code>PatternLayout</code> to format its output. @@ -512,9 +512,7 @@ logback documentation page</a> for more information about any component you'd like to test. </p> - - - + Modified: logback/trunk/logback-site/src/site/resources/documentation.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/documentation.html (original) +++ logback/trunk/logback-site/src/site/resources/documentation.html Mon Feb 5 14:28:49 2007 @@ -19,7 +19,7 @@ </div> <div id="content"> - <h2>Logback documentation</h2> + <h2>Logback documentation</h2> <p>Below is a list of logback-related documentaiton currently available.</p> @@ -45,7 +45,7 @@ </li> </ul> - Source code related documentation: + <p>Source code related documentation:</p> <ul> <li> @@ -59,18 +59,13 @@ </li> </ul> - - Recently, Ceki G�lc� presented the top 10 reasons for migrating your projects to logback. + <p> + Recently, Ceki Gülcü presented the top 10 reasons for migrating your projects to logback. Issues such as migration strategy, new APIs, SLF4J and Joran were be discussed. Emphasis was given to practical aspects and a live demo rather than relatively theoretical considerations. If you were not able to attend the presentation (or even if you were there), you can <a href="10reasons.ppt">download the slides</a> that Ceki used. - - - - - - + </p> Modified: logback/trunk/logback-site/src/site/resources/download.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/download.html (original) +++ logback/trunk/logback-site/src/site/resources/download.html Mon Feb 5 14:28:49 2007 @@ -20,8 +20,7 @@ <div id="content"> - - <div class="section"> + <div class="section"> <h2>Download links</h2> </div> @@ -32,13 +31,13 @@ <ul> <p> - <a href="dist/logback-${project.version}.zip"> - logback-${project.version}.zip + <a href="dist/logback-${pom.version}.zip"> + logback-${pom.version}.zip </a> </p> <p> - <a href="dist/logback-${project.version}.tar.gz"> - logback-${project.version}.tar.gz + <a href="dist/logback-${pom.version}.tar.gz"> + logback-${pom.version}.tar.gz </a> </p> </ul> @@ -50,9 +49,6 @@ - - - <script src="templates/footer.js"></script> </div> </body> Modified: logback/trunk/logback-site/src/site/resources/index.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/index.html (original) +++ logback/trunk/logback-site/src/site/resources/index.html Mon Feb 5 14:28:49 2007 @@ -20,10 +20,10 @@ <div id="content"> - <h2>Logback Project</h2> + <h2>Logback Project</h2> <p> Logback is intended as a successor to the popular log4j - project. It was designed by Ceki G�lc�, the founder of the + project. It was designed by Ceki Gülcü, the founder of the log4j project. It builds upon exerience gained in building industrial-strength logging systems going back as far as 1999. </p> @@ -38,7 +38,8 @@ The logback-core module lays the groundwork for the other two modules. The logback-classic module can be assimilated to a significantly improved version of log4j. Moreover, - logback-classic natively implements the <a href="http://www.slf4j.org">SLF4J API</a> so that you can + logback-classic natively implements the <a + href="http://www.slf4j.org">SLF4J API</a> so that you can readily switch back and forth between logback and other logging systems such as log4j or JDK14 Logging. @@ -46,7 +47,7 @@ provide HTTP-access log functionality. Note that you can easily build your own modules on top of the Core module. </p> - + </div> Modified: logback/trunk/logback-site/src/site/resources/jmxConfig.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/jmxConfig.html (original) +++ logback/trunk/logback-site/src/site/resources/jmxConfig.html Mon Feb 5 14:28:49 2007 @@ -21,7 +21,7 @@ - <h2>JMX Configurator</h2> + <h2>JMX Configurator</h2> <p> As of version 0.8, logback ships with a component that allows @@ -42,9 +42,9 @@ to the <em>$TOMCAT_HOME/bin/catalina.sh</em> configuration file: </p> -<div class="source"><pre>CATALINA_OPTS="-Dcom.sun.management.jmxremote" -CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.ssl=false" -CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"</pre></div> +<div class="source"><pre>CATALINA_OPTS="-Dcom.sun.management.jmxremote" +CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.ssl=false" +CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"</pre></div> <p> Once started with these options, Tomcat's JMX compoenents can be accessed @@ -68,24 +68,24 @@ <em>$TOMCAT_HOME/bin/catalina.sh</em> configuration file: </p> -<div class="source"><pre><!-- at the beginning of the file --> -CATALINA_OPTS="-Dcom.sun.management.jmxremote" -CATALINA_OPTS="$CATALINA_OPTS -Djavax.management.builder.initial=mx4j.server.MX4JMBeanServerBuilder" +<div class="source"><pre><!-- at the beginning of the file --> +CATALINA_OPTS="-Dcom.sun.management.jmxremote" +CATALINA_OPTS="$CATALINA_OPTS -Djavax.management.builder.initial=mx4j.server.MX4JMBeanServerBuilder" -<!-- in the "Add on extra jar files to CLASSPATH" section --> -CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-impl.jar</pre></div> +<!-- in the "Add on extra jar files to CLASSPATH" section --> +CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-impl.jar</pre></div> <p> Finally, declare a new <code>Connector</code> in the <em>$TOMCAT_HOME/conf/server.xml</em> file: </p> -<div class="source"><pre><Connector port="8050" - handler.list="mx" - mx.enabled="true" - mx.httpHost="localhost" - mx.httpPort="8082" - protocol="AJP/1.3" /></pre></div> +<div class="source"><pre><Connector port="8050" + handler.list="mx" + mx.enabled="true" + mx.httpHost="localhost" + mx.httpPort="8082" + protocol="AJP/1.3" /></pre></div> <p> Once Tomcat is started, you should be ableo to reach the JMX components by @@ -102,19 +102,19 @@ added: </p> -<div class="source"><pre><Call id="MBeanServer" class="java.lang.management.ManagementFactory" name="getPlatformMBeanServer"/> -<!-- initialize the Jetty MBean container --> -<Get id="Container" name="container"> - <Call name="addEventListener"> - <Arg> - <New class="org.mortbay.management.MBeanContainer"> - <Arg><Ref id="MBeanServer"/></Arg> - <Set name="managementPort">8082</Set> - <Call name="start" /> - </New> - </Arg> - </Call> -</Get></pre></div> +<div class="source"><pre><Call id="MBeanServer" class="java.lang.management.ManagementFactory" name="getPlatformMBeanServer"/> +<!-- initialize the Jetty MBean container --> +<Get id="Container" name="container"> + <Call name="addEventListener"> + <Arg> + <New class="org.mortbay.management.MBeanContainer"> + <Arg><Ref id="MBeanServer"/></Arg> + <Set name="managementPort">8082</Set> + <Call name="start" /> + </New> + </Arg> + </Call> +</Get></pre></div> <p> Once Jetty is started with this configuration, all available components can be reviewed @@ -130,21 +130,21 @@ file. This is done by adding a single element, as shown below: </p> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <b><jmxConfigurator /></b> + <b><jmxConfigurator /></b> - <appender name="console" class="ch.qos.logback.classic.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%date [%thread] %-5level %logger{25} - %msg%n</Pattern> - </layout> - </appender> - - <root> - <level value="debug"/> - <appender-ref ref="console" /> - </root> -</configuration></pre></div> + <appender name="console" class="ch.qos.logback.classic.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%date [%thread] %-5level %logger{25} - %msg%n</Pattern> + </layout> + </appender> + + <root> + <level value="debug"/> + <appender-ref ref="console" /> + </root> +</configuration></pre></div> <p> Once the JMX Configurator is displayed on your screen, there are @@ -202,10 +202,6 @@ - - - - <script src="templates/footer.js"></script> </div> </body> Modified: logback/trunk/logback-site/src/site/resources/license.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/license.html (original) +++ logback/trunk/logback-site/src/site/resources/license.html Mon Feb 5 14:28:49 2007 @@ -19,8 +19,9 @@ </div> <div id="content"> - <h2>Logback License</h2> - + <div class="section"> + <h2>Logback License</h2> + </div> <p> Logback source code and binaries are distributed under the @@ -39,7 +40,8 @@ published by the Free Software Foundation.</pre></div> <p>Please note that logback is intended to be used behind the - SLF4J API, which is licensed under <a href="http://www.slf4j.org/license.html">an X11 type license</a>. + SLF4J API, which is licensed under <a + href="http://www.slf4j.org/license.html">an X11 type license</a>. </p> <p>If you wish to make a significant contribution to the logback @@ -48,10 +50,7 @@ formalize the terms of your contribution and to protect the project in case of litigation. </p> - - - - + Modified: logback/trunk/logback-site/src/site/resources/mailinglist.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/mailinglist.html (original) +++ logback/trunk/logback-site/src/site/resources/mailinglist.html Mon Feb 5 14:28:49 2007 @@ -21,7 +21,7 @@ - <h2>Project Mailing Lists</h2> + <h2>Project Mailing Lists</h2> <p> A mailing list is an electronic discussion forum that anyone @@ -35,23 +35,23 @@ </p> <h3>Respect the mailing list type</h3> <p> - The "User" lists where you can send questions and comments - about configuration, setup, usage and other "user" types of - questions. The "Developer" lists where you can send + The "User" lists where you can send questions and comments + about configuration, setup, usage and other "user" types of + questions. The "Developer" lists where you can send questions and comments about the actual software source code - and general "development" types of questions. + and general "development" types of questions. </p> <p> Some questions are appropriate for posting on both the - "user" and the "developer" lists. In this case, pick one and + "user" and the "developer" lists. In this case, pick one and only one. Do not cross post. </p> <p> Please do your best to ensure that you are not sending HTML - or "Stylelized" email to the list. If you are using Outlook + or "Stylelized" email to the list. If you are using Outlook or Outlook Express or Eudora, chances are that you are sending HTML email by default. There is usually a setting - that will allow you to send "Plain Text" email. + that will allow you to send "Plain Text" email. </p> @@ -67,23 +67,28 @@ <td>Logback Announce List</td> <td>Low</td> <td> - <a href="http://qos.ch/mailman/listinfo/logback-announce"> + <a + href="http://qos.ch/mailman/listinfo/logback-announce"> Subscribe </a> </td> <td> - <a href="http://qos.ch/mailman/options/logback-announce"> + <a + href="http://qos.ch/mailman/options/logback-announce"> Unsubscribe </a> </td> <td> - <a href="http://www.qos.ch/pipermail/logback-announce/"> + <a + href="http://www.qos.ch/pipermail/logback-announce/"> qos.ch </a> | - <a href="http://marc.theaimsgroup.com/?l=logback-announce"> + <a + href="http://marc.theaimsgroup.com/?l=logback-announce"> MARC </a> | - <a href="http://www.nabble.com/Logback-Announce-f16251.html"> + <a + href="http://www.nabble.com/Logback-Announce-f16251.html"> Nabble </a> </td> @@ -92,24 +97,29 @@ <td>Logback User List</td> <td>Medium</td> <td> - <a href="http://qos.ch/mailman/listinfo/logback-user"> + <a + href="http://qos.ch/mailman/listinfo/logback-user"> Subscribe </a> </td> <td> - <a href="http://qos.ch/mailman/options/logback-user"> + <a + href="http://qos.ch/mailman/options/logback-user"> Unsubscribe </a> </td> <td> - <a href="http://www.qos.ch/pipermail/logback-user/"> + <a + href="http://www.qos.ch/pipermail/logback-user/"> qos.ch </a> | - <a href="http://marc.theaimsgroup.com/?l=logback-user"> + <a + href="http://marc.theaimsgroup.com/?l=logback-user"> MARC </a> | - <a href="http://www.nabble.com/Logback-User-f16252.html"> + <a + href="http://www.nabble.com/Logback-User-f16252.html"> Nabble </a> </td> @@ -118,23 +128,28 @@ <td>Logback Dev List</td> <td>Medium</td> <td> - <a href="http://qos.ch/mailman/listinfo/logback-dev"> + <a + href="http://qos.ch/mailman/listinfo/logback-dev"> Subscribe </a> </td> <td> - <a href="http://qos.ch/mailman/options/logback-dev"> + <a + href="http://qos.ch/mailman/options/logback-dev"> Unsubscribe </a> </td> <td> - <a href="http://www.qos.ch/pipermail/logback-dev/"> + <a + href="http://www.qos.ch/pipermail/logback-dev/"> qos.ch </a> | - <a href="http://marc.theaimsgroup.com/?l=logback-dev"> + <a + href="http://marc.theaimsgroup.com/?l=logback-dev"> MARC </a> | - <a href="http://www.nabble.com/Logback-Dev-f16253.html"> + <a + href="http://www.nabble.com/Logback-Dev-f16253.html"> Nabble </a> </td> @@ -143,10 +158,9 @@ <h2>On IRC</h2> - <p>We can also be reached by IRC at <code><span class="big">irc.freenode.net#logback</span>.</code> + <p>We can also be reached by IRC at <code><span + class="big">irc.freenode.net#logback</span>.</code> </p> - - Modified: logback/trunk/logback-site/src/site/resources/manual/appenders.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/manual/appenders.html (original) +++ logback/trunk/logback-site/src/site/resources/manual/appenders.html Mon Feb 5 14:28:49 2007 @@ -20,30 +20,34 @@ <script src="../templates/right.js"></script> </div> <div id="content"> - <h2>Chapter 4: Appenders</h2> + <h2>Chapter 4: Appenders</h2> <div class="author"> - Authors: Ceki G�lc�, S�bastien Pennec + Authors: Ceki Gülcü, Sébastien Pennec </div> - <table class="bodyTable"> - <tr class="a"> - <td> - <a 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"></img> + <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>Copyright © 2000-2006, QOS.ch</p> <p> - + <!--Creative Commons License--> This work is licensed under a - <a href="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + <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> @@ -74,12 +78,12 @@ import ch.qos.logback.core.spi.LifeCycle; -public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachable { +public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachable { public String getName(); <b>void doAppend(E event);</b> - public void setLayout(Layout<E> layout); - public Layout<E> getLayout(); + public void setLayout(Layout<E> layout); + public Layout<E> getLayout(); public void setName(String name); }</pre></div> @@ -109,7 +113,7 @@ transmitting them over the wire. </p> - <a name="AppenderBase"></a> + <a name="AppenderBase"/> <h2>AppenderBase</h2> <p> @@ -126,8 +130,7 @@ presenting a bit of its actual source code. </p> -<div class="source"> - <pre>public synchronized void doAppend(E eventObject) { +<div class="source"><pre>public synchronized void doAppend(E eventObject) { // prevent re-entry. if (guard) { @@ -140,7 +143,7 @@ if (!this.started) { if (statusRepeatCount++ < ALLOWED_REPEATS) { addStatus(new WarnStatus( - "Attempted to append to non started appender [" + name + "].",this)); + "Attempted to append to non started appender [" + name + "].",this)); } return; } @@ -155,8 +158,7 @@ } finally { guard = false; } -}</pre> -</div> +}</pre></div> <p> This implementation of the <code>doAppend()</code> method is synchronized. @@ -227,7 +229,7 @@ contained in the core module are can be used by any module without any customization. </p> - <a name="WriterAppender"></a> + <a name="WriterAppender" /> <h3>WriterAppender</h3> <p> @@ -242,13 +244,13 @@ These options are described next. </p> - <table class="bodyTable"> - <tr class="b"> + <table> + <tr> <th>Option Name</th> <th>Type</th> <th>Description</th> </tr> - <tr class="a"> + <tr> <td><b><span class="option">Encoding</span></b></td> <td><code>String</code></td> <td> @@ -266,7 +268,7 @@ that the platform's default encoding is used. </td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">ImmediateFlush</span></b></td> <td><code>boolean</code></td> <td> @@ -307,18 +309,18 @@ public static void main(String[] args) throws Exception { LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); - WriterAppender<LoggingEvent> writerAppender = new WriterAppender<LoggingEvent>(); + WriterAppender<LoggingEvent> writerAppender = new WriterAppender<LoggingEvent>(); writerAppender.setContext(lc); - writerAppender.setLayout(new EchoLayout<LoggingEvent>()); + writerAppender.setLayout(new EchoLayout<LoggingEvent>()); - OutputStream os = new FileOutputStream("exitWoes1.log"); + OutputStream os = new FileOutputStream("exitWoes1.log"); writerAppender.setWriter(new OutputStreamWriter(os)); writerAppender.setImmediateFlush(false); writerAppender.start(); Logger logger = LoggerFactory.getLogger(ExitWoes1.class); - logger.debug("Hello world."); + logger.debug("Hello world."); } }</pre></div> @@ -349,10 +351,10 @@ the class diagram for <code>WriterAppender</code> and its subclasses. </p> - <img src="images/chapter4/fileAppenderUML.png" alt="A UML diagram showing FileAppender"></img> - - <a name="ConsoleAppender"></a> - <h3>ConsoleAppender</h3> + <img src="images/chapter4/fileAppenderUML.png" alt="A UML diagram showing FileAppender"/> + + <a name="ConsoleAppender" /> + <h3>ConsoleAppender</h3> <p> The <a href="../xref/ch/qos/logback/core/ConsoleAppender.html"> @@ -365,23 +367,23 @@ which buffers I/O operations but not character conversions. </p> - <table class="bodyTable"> - <tr class="a"> + <table> + <tr> <th>Option Name</th> <th>Type</th> <th>Description</th> </tr> - <tr class="b"> + <tr> <td><b><span class="option">Encoding</span></b></td> <td><code>String</code></td> <td>See <code>WriterAppender</code> options.</td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">ImmediateFlush</span></b></td> <td><code>boolean</code></td> <td>See <code>WriterAppender</code> options.</td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">Target</span></b></td> <td><code>String</code></td> <td> @@ -396,20 +398,20 @@ </p> <em>Example 4.2: ConsoleAppender configuration (logback-examples/src/main/java/chapter4/conf/logback-Console.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <b><appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg %n</Pattern> - </layout> - </appender></b> - - <root> - <level value="debug" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + <b><appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg %n</Pattern> + </layout> + </appender></b> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p> To run this example, just issue the following command, @@ -418,7 +420,7 @@ <div class="source"><pre>java chapter4.ConfigurationTester src/main/java/chapter4/conf/logback-Console.xml</pre></div> - <a name="FileAppender"></a> + <a name="FileAppender" /> <h3>FileAppender</h3> <p> @@ -436,25 +438,25 @@ a <code>BufferedWriter</code>. Options for <code>FileAppender</code> are summarized below. </p> - <table class="bodyTable"> - <tr class="a"> + <table> + <tr> <th>Option Name</th> <th>Type</th> <th>Description</th> </tr> - <tr class="b"> + <tr> <td><b><span class="option">Append</span></b></td> <td><code>boolean</code></td> <td>If true, events are appended at the end of an existing file. Otherwise, if <span class="option">Append</span> is false, any existing file is truncated. The <span class="option">Append</span> option is set to true by default.</td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">Encoding</span></b></td> <td><code>String</code></td> <td>See <code>WriterAppender</code> options.</td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">BufferedIO</span></b></td> <td><code>boolean</code></td> <td> @@ -470,16 +472,16 @@ CPU cycles in the process. </td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">BufferSize</span></b></td> <td><code>int</code></td> <td>Size of <code>BufferedWriter</code> buffer. The default value is 8192.</td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">File</span></b></td> <td><code>String</code></td> <td> - The name of the file to write to. If the file does not exist, it is created. <br></br> + The name of the file to write to. If the file does not exist, it is created. <br /> On the MS Windows platform users frequently forget to escape back slashes. For example, the value <em>c:\temp\test.log</em> is not likely to be interpreted properly as <em>'\t'</em> is an escape sequence interpreted as a single @@ -489,7 +491,7 @@ The <span class="option">File</span> option has no default value. </td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">ImmediateFlush</span></b></td> <td><code>boolean</code></td> <td> @@ -523,25 +525,25 @@ </p> <em>Example 4.3: FileAppender configuration (logback-examples/src/main/java/chapter4/conf/logback-fileAppender.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <b><appender name="FILE" class="ch.qos.logback.core.FileAppender"> - <File>testFile.log</File> - <Append>true</Append> - <Encoding>UTF-8</Encoding> - <BufferedIO>false</BufferedIO> - <ImmediateFlush>true</ImmediateFlush> - - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern> - </layout> - </appender></b> - - <root> - <level value="debug" /> - <appender-ref ref="FILE" /> - </root> -</configuration></pre></div> + <b><appender name="FILE" class="ch.qos.logback.core.FileAppender"> + <File>testFile.log</File> + <Append>true</Append> + <Encoding>UTF-8</Encoding> + <BufferedIO>false</BufferedIO> + <ImmediateFlush>true</ImmediateFlush> + + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern> + </layout> + </appender></b> + + <root> + <level value="debug" /> + <appender-ref ref="FILE" /> + </root> +</configuration></pre></div> <p> To run this example, use the provided <code>ConfigurationTester</code> by @@ -551,7 +553,7 @@ <div class="source"><pre>java chapter4.ConfigurationTester src/main/java/chapter4/conf/logback-fileAppender.xml</pre></div> - <a name="RollingFileAppender"></a> + <a name="RollingFileAppender" /> <h3>RollingFileAppender</h3> <p> @@ -580,43 +582,43 @@ <p>Here are the available options for <code>RollingFileAppender</code>:</p> - <table class="bodyTable"> - <tr class="b"> + <table> + <tr> <th>Option Name</th> <th>Type</th> <th>Description</th> </tr> - <tr class="a"> + <tr> <td><b><span class="option">Append</span></b></td> <td><code>boolean</code></td> <td>See <code>FileAppender</code> options.</td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">BufferedIO</span></b></td> <td><code>boolean</code></td> <td>See <code>FileAppender</code> options.</td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">BufferSize</span></b></td> <td><code>int</code></td> <td>See <code>FileAppender</code> options.</td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">Encoding</span></b></td> <td><code>String</code></td> <td>See <code>WriterAppender</code> options.</td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">File</span></b></td> <td><code>String</code></td> <td>See <code>FileAppender</code> options.</td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">ImmediateFlush</span></b></td> <td><code>boolean</code></td> <td>See <code>WriterAppender</code> options.</td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">RollingPolicy</span></b></td> <td><code>RollingPolicy</code></td> <td> @@ -625,7 +627,7 @@ occurs. See more information below. </td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">TriggeringPolicy</span></b></td> <td><code>TriggeringPolicy</code></td> <td> @@ -663,7 +665,7 @@ Lastly, a <code>RollingPolicy</code> knows about its parent. </p> - <a name="FixedWindowRollingPolicy"></a> + <a name="FixedWindowRollingPolicy" /> <h4>FixedWindowRollingPolicy</h4> <p> @@ -685,13 +687,13 @@ Here are the available options for <code>FixedWindowRollingPolicy</code> </p> - <table class="bodyTable"> - <tr class="a"> + <table> + <tr> <th>Option Name</th> <th>Type</th> <th>Description</th> </tr> - <tr class="b"> + <tr> <td><b><span class="option">FileNamePattern</span></b></td> <td><code>String</code></td> <td> @@ -717,7 +719,7 @@ </p> </td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">MaxIndex</span></b></td> <td><code>int</code></td> <td> @@ -726,7 +728,7 @@ </p> </td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">MinIndex</span></b></td> <td><code>int</code></td> <td> @@ -754,8 +756,8 @@ option is set to <em>foo.log</em>. </p> - <table class="bodyTable"> - <tr class="a"> + <table> + <tr> <th> Steps </th> @@ -767,7 +769,7 @@ </th> <th>Description</th> </tr> - <tr class="b"> + <tr> <td> 0 </td> @@ -782,7 +784,7 @@ into the initial file. </td> </tr> - <tr class="a"> + <tr> <td> 1 </td> @@ -797,7 +799,7 @@ a new <em>foo.log</em> file is created and used for the output. </td> </tr> - <tr class="b"> + <tr> <td> 2 </td> @@ -813,7 +815,7 @@ Again, a new <em>foo.log</em> file is created and used for the output. </td> </tr> - <tr class="a"> + <tr> <td> 3 </td> @@ -830,7 +832,7 @@ A new <em>foo.log</em> file is created and used for the output. </td> </tr> - <tr class="b"> + <tr> <td> 4 </td> @@ -857,30 +859,30 @@ <em>Example 4.4: Sample configuration of a <code>RollingFileAppender</code> using a <code>FixedWindowRollingPolicy</code> (logback-examples/src/main/java/chapter4/conf/logback-RollingFixedWindow.xml)</em> -<div class="source"><pre><configuration> - <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> - <File>testFile.log</File> - <b><rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"> - <FileNamePattern>testFile.%i.log.zip</FileNamePattern> - <MinIndex>1</MinIndex> - <MaxIndex>3</MaxIndex> - </rollingPolicy></b> - - <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"> - <MaxFileSize>5MB</MaxFileSize> - </triggeringPolicy> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern> - </layout> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="FILE" /> - </root> -</configuration></pre></div> +<div class="source"><pre><configuration> + <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> + <File>testFile.log</File> + <b><rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"> + <FileNamePattern>testFile.%i.log.zip</FileNamePattern> + <MinIndex>1</MinIndex> + <MaxIndex>3</MaxIndex> + </rollingPolicy></b> + + <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"> + <MaxFileSize>5MB</MaxFileSize> + </triggeringPolicy> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="FILE" /> + </root> +</configuration></pre></div> - <a name="TimeBasedRollingPolicy"></a> + <a name="TimeBasedRollingPolicy" /> <h4>TimeBasedRollingPolicy</h4> <p> <a href="../xref/ch/qos/logback/core/rolling/TimeBasedRollingPolicy.html"> @@ -906,15 +908,15 @@ of <em>yyyy-MM-dd</em> is assumed. The following examples should clarify the point. </p> - <table class="bodyTable"> - <tr class="a"> + <table> + <tr> <th> <span class="option">FileNamePattern</span> </th> <th>Roll-over schedule</th> <th>Example</th> </tr> - <tr class="b"> + <tr> <td> <em>/wombat/folder/foo.%d</em> </td> @@ -931,7 +933,7 @@ output will be directed to <em>/wombat/foo.2006-11-24</em>. </td> </tr> - <tr class="a"> + <tr> <td> <em>/wombat/foo.%d{yyyy-MM}.log</em> </td> @@ -944,7 +946,7 @@ <em>/wombat/foo.2006-11.log</em>. </td> </tr> - <tr class="b"> + <tr> <td> <em>/wombat/foo.%d{yyyy-ww}.log</em> </td> @@ -958,7 +960,7 @@ until it is rolled over at the beginning of the next week. </td> </tr> - <tr class="a"> + <tr> <td> <em>/wombat/foo.%d{yyyy-MM-dd-a}.log</em> </td> @@ -970,7 +972,7 @@ <em>/wombat/foo.2006-11-03-PM.log</em>. </td> </tr> - <tr class="b"> + <tr> <td> <em>/wombat/foo.%d{yyyy-MM-dd_HH}.log</em> </td> @@ -982,7 +984,7 @@ <em>/wombat/foo.2006-11-03_12.log</em>. </td> </tr> - <tr class="a"> + <tr> <td> <em>/wombat/foo.%d{yyyy-MM-dd_HH-mm}.log</em> </td> @@ -1001,13 +1003,13 @@ will be treated as quoted text. For instance, characters like <em>'.'</em>, <em>' '</em>, <em>'#'</em> and <em>'@'</em> will appear in the resulting time text even when they are not enclosed within single quotes. Nevertheless, we would recommend against - using the colon <em>":"</em> character anywhere within the + using the colon <em>":"</em> character anywhere within the <span class="option">FileNamePattern</span> option. The text before the colon is interpreted as the protocol specification of a - URL, which is most probably not what you intend. The slash <em>"/"</em> character, a + URL, which is most probably not what you intend. The slash <em>"/"</em> character, a common date field separator, must also be avoided. It is taken as a file separator causing the rollover operation to fail because the target file cannot - be created. Although less common, the backslash character <em>"\"</em> is equally troublesome. + be created. Although less common, the backslash character <em>"\"</em> is equally troublesome. </p> <p> @@ -1016,13 +1018,13 @@ This feature is enabled if the value of the <span class="option">FileNamePattern</span> option ends with <em>.gz</em> or <em>.zip</em>. </p> - <table class="bodyTable"> - <tr class="b"> + <table> + <tr> <th><span class="option">FileNamePattern</span></th> <th>Rollover schedule</th> <th>Example</th> </tr> - <tr class="a"> + <tr> <td><em>/wombat/foo.%d.gz</em></td> <td>Daily rollover (at midnight) with automatic GZIP compression of the arcived files.</td> @@ -1095,25 +1097,25 @@ <em>Example 4.5: Sample configuration of a <code>RollingFileAppender</code> using a <code>TimeBasedRollingPolicy</code> (logback-examples/src/main/java/chapter4/conf/logback-RollingTimeBased.xml)</em> -<div class="source"><pre><configuration> - <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> - <File>logFile.log</File> - <b><rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern>logFile.%d{yyyy-MM-dd}.log</FileNamePattern> - </rollingPolicy></b> - - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern> - </layout> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="FILE" /> - </root> -</configuration></pre></div> +<div class="source"><pre><configuration> + <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> + <File>logFile.log</File> + <b><rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> + <FileNamePattern>logFile.%d{yyyy-MM-dd}.log</FileNamePattern> + </rollingPolicy></b> + + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="FILE" /> + </root> +</configuration></pre></div> - <a name="TriggeringPolicy"></a> + <a name="TriggeringPolicy"/> <h3>Triggering policies</h3> <p><a href="../xref/ch/qos/logback/core/rolling/TriggeringPolicy.html"><code>TriggeringPolicy</code></a> @@ -1141,7 +1143,7 @@ returning a boolean value. </p> - <a name="SizeBasedTriggeringPolicy"></a> + <a name="SizeBasedTriggeringPolicy" /> <h4>SizeBasedTriggeringPolicy</h4> <p> @@ -1177,28 +1179,28 @@ <em>Example 4.6: Sample configuration of a <code>RollingFileAppender</code> using a <code>SizeBasedTriggeringPolicy</code> (logback-examples/src/main/java/chapter4/conf/logback-RollingSizeBased.xml)</em> -<div class="source"><pre><configuration> - <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> - <File>testFile.log</File> - <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"> - <FileNamePattern>testFile.%i.log.zip</FileNamePattern> - <MinIndex>1</MinIndex> - <MaxIndex>3</MaxIndex> - </rollingPolicy> - - <b><triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"> - <MaxFileSize>5MB</MaxFileSize> - </triggeringPolicy></b> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern> - </layout> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="FILE" /> - </root> -</configuration></pre></div> +<div class="source"><pre><configuration> + <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> + <File>testFile.log</File> + <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"> + <FileNamePattern>testFile.%i.log.zip</FileNamePattern> + <MinIndex>1</MinIndex> + <MaxIndex>3</MaxIndex> + </rollingPolicy> + + <b><triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"> + <MaxFileSize>5MB</MaxFileSize> + </triggeringPolicy></b> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="FILE" /> + </root> +</configuration></pre></div> <p> <code>TriggeringPolicy</code> implementations do not only serve with @@ -1216,14 +1218,14 @@ with a <code>Level</code> of <em>ERROR</em> or more is issued. </p> - <a name="Classic"></a> + <a name="Classic"/> <h2>Logback Classic</h2> <p>While logging event are declared as <code>Object</code> in logback core, they are instances of the <code>LoggingEvent</code> class in logback classic.</p> - <a name="SocketAppender"></a> + <a name="SocketAppender" /> <h3>SocketAppender</h3> <p> @@ -1285,13 +1287,13 @@ <code>SocketAppender</code> options are listed in the following table. </p> - <table class="bodyTable"> - <tr class="b"> + <table> + <tr> <th>Option Name</th> <th>Type</th> <th>Description</th> </tr> - <tr class="a"> + <tr> <td><b><span class="option">IncludeCallerData</span></b></td> <td><code>boolean</code></td> <td> @@ -1302,7 +1304,7 @@ </p> </td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">Port</span></b></td> <td><code>int</code></td> <td> @@ -1311,7 +1313,7 @@ </p> </td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">ReconnectionDelay</span></b></td> <td><code>int</code></td> <td> @@ -1324,7 +1326,7 @@ connector thread present. </td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">RemoteHost</span></b></td> <td><code>String</code></td> <td> @@ -1396,21 +1398,21 @@ </p> <em>Example 4.7: SocketAppender configuration (logback-examples/src/main/java/chapter4/socket/client1.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="SOCKET" class="ch.qos.logback.classic.net.SocketAppender"> - <RemoteHost>${host}</RemoteHost> - <Port>${port}</Port> - <ReconnectionDelay>10000</ReconnectionDelay> - <IncludeCallerData>${includeCallerData}</IncludeCallerData> - </appender> - - <root> - <level value ="debug"/> - <appender-ref ref="SOCKET" /> - </root> + <appender name="SOCKET" class="ch.qos.logback.classic.net.SocketAppender"> + <RemoteHost>${host}</RemoteHost> + <Port>${port}</Port> + <ReconnectionDelay>10000</ReconnectionDelay> + <IncludeCallerData>${includeCallerData}</IncludeCallerData> + </appender> + + <root> + <level value ="debug"/> + <appender-ref ref="SOCKET" /> + </root> -</configuration></pre></div> +</configuration></pre></div> <p> @@ -1472,7 +1474,7 @@ tunnels the events it receives from its clients to a second server. </p> - <a name="JMSAppenderBase"></a> + <a name="JMSAppenderBase" /> <h3>JMSAppenderBase</h3> <p> @@ -1515,13 +1517,13 @@ Here are <code>JMSAppenderBase</code>'s options: </p> - <table class="bodyTable"> - <tr class="a"> + <table> + <tr> <th>Option Name</th> <th>Type</th> <th>Description</th> </tr> - <tr class="b"> + <tr> <td><b><span class="option">InitialContextFactoryName</span></b></td> <td><code>String</code></td> <td> @@ -1537,7 +1539,7 @@ </p> </td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">ProviderURL</span></b></td> <td><code>String</code></td> <td> @@ -1553,7 +1555,7 @@ </p> </td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">URLPkgPrefixes</span></b></td> <td><code>String</code></td> <td> @@ -1575,7 +1577,7 @@ </p> </td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">SecurityPrincipalName</span></b></td> <td><code>String</code></td> <td> @@ -1590,7 +1592,7 @@ </p> </td> </tr> - <tr class="b"> + <tr> <td> <b> <span class="option">SecurityCredentials</span> @@ -1613,7 +1615,7 @@ </p> </td> </tr> - <tr class="a"> + <tr> <td> <b> <span class="option">UserName</span> @@ -1628,7 +1630,7 @@ </p> </td> </tr> - <tr class="b"> + <tr> <td> <b> <span class="option">Password</span> @@ -1673,8 +1675,8 @@ </p> <div class="source"><pre>Properties env = new Properties(); -env.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.activemq.jndi.ActiveMQInitialContextFactory"); -env.put(Context.PROVIDER_URL, "tcp://<em>hostname</em>:61616"); +env.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.activemq.jndi.ActiveMQInitialContextFactory"); +env.put(Context.PROVIDER_URL, "tcp://<em>hostname</em>:61616"); Context ctx = new InitialContext(env);</pre></div> <p> @@ -1726,7 +1728,7 @@ The JMS appenders do not implement the <code>ExceptionListener</code> interface. </p> - <a name="JMSTopicAppender"></a> + <a name="JMSTopicAppender" /> <h3>JMSTopicAppender</h3> <p> @@ -1752,10 +1754,10 @@ successiveFailureCount = 0; } catch (Exception e) { successiveFailureCount++; - if (successiveFailureCount > SUCCESSIVE_FAILURE_LIMIT) { + if (successiveFailureCount > SUCCESSIVE_FAILURE_LIMIT) { stop(); } - addError("Could not publish message in JMSTopicAppender [" + name + "].", e); + addError("Could not publish message in JMSTopicAppender [" + name + "].", e); } }</pre></div> @@ -1797,11 +1799,11 @@ Logger log = (Logger) LoggerFactory.getLogger(event.getLoggerRemoteView().getName()); log.callAppenders(event); } else { - logger.warn("Received message is of type " + message.getJMSType() - + ", was expecting ObjectMessage."); + logger.warn("Received message is of type " + message.getJMSType() + + ", was expecting ObjectMessage."); } } catch (JMSException jmse) { - logger.error("Exception thrown while processing incoming message.", jmse); + logger.error("Exception thrown while processing incoming message.", jmse); } }</pre></div> @@ -1818,13 +1820,13 @@ listed below. </p> - <table class="bodyTable"> - <tr class="a"> + <table> + <tr> <th>Option Name</th> <th>Type</th> <th>Description</th> </tr> - <tr class="b"> + <tr> <td><b><span class="option">TopicConnectionFactoryBindingName</span></b></td> <td><code>String</code></td> <td> @@ -1833,7 +1835,7 @@ </p> </td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">TopicBindingName</span></b></td> <td><code>String</code></td> <td> @@ -1849,27 +1851,27 @@ </p> <em>Example 4.8: JMSTopicAppender configuration (logback-examples/src/main/java/chapter4/conf/logback-JMSTopic.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="Topic" - class="ch.qos.logback.classic.net.JMSTopicAppender"> - <InitialContextFactoryName> + <appender name="Topic" + class="ch.qos.logback.classic.net.JMSTopicAppender"> + <InitialContextFactoryName> org.apache.activemq.jndi.ActiveMQInitialContextFactory - </InitialContextFactoryName> - <ProviderURL>tcp://localhost:61616</ProviderURL> - <TopicConnectionFactoryBindingName> + </InitialContextFactoryName> + <ProviderURL>tcp://localhost:61616</ProviderURL> + <TopicConnectionFactoryBindingName> ConnectionFactory - </TopicConnectionFactoryBindingName> - <TopicBindingName>MyTopic</TopicBindingName> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="Topic" /> - </root> -</configuration></pre></div> + </TopicConnectionFactoryBindingName> + <TopicBindingName>MyTopic</TopicBindingName> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="Topic" /> + </root> +</configuration></pre></div> - <a name="JMSQueueAppender"></a> + <a name="JMSQueueAppender" /> <h3>JMSQueueAppender</h3> <p> @@ -1887,13 +1889,13 @@ listed below. </p> - <table class="bodyTable"> - <tr class="b"> + <table> + <tr> <th>Option Name</th> <th>Type</th> <th>Description</th> </tr> - <tr class="a"> + <tr> <td><b><span class="option">QueueConnectionFactoryBindingName</span></b></td> <td><code>String</code></td> <td> @@ -1902,7 +1904,7 @@ </p> </td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">QueueBindingName</span></b></td> <td><code>String</code></td> <td> @@ -1918,27 +1920,27 @@ similar to that of a <code>JMSTopicAppender</code>. </p> <em>Example 4.9: JMSQueueAppender configuration (logback-examples/src/main/java/chapter4/conf/logback-JMSQueue.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="Queue" - class="ch.qos.logback.classic.net.JMSQueueAppender"> - <InitialContextFactoryName> + <appender name="Queue" + class="ch.qos.logback.classic.net.JMSQueueAppender"> + <InitialContextFactoryName> org.apache.activemq.jndi.ActiveMQInitialContextFactory - </InitialContextFactoryName> - <ProviderURL>tcp://localhost:61616</ProviderURL> - <QueueConnectionFactoryBindingName> + </InitialContextFactoryName> + <ProviderURL>tcp://localhost:61616</ProviderURL> + <QueueConnectionFactoryBindingName> ConnectionFactory - </QueueConnectionFactoryBindingName> - <QueueBindingName>MyQueue</QueueBindingName> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="Queue" /> - </root> -</configuration></pre></div> + </QueueConnectionFactoryBindingName> + <QueueBindingName>MyQueue</QueueBindingName> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="Queue" /> + </root> +</configuration></pre></div> - <a name="SMTPAppender"></a> + <a name="SMTPAppender"/> <h3>SMTPAppender</h3> <p> @@ -1953,20 +1955,20 @@ The various options for <code>SMTPAppender</code> are summarized in the following table. </p> - <table class="bodyTable"> - <tr class="a"> + <table> + <tr> <th>Option Name</th> <th>Type</th> <th>Description</th> </tr> - <tr class="b"> + <tr> <td><b><span class="option">SMTPHost</span></b></td> <td><code>String</code></td> <td> The host name of the SMTP server. This parameter is mandatory. </td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">To</span></b></td> <td><code>String</code></td> <td> @@ -1974,7 +1976,7 @@ be specified by using several <To> elements. </td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">From</span></b></td> <td><code>String</code></td> <td> @@ -1982,7 +1984,7 @@ <code>SMTPAppender</code>. </td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">Subject</span></b></td> <td><code>String</code></td> <td> @@ -2004,7 +2006,7 @@ </p> </td> </tr> - <tr class="b"> + <tr> <td><b><span class="option">BufferSize</span></b></td> <td><code>String</code></td> <td> @@ -2015,11 +2017,11 @@ The default size of the cyclic buffer is 512. </td> </tr> - <tr class="a"> + <tr> <td><b><span class="option">Evaluator</span></b></td> <td><code>String</code></td> <td> - <p>This option is declared by creating a new <code><EventEvaluator/></code> + <p>This option is declared by creating a new <code><EventEvaluator/></code> element. The name of the class that the user wishes to use as the <code>SMTPAppender</code>'s <code>Evaluator</code> can be given by adding an attribute to the newly created element. @@ -2068,22 +2070,22 @@ </p> <em>Example 4.10: A sample <code>SMTPAppender</code> configuration (logback-examples/src/main/java/chapter4/mail/mail1.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender"> - <SMTPHost>ADDRESS-OF-YOUR-SMTP-HOST</SMTPHost> - <To>DESTINATION-EMAIL</To> - <From>SENDER-EMAIL</From> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%date %-5level %logger{35} - %message%n</Pattern> - </layout> - </appender> - - <root> - <level value ="debug"/> - <appender-ref ref="EMAIL" /> - </root> -</configuration></pre></div> + <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender"> + <SMTPHost>ADDRESS-OF-YOUR-SMTP-HOST</SMTPHost> + <To>DESTINATION-EMAIL</To> + <From>SENDER-EMAIL</From> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%date %-5level %logger{35} - %message%n</Pattern> + </layout> + </appender> + + <root> + <level value ="debug"/> + <appender-ref ref="EMAIL" /> + </root> +</configuration></pre></div> <p> Before trying out <code>chapter4.mail.Email</code> application with the above @@ -2108,12 +2110,12 @@ </p> <div class="source"><pre> - <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender"> - <SMTPHost>${smtpHost}</SMTPHost> - <To>${to}</To> - <From>${from}</From> - <layout class="ch.qos.logback.classic.html.HTMLLayout"/> - </appender> + <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender"> + <SMTPHost>${smtpHost}</SMTPHost> + <To>${to}</To> + <From>${from}</From> + <layout class="ch.qos.logback.classic.html.HTMLLayout"/> + </appender> </pre></div> <p> @@ -2207,25 +2209,25 @@ <em>Example 4.12: <code>SMTPAppender</code> with custom <code>Evaluator</code> and buffer size (logback-examples/src/main/java/chapter4/mail/mail3.xml)</em> -<div class="source"><pre><configuration> - <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender"> - <b><Evaluator class="chapter4.mail.CounterBasedEvaluator" /></b> - <BufferSize>1050</BufferSize> - <SMTPHost>${smtpHost}</SMTPHost> - <To>${to}</To> - <From>${from}</From> - <layout class="ch.qos.logback.classic.html.HTMLLayout"/> - </appender> - - <root> - <level value ="debug"/> - <appender-ref ref="EMAIL" /> - </root> -</configuration></pre></div> +<div class="source"><pre><configuration> + <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender"> + <b><Evaluator class="chapter4.mail.CounterBasedEvaluator" /></b> + <BufferSize>1050</BufferSize> + <SMTPHost>${smtpHost}</SMTPHost> + <To>${to}</To> + <From>${from}</From> + <layout class="ch.qos.logback.classic.html.HTMLLayout"/> + </appender> + + <root> + <level value ="debug"/> + <appender-ref ref="EMAIL" /> + </root> +</configuration></pre></div> - <a name="DBAppender"></a> + <a name="DBAppender"/> <h3>DBAppender</h3> <p> @@ -2265,47 +2267,47 @@ <code>getGeneratedKeys()</code> method. </p> - <table class="bodyTable"> - <tr class="b"> + <table border="1" cellpadding="4"> + <tr> <th>RDBMS</th> <th> supports - <br></br> + <br /> <code>getGeneratedKeys()</code> method </th> <th> specific - <br></br> + <br /> SQLDialect support </th> </tr> - <tr class="a"> + <tr> <td>PostgreSQL</td> <td>NO</td> <td>present and used</td> </tr> - <tr class="b"> + <tr> <td>MySQL</td> <td>YES</td> <td>present, but not actually needed or used</td> </tr> - <tr class="a"> + <tr> <td>Oracle</td> <td>YES</td> <td>present, but not actually needed or used</td> </tr> - <tr class="b"> + <tr> <td>DB2</td> <td>YES</td> <td>not present, and not needed or used</td> </tr> - <tr class="a"> + <tr> <td>MsSQL</td> <td>YES</td> <td>not present, and not needed or used</td> </tr> - <tr class="b"> + <tr> <td>HSQL</td> <td>NO</td> <td>present and used</td> @@ -2315,7 +2317,7 @@ <p> Experiments show that writing a single event into the database takes approximately 10 milliseconds, on a - "standard" PC. If pooled connections are used, this figure + "standard" PC. If pooled connections are used, this figure drops to around 1 milliseconds. Note that most JDBC drivers already ship with connection pooling support. </p> @@ -2338,35 +2340,35 @@ <p> The <em>logging_event</em> table contains the following fields: </p> - <table class="bodyTable"> - <tr class="a"> + <table> + <tr> <th>Field</th> <th>Type</th> <th>Description</th> </tr> - <tr class="b"> + <tr> <td><b>timestmp</b></td> <td><code>big int</code></td> <td>The timestamp that was valid at the logging event's creation.</td> </tr> - <tr class="a"> + <tr> <td><b>formatted_message</b></td> <td><code>text</code></td> <td>The message that has been added to the logging event, after formatting with <code>org.slf4j.impl.MessageFormatter</code>, in case object were passed along with the message.</td> </tr> - <tr class="b"> + <tr> <td><b>logger_name</b></td> <td><code>varchar</code></td> <td>The name of the logger used to issue the logging request.</td> </tr> - <tr class="a"> + <tr> <td><b>level_string</b></td> <td><code>varchar</code></td> <td>The level of the logging event.</td> </tr> - <tr class="b"> + <tr> <td><b>reference_flag</b></td> <td><code>smallint</code></td> <td> @@ -2384,27 +2386,27 @@ </p> </td> </tr> - <tr class="a"> + <tr> <td><b>caller_filename</b></td> <td><code>varchar</code></td> <td>The name of the file where the logging request was issued.</td> </tr> - <tr class="b"> + <tr> <td><b>caller_class</b></td> <td><code>varchar</code></td> <td>The class where the logging request was issued.</td> </tr> - <tr class="a"> + <tr> <td><b>caller_method</b></td> <td><code>varchar</code></td> <td>The name of the method where the logging request was issued.</td> </tr> - <tr class="b"> + <tr> <td><b>caller_line</b></td> <td><code>char</code></td> <td>The line number where the logging request was issued.</td> </tr> - <tr class="a"> + <tr> <td><b>event_id</b></td> <td><code>int</code></td> <td>The database id of the logging event.</td> @@ -2417,23 +2419,23 @@ It contains these fields: </p> - <table class="bodyTable"> - <tr class="b"> + <table> + <tr> <th>Field</th> <th>Type</th> <th>Description</th> </tr> - <tr class="a"> + <tr> <td><b>event_id</b></td> <td><code>int</code></td> <td>The database id of the logging event.</td> </tr> - <tr class="b"> + <tr> <td><b>mapped_key</b></td> <td><code>varchar</code></td> <td>The key of the <code>MDC</code> property</td> </tr> - <tr class="a"> + <tr> <td><b>mapped_value</b></td> <td><code>text</code></td> <td>The value of the <code>MDC</code> property</td> @@ -2444,23 +2446,23 @@ The <em>logging_event_exception</em> table contains the following fields: </p> - <table class="bodyTable"> - <tr class="b"> + <table> + <tr> <th>Field</th> <th>Type</th> <th>Description</th> </tr> - <tr class="a"> + <tr> <td><b>event_id</b></td> <td><code>int</code></td> <td>The database id of the logging event.</td> </tr> - <tr class="b"> + <tr> <td><b>i</b></td> <td><code>smallint</code></td> <td>The index of the line in the full stack trace.</td> </tr> - <tr class="a"> + <tr> <td><b>trace_line</b></td> <td><code>varchar</code></td> <td>The corresponding line</td> @@ -2474,15 +2476,15 @@ <p>The <em>logging_event</em> table:</p> - <img src="images/chapter4/dbAppenderLE.gif" alt="Logging Event table"></img> + <img src="images/chapter4/dbAppenderLE.gif" alt="Logging Event table" /> <p>The <em>logging_event_exception</em> table:</p> - <img src="images/chapter4/dbAppenderLEException.gif" alt="Logging Event Exception table"></img> + <img src="images/chapter4/dbAppenderLEException.gif" alt="Logging Event Exception table" /> <p>The <em>logging_event_property</em> table:</p> - <img src="images/chapter4/dbAppenderLEProperty.gif" alt="Logging Event Property table"></img> + <img src="images/chapter4/dbAppenderLEProperty.gif" alt="Logging Event Property table" /> <h4>ConnectionSource</h4> @@ -2503,22 +2505,22 @@ </p> <em>Example 4.13: <code>DBAppender</code> configuration (logback-examples/src/main/java/chapter4/db/append-toMySQL-with-driverManager.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <b><appender name="DB" class="ch.qos.logback.classic.db.DBAppender"> - <connectionSource class="ch.qos.logback.core.db.DriverManagerConnectionSource"> - <driverClass>com.mysql.jdbc.Driver</driverClass> - <url>jdbc:mysql://host_name:3306/datebase_name</url> - <user>username</user> - <password>password</password> - </connectionSource> - </appender></b> + <b><appender name="DB" class="ch.qos.logback.classic.db.DBAppender"> + <connectionSource class="ch.qos.logback.core.db.DriverManagerConnectionSource"> + <driverClass>com.mysql.jdbc.Driver</driverClass> + <url>jdbc:mysql://host_name:3306/datebase_name</url> + <user>username</user> + <password>password</password> + </connectionSource> + </appender></b> - <root> - <level value="debug" /> - <appender-ref ref="DB" /> - </root> -</configuration></pre></div> + <root> + <level value="debug" /> + <appender-ref ref="DB" /> + </root> +</configuration></pre></div> <p> The correct driver must be declared. Here, the <code>com.mysql.jdbc.Driver</code> @@ -2543,7 +2545,33 @@ <code>javax.sql.DataSource</code>, e.g. within a J2EE application server, see <code>JNDIConnectionSource</code>). </p> +<!-- + + HAS TO BE TESTED + <p> + If you do not have another connection pooling mechanism built + into your application, you can use the + <a href="http://jakarta.apache.org/commons/dbcp/index.html"> + commons-dbcp </a> package from Apache: + </p> + +<div class="source"><pre> + <connectionSource + class="ch.qos.logback.core.db.DriverManagerConnectionSource"> + <param name="driver" value="org.apache.commons.dbcp.PoolingDriver"/> + <param name="url" value="jdbc:apache:commons:dbcp:/myPoolingDriver"/> + </connectionSource> +</pre></div> + + <p> + Then the configuration information for the commons-dbcp + package goes into the file <em>myPoolingDriver.jocl</em> and is + placed in the classpath. See the + <a href="http://jakarta.apache.org/commons/dbcp/index.html"> commons-dbcp </a> + documentation for details. + </p> + --> <p> Connecting to a database using a <code>DataSource</code> is rather similar. @@ -2556,31 +2584,31 @@ </p> <em>Example 4.14: <code>DBAppender</code> configuration (logback-examples/src/main/java/chapter4/db/append-with-datasource.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="DB" class="ch.qos.logback.classic.db.DBAppender"> - <b><connectionSource class="ch.qos.logback.core.db.DataSourceConnectionSource"> + <appender name="DB" class="ch.qos.logback.classic.db.DBAppender"> + <b><connectionSource class="ch.qos.logback.core.db.DataSourceConnectionSource"> - <dataSource class="${dataSourceClass}"> + <dataSource class="${dataSourceClass}"> </b><!-- Joran cannot substitute variables that are not attribute values. Therefore, we cannot declare the next parameter like the others. - --> - <b><param name="${url-key:-url}" value="${url_value}"/> - <serverName>${serverName}</serverName> - <databaseName>${databaseName}</databaseName> - </dataSource></b> + --> + <b><param name="${url-key:-url}" value="${url_value}"/> + <serverName>${serverName}</serverName> + <databaseName>${databaseName}</databaseName> + </dataSource></b> - <user>${user}</user> - <password>${password}</password> - </connectionSource> - </appender> - - <root> - <level value ="debug"/> - <appender-ref ref="DB" /> - </root> -</configuration></pre></div> + <user>${user}</user> + <password>${password}</password> + </connectionSource> + </appender> + + <root> + <level value ="debug"/> + <appender-ref ref="DB" /> + </root> +</configuration></pre></div> <p> Not that in this configuration sample, we make heavy use of substitution variables. @@ -2588,7 +2616,34 @@ single configuration file and shared by logback and other frameworks. </p> +<!-- TO BE TESTED + <p> + The connection created by <code>DataSourceConnectionSource</code> can be placed in a JNDI + context by using <code>BindDataSourceToJNDIAction</code>. In that case, one has to specify + the use of this class by adding a new rule to Joran, logback's configuration framework. Here + is an excerpt of such a configuration file. + </p> + +<div class="source"><pre><configuration> + .. + <b><newRule pattern="configuration/bindDataSourceToJNDI" + actionClass="ch.qos.logback.core.db.BindDataSourceToJNDIAction"/> + + <bindDataSourceToJNDI /></b> + .. +</configuration></pre></div> + <p> + The <em>newRule</em> element teaches Joran to use specified action class with the given pattern. + Then, we simply declare the given element. The action class will be called and our connection + source will be bound to a JNDI context. + </p> + <p> + This is a very powerfull possibility of Joran. If you'd like to read more about Joran, please + visit our <a href="../joran.html">introduction to Joran</a>. + </p> + + --> <p> The third implementation of <code>ConnectionSource</code> that is shipped with @@ -2641,24 +2696,24 @@ without any pooling. </p> <em>Example 4.15: <code>DBAppender</code> configuration without pooling (logback-examples/src/main/java/chapter4/db/append-toMySQL-with-datasource.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="DB" class="ch.qos.logback.classic.db.DBAppender"> - <connectionSource class="ch.qos.logback.core.db.DataSourceConnectionSource"> - <dataSource class="com.mysql.jdbc.jdbc2.optional.MysqlDataSource"> - <serverName>${serverName}</serverName> - <port>${port$</port> - <databaseName>${dbName}</databaseName> - <user>${user}</user> - <password>${pass}</password> - </dataSource> - </connectionSource> - </appender> + <appender name="DB" class="ch.qos.logback.classic.db.DBAppender"> + <connectionSource class="ch.qos.logback.core.db.DataSourceConnectionSource"> + <dataSource class="com.mysql.jdbc.jdbc2.optional.MysqlDataSource"> + <serverName>${serverName}</serverName> + <port>${port$</port> + <databaseName>${dbName}</databaseName> + <user>${user}</user> + <password>${pass}</password> + </dataSource> + </connectionSource> + </appender> - <root> - <level value="debug" /> - <appender-ref ref="DB" /> - </root> + <root> + <level value="debug" /> + <appender-ref ref="DB" /> + </root> </configuration</pre></div> <p> @@ -2677,26 +2732,26 @@ </p> <em>Example 4.16: <code>DBAppender</code> configuration with pooling (logback-examples/src/main/java/chapter4/db/append-toMySQL-with-datasource-and-pooling.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="DB" class="ch.qos.logback.classic.db.DBAppender"> + <appender name="DB" class="ch.qos.logback.classic.db.DBAppender"> <connectionSource - class="ch.qos.logback.core.db.DataSourceConnectionSource"> + class="ch.qos.logback.core.db.DataSourceConnectionSource"> <b><dataSource - class="com.mchange.v2.c3p0.ComboPooledDataSource"> - <driverClass>com.mysql.jdbc.Driver</driverClass> - <jdbcUrl>jdbc:mysql://${serverName}:${port}/${dbName}</jdbcUrl> - <user>${user}</user> - <password>${password}</password> - </dataSource></b> - </connectionSource> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="DB" /> - </root> -</configuration></pre></div> + class="com.mchange.v2.c3p0.ComboPooledDataSource"> + <driverClass>com.mysql.jdbc.Driver</driverClass> + <jdbcUrl>jdbc:mysql://${serverName}:${port}/${dbName}</jdbcUrl> + <user>${user}</user> + <password>${password}</password> + </dataSource></b> + </connectionSource> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="DB" /> + </root> +</configuration></pre></div> <p> With this new configuration, sending 500 logging requests to @@ -2705,7 +2760,7 @@ The gain is a <em>10</em> factor. </p> - <a name="SyslogAppender"></a> + <a name="SyslogAppender" /> <h3>SyslogAppender</h3> <p> @@ -2720,13 +2775,13 @@ Here are its options: </p> - <table class="bodyTable"> - <tr class="b"> + <table> + <tr> <th>Option Name</th> <th>Type</th> <th>Description</th> </tr> - <tr class="a"> + <tr> <td> <b> <span class="option">SyslogHost</span> @@ -2739,7 +2794,7 @@ The host name of the syslog server. </td> </tr> - <tr class="b"> + <tr> <td> <b> <span class="option">Port</span> @@ -2753,7 +2808,7 @@ to change the default value, that is <em>514</em>. </td> </tr> - <tr class="a"> + <tr> <td> <b> <span class="option">Facility</span> @@ -2775,7 +2830,7 @@ </p> </td> </tr> - <tr class="b"> + <tr> <td> <b> <span class="option">SuffixPattern</span> @@ -2814,20 +2869,20 @@ </p> <em>Example 4.17: <code>SyslogAppender</code> configuration (logback-examples/src/main/java/chapter4/conf/logback-syslog.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="SYSLOG" - class="ch.qos.logback.classic.net.SyslogAppender"> - <SyslogHost>remote_home</SyslogHost> - <Facility>AUTH</Facility> - <SuffixPattern>%-4relative [%thread] %-5level - %msg</SuffixPattern> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + <appender name="SYSLOG" + class="ch.qos.logback.classic.net.SyslogAppender"> + <SyslogHost>remote_home</SyslogHost> + <Facility>AUTH</Facility> + <SuffixPattern>%-4relative [%thread] %-5level - %msg</SuffixPattern> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p> When testing this configuration, one should verify that the remote syslog daemon @@ -2836,7 +2891,7 @@ </p> - <a name="Access"></a> + <a name="Access" /> <h2>Logback Access</h2> <p> @@ -2846,7 +2901,7 @@ focuse on the differences with the classic appenders. </p> - <a name="AccessSocketAppender"></a> + <a name="AccessSocketAppender"/> <h3>SocketAppender</h3> <p> @@ -2862,7 +2917,7 @@ for classic's <code>SocketAppender</code>. </p> - <a name="AccessSMTPAppender"></a> + <a name="AccessSMTPAppender"/> <h3>SMTPAppender</h3> <p> @@ -2879,20 +2934,20 @@ Here is a sample configuration of a <code>SMTPAppender</code> in the access environnement. </p> <em>Example 4.18: <code>SMTPAppender</code> configuration (logback-examples/src/main/java/chapter4/conf/access/logback-smtp.xml)</em> -<div class="source"><pre><appender name="SMTP" - class="ch.qos.logback.access.net.SMTPAppender"> - <layout class="ch.qos.logback.access.html.HTMLLayout"> - <Pattern>%h%l%u%t%r%s%b</Pattern> - </layout> +<div class="source"><pre><appender name="SMTP" + class="ch.qos.logback.access.net.SMTPAppender"> + <layout class="ch.qos.logback.access.html.HTMLLayout"> + <Pattern>%h%l%u%t%r%s%b</Pattern> + </layout> - <b><Evaluator class="ch.qos.logback.access.net.URLEvaluator"> - <URL>url1.jsp</URL> - <URL>directory/url2.html</URL> - </Evaluator></b> - <From>sender_email@host.com</From> - <SMTPHost>mail.domain.com</SMTPHost> - <To>recipient_email@host.com</To> -</appender></pre></div> + <b><Evaluator class="ch.qos.logback.access.net.URLEvaluator"> + <URL>url1.jsp</URL> + <URL>directory/url2.html</URL> + </Evaluator></b> + <From>sender_email@host.com</From> + <SMTPHost>mail.domain.com</SMTPHost> + <To>recipient_email@host.com</To> +</appender></pre></div> <p> This way of triggering the email lets user select pages that are important steps @@ -2904,7 +2959,7 @@ - <a name="AccessDBAppender"></a> + <a name="AccessDBAppender"/> <h3>DBAppender</h3> <p> @@ -2925,62 +2980,62 @@ <p>The <em>access_event</em> table's fields are described below:</p> - <table class="bodyTable"> - <tr class="a"> + <table> + <tr> <th>Field</th> <th>Type</th> <th>Description</th> </tr> - <tr class="b"> + <tr> <td><b>timestmp</b></td> <td><code>big int</code></td> <td>The timestamp that was valid at the access event's creation.</td> </tr> - <tr class="a"> + <tr> <td><b>requestURI</b></td> <td><code>varchar</code></td> <td>The URI that was requested.</td> </tr> - <tr class="b"> + <tr> <td><b>requestURL</b></td> <td><code>varchar</code></td> <td>The URL that was requested. This is a string composed of the request method, the request URI and the request protocol. </td> </tr> - <tr class="a"> + <tr> <td><b>remoteHost</b></td> <td><code>varchar</code></td> <td>The name of the remote host.</td> </tr> - <tr class="b"> + <tr> <td><b>remoteUser</b></td> <td><code>varchar</code></td> <td> The name of the remote user. </td> </tr> - <tr class="a"> + <tr> <td><b>remoteAddr</b></td> <td><code>varchar</code></td> <td>The remote IP address.</td> </tr> - <tr class="b"> + <tr> <td><b>protocol</b></td> <td><code>varchar</code></td> <td>The request protocol, like <em>HTTP</em> or <em>HTTPS</em>.</td> </tr> - <tr class="a"> + <tr> <td><b>method</b></td> <td><code>varchar</code></td> <td>The request method, usually <em>GET</em> or <em>POST</em>.</td> </tr> - <tr class="b"> + <tr> <td><b>serverName</b></td> <td><code>varchar</code></td> <td>The name of the server that issued the request.</td> </tr> - <tr class="a"> + <tr> <td><b>event_id</b></td> <td><code>int</code></td> <td>The database id of the access event.</td> @@ -2992,28 +3047,28 @@ requests. The information is organised as shown below: </p> - <table class="bodyTable"> - <tr class="b"> + <table> + <tr> <th>Field</th> <th>Type</th> <th>Description</th> </tr> - <tr class="a"> + <tr> <td><b>event_id</b></td> <td><code>int</code></td> <td>The database id of the corresponding access event.</td> </tr> - <tr class="b"> + <tr> <td><b>header_key</b></td> <td><code>varchar</code></td> <td>The header name, for example <em>User-Agent</em>.</td> </tr> - <tr class="a"> + <tr> <td><b>header_value</b></td> <td><code>varchar</code></td> <td>The header value, for example <em>Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.1) Gecko/20061010 Firefox/2.0</em></td> </tr> - </table> + </table> <p> All options of classic's <code>DBAppender</code> are available @@ -3021,13 +3076,13 @@ described below. </p> - <table class="bodyTable"> - <tr class="b"> + <table> + <tr> <th>Option Name</th> <th>Type</th> <th>Description</th> </tr> - <tr class="a"> + <tr> <td> <b> <span class="option">insertHeaders</span> @@ -3047,23 +3102,23 @@ Here is a sample configuration that uses <code>DBAppender</code>. </p> <em>Example 4.19: DBAppender configuration (logback-examples/src/main/java/chapter4/conf/access/logback-DB.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="DB" class="ch.qos.logback.access.db.DBAppender"> - <connectionSource class="ch.qos.logback.core.db.DriverManagerConnectionSource"> - <driverClass>com.mysql.jdbc.Driver</driverClass> - <url>jdbc:mysql://localhost:3306/logbackdb</url> - <user>logback</user> - <password>logback</password> - </connectionSource> - <insertHeaders>true</insertHeaders> - </appender> + <appender name="DB" class="ch.qos.logback.access.db.DBAppender"> + <connectionSource class="ch.qos.logback.core.db.DriverManagerConnectionSource"> + <driverClass>com.mysql.jdbc.Driver</driverClass> + <url>jdbc:mysql://localhost:3306/logbackdb</url> + <user>logback</user> + <password>logback</password> + </connectionSource> + <insertHeaders>true</insertHeaders> + </appender> - <appender-ref ref="DB" /> -</configuration></pre></div> + <appender-ref ref="DB" /> +</configuration></pre></div> - <a name="WriteYourOwnAppender"></a> + <a name="WriteYourOwnAppender" /> <h2>Writing your own Appender</h2> @@ -3086,12 +3141,12 @@ import ch.qos.logback.core.Layout; -public class CountingConsoleAppender extends AppenderBase<LoggingEvent> { +public class CountingConsoleAppender extends AppenderBase<LoggingEvent> { static int DEFAULT_LIMIT = 16; int counter = 0; int limit = DEFAULT_LIMIT; - private Layout<LoggingEvent> layout; + private Layout<LoggingEvent> layout; public CountingConsoleAppender() { } @@ -3107,7 +3162,7 @@ @Override public void start() { if (this.layout == null) { - addError("No layout set for the appender named ["+ name +"]."); + addError("No layout set for the appender named ["+ name +"]."); return; } @@ -3116,7 +3171,7 @@ public void append(LoggingEvent event) { - if (counter >= limit) { + if (counter >= limit) { return; } @@ -3127,11 +3182,11 @@ counter++; } - public Layout<LoggingEvent> getLayout() { + public Layout<LoggingEvent> getLayout() { return layout; } - public void setLayout(Layout<LoggingEvent> layout) { + public void setLayout(Layout<LoggingEvent> layout) { this.layout = layout; } }</pre></div> @@ -3159,11 +3214,11 @@ </li> </ul> - + <p> The <code>CountingConsoleAppender</code> can be configured like any appender. See sample file <em>logback-examples/src/main/java/chapter4/countingConsole.xml</em> for an example. - + </p> <script src="../templates/footer.js"></script> Modified: logback/trunk/logback-site/src/site/resources/manual/architecture.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/manual/architecture.html (original) +++ logback/trunk/logback-site/src/site/resources/manual/architecture.html Mon Feb 5 14:28:49 2007 @@ -16,801 +16,1232 @@ <div id="right"> <script src="../templates/right.js"></script> </div> -<div id="content"><br /> - <h2>Chapter 2: - Architecture</h2> - <div class="author">Authors: Ceki Gülcü, - Sébastien Pennec </div> - <table class="bodyTable"> - <tbody> - <tr class="a"> - <td><a href="http://creativecommons.org/licenses/by-nc-sa/2.5/"><img alt="Creative Commons License" style="border-width: 0pt;" src="http://creativecommons.org/images/public/somerights20.png" /> </a></td> - <td><p>Copyright © 2000-2006, QOS.ch</p> - <p>This work is licensed under a <a href="http://creativecommons.org/licenses/by-nc-sa/2.5/">Creative - Commons - Attribution-NonCommercial-ShareAlike 2.5 - License </a>. </p></td> - </tr> - </tbody> - </table> - <h2>Logback architecture</h2> - <p>Logback's basic architecture is sufficiently generic so as to - apply under different circumstances. At present time, logback is - divided into three modules, Core, Classic and Access. </p> - <p> The <em>core</em> module lays the groundwork for the other - two - modules. The <em>classic</em> module extends <em>core</em>. - The - classic module corresponds to a significantly improved - version of log4j. Logback-classic natively implements the <a href="http://www.slf4j.org">SLF4J API</a> so that you - can - readily switch back and forth between logback and other logging - systems such as log4j or JDK14 Logging. The third module called <em>access</em> integrates with Servlet containers to - provide - HTTP-access log functionality. The access module will be covered - in a <a href="../access.html">separate document</a>. </p> - <p>In the reminder of this document, we will write "logback" to - refer to the - logback classic module. </p> - <h2>Logger, Appenders and Layouts</h2> - <p>Logback has three main types: <code>Logger</code>, <code>Appender</code> and <code>Layout</code>. - These three types of components work - together to enable developers to log messages according to - message type and level, and to control at runtime how these - messages are formatted and where they are reported. </p> - <p> The Logger class is part of the classic module. On the other - hand, the <code>Appender</code> and <code>Layout</code> interfaces are part of the core module. For the sake of genericity, - logback-core has no notion of loggers. </p> - <a name="LoggerContext"></a> - <h3>Logger context</h3> - <p>The first and foremost advantage of any logging API over plain <code>System.out.println</code> resides in its ability to - disable - certain log statements while allowing others to print - unhindered. This capability assumes that the logging space, that - is, the space of all possible logging statements, is categorized - according to some developer-chosen criteria. In logback, this - categorization is an inherent part of loggers. </p> - <p> Loggers are named entities. Their names are case-sensitive and - they follow the hierarchical naming rule: </p> - <div class="definition"> - <div class="deftitle">Named Hierarchy</div> - <p>A logger is said to be an ancestor of another logger if - its name followed by a dot is a prefix of the descendant - logger name. A logger is said to be a parent of a child - logger if there are no ancestors between itself and the - descendant logger. </p> - </div> - <p>For example, the logger named <code>"com.foo"</code> is a parent of the logger named <code>"com.foo.Bar"</code>. - Similarly, <code>"java"</code> is a parent of <code>"java.util"</code> and an ancestor of <code>"java.util.Vector"</code>. This naming scheme should - be familiar to most developers. </p> - <p> The root logger resides at the top of the logger hierarchy. It - is exceptional in that it is part of every hierarchy at its - inception. Like every logger, it can be retrieved by its name, - as follows: </p> - <div class="source"> - <pre>Logger rootLogger = LoggerFactory.getLogger(<a href="../apidocs/constant-values.html#ch.qos.logback.classic.LoggerContext.ROOT_NAME">LoggerContext.<em>ROOT_NAME</em></a>);</pre> - </div> - <p>All other loggers are also retrieved with the class static <code>getLogger</code> method found in the <a href="http://www.slf4j.org/api/org/slf4j/Logger.html">org.slf4j.LoggerFactory</a> class. This method takes the name of the desired logger as a - parameter. Some of the basic methods in the <code>Logger</code> interface are listed below. </p> - <div class="source"> - <pre>package org.slf4j; public interface Logger {<br /> // Printing methods: public void debug(String message);<br /> public void info(String message); public void warn(String message); <br /> public void error(String message); public void fatal(String message); <br />}</pre> - </div> - <p>Loggers may be assigned levels. The set of possible levels, - that - is DEBUG, INFO, WARN and ERROR are defined in the <code>ch.qos.logback.classic.Level</code> class. Note that - in - logback, the level class is final and cannot be derived, as a - much more flexible approach exist in the form of Marker objects. </p> - <p> If a given logger is not assigned a level, then it inherits - one from its closest ancestor with an assigned level. More - formally: </p> - <div class="definition"> - <div class="deftitle">Level Inheritance</div> - <p>The effective level for a given logger <em>L</em>, - is equal to - the first non-null level in its hierarchy, starting at <em>L</em> itself and proceeding upwards in the hierarchy - towards the root logger. </p> - </div> - <p>To ensure that all loggers can eventually inherit a level, the - root logger always has an assigned level. By default, this level - is DEBUG. </p> - <p> Below are four examples with various assigned level values and - the resulting effective (inherited) levels according to the - level inheritance rule. </p> - <em>Example 1</em> - <table class="bodyTable"> - <tbody> - <tr class="b"> - <th>Logger name </th> - <th> Assigned level </th> - <th> Effective level </th> - </tr> - <tr class="a"> - <td>root</td> - <td>DEBUG</td> - <td>DEBUG</td> - </tr> - <tr class="b"> - <td>X</td> - <td>none</td> - <td>DEBUG</td> - </tr> - <tr class="a"> - <td>X.Y</td> - <td>none</td> - <td>DEBUG</td> - </tr> - <tr class="b"> - <td>X.Y.Z</td> - <td>none</td> - <td>DEBUG</td> - </tr> - </tbody> - </table> - <p> In example 1 above, only the root logger is assigned a level. - This level value, <code>DEBUG</code>, is inherited by the - other - loggers <code>X</code>, <code>X.Y</code> and <code>X.Y.Z</code> </p> - <em>Example 2</em> - <table class="bodyTable"> - <tbody> - <tr class="a"> - <th>Logger name </th> - <th> Assigned level </th> - <th> Effective level </th> - </tr> - <tr class="b"> - <td>root</td> - <td>ERROR</td> - <td>ERROR</td> - </tr> - <tr class="a"> - <td>X</td> - <td>INFO</td> - <td>INFO</td> - </tr> - <tr class="b"> - <td>X.Y</td> - <td>DEBUG</td> - <td>DEBUG</td> - </tr> - <tr class="a"> - <td>X.Y.Z</td> - <td>WARN</td> - <td>WARN</td> - </tr> - </tbody> - </table> - <p>In example 2 above, all loggers have an assigned level value. - Level inheritence does not come into play. </p> - <em>Example 3</em> - <table class="bodyTable"> - <tbody> - <tr class="b"> - <th>Logger name </th> - <th> Assigned level </th> - <th> Effective level </th> - </tr> - <tr class="a"> - <td>root</td> - <td>DEBUG</td> - <td>DEBUG</td> - </tr> - <tr class="b"> - <td>X</td> - <td>INFO</td> - <td>INFO</td> - </tr> - <tr class="a"> - <td>X.Y</td> - <td>none</td> - <td>INFO</td> - </tr> - <tr class="b"> - <td>X.Y.Z</td> - <td>ERROR</td> - <td>ERROR</td> - </tr> - </tbody> - </table> - <p>In example 3 above, the loggers <code>root</code>, <code>X</code> and <code>X.Y.Z</code> are assigned the levels <code>DEBUG</code>, <code>INFO</code> and <code>ERROR</code> respectively. Logger <code>X.Y</code> inherits its level value from its parent <code>X</code>. </p> - <em>Example 4</em> - <table class="bodyTable"> - <tbody> - <tr class="a"> - <th>Logger name </th> - <th> Assigned level </th> - <th> Effective level </th> - </tr> - <tr class="b"> - <td>root</td> - <td>DEBUG</td> - <td>DEBUG</td> - </tr> - <tr class="a"> - <td>X</td> - <td>INFO</td> - <td>INFO</td> - </tr> - <tr class="b"> - <td>X.Y</td> - <td>none</td> - <td>INFO</td> - </tr> - <tr class="a"> - <td>X.Y.Z</td> - <td>none</td> - <td>INFO</td> - </tr> - </tbody> - </table> - <p>In example 4 above, the loggers <code>root</code> and <code>X</code> and are assigned the levels <code>DEBUG</code> and <code>INFO</code> respectively. The loggers <code>X.Y</code> and <code>X.Y.Z</code> inherit their level value from their - nearest - parent <code>X</code>, which has an assigned level. </p> - <a name="PrintintMethods"></a> - <h3>Printing methods</h3> - <p>By definition, the printing method determines the level of a - logging request. For example, if <code>L</code> is a - logger - instance, then the statement <code>L.info("..")</code> is - a - logging statement of level INFO. </p> - <p>A logging request is said to be <em>enabled</em> if its level +<div id="content"> + <h2>Chapter 2: Architecture</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> + + + <h2>Logback architecture</h2> + + <p> + Logback's basic architecture is sufficiently generic so as to + apply under different circumstances. At present time, logback is + divided into three modules, Core, Classic and Access. + </p> + + <p> + The <em>core</em> module lays the groundwork for the other two + modules. The <em>classic</em> module extends <em>core</em>. The + classic module corresponds to a significantly improved + version of log4j. Logback-classic natively implements the <a + href="http://www.slf4j.org">SLF4J API</a> so that you can + readily switch back and forth between logback and other logging + systems such as log4j or JDK14 Logging. The third module called + <em>access</em> integrates with Servlet containers to provide + HTTP-access log functionality. The access module will be covered + in a <a href="../access.html">separate document</a>. + </p> + <p> + In the reminder of this document, we will write "logback" to refer to the + logback classic module. + </p> + + <h2>Logger, Appenders and Layouts</h2> + + <p> + Logback has three main types: <code>Logger</code>, + <code>Appender</code> and <code>Layout</code>. These three types of components work + together to enable developers to log messages according to + message type and level, and to control at runtime how these + messages are formatted and where they are reported. + </p> + <p> + The Logger class is part of the classic module. On the other + hand, the <code>Appender</code> and <code>Layout</code> interfaces + are part of the core module. For the sake of genericity, + logback-core has no notion of loggers. + </p> + + <a name="LoggerContext" /> + <h3>Logger context</h3> + + <p>The first and foremost advantage of any logging API over plain + <code>System.out.println</code> resides in its ability to disable + certain log statements while allowing others to print + unhindered. This capability assumes that the logging space, that + is, the space of all possible logging statements, is categorized + according to some developer-chosen criteria. In logback, this + categorization is an inherent part of loggers. + </p> + + <p> + Loggers are named entities. Their names are case-sensitive and + they follow the hierarchical naming rule: + </p> + <div class="definition"> + <div class="deftitle">Named Hierarchy</div> + <p> + A logger is said to be an ancestor of another logger if + its name followed by a dot is a prefix of the descendant + logger name. A logger is said to be a parent of a child + logger if there are no ancestors between itself and the + descendant logger. + </p> + </div> + + <p> + For example, the logger named <code>"com.foo"</code> + is a parent of the logger named <code>"com.foo.Bar"</code>. + Similarly, <code>"java"</code> + is a parent of <code>"java.util"</code> and an ancestor of + <code>"java.util.Vector"</code>. + This naming scheme should be familiar to most developers. + </p> + <p> + The root logger resides at the top of the logger hierarchy. It + is exceptional in that it is part of every hierarchy at its + inception. Like every logger, it can be retrieved by its name, + as follows: + </p> + <div class="source"><pre>Logger rootLogger = LoggerFactory.getLogger(<a href="../apidocs/constant-values.html#ch.qos.logback.classic.LoggerContext.ROOT_NAME">LoggerContext.<em>ROOT_NAME</em></a>);</pre></div> + + <p> + All other loggers are also retrieved with the class static + <code>getLogger</code> method found in the <a + href="http://www.slf4j.org/api/org/slf4j/Logger.html">org.slf4j.LoggerFactory</a> + class. This method takes the name of the desired logger as a + parameter. Some of the basic methods in the <code>Logger</code> + interface are listed below. + </p> + + <div class="source"><pre>package org.slf4j; +public interface Logger { + + // Printing methods: + public void debug(String message); + public void info(String message); + public void warn(String message); + public void error(String message); + public void fatal(String message); +}</pre></div> + + <p> + Loggers may be assigned levels. The set of possible levels, that + is DEBUG, INFO, WARN and ERROR are defined in the + <code>ch.qos.logback.classic.Level</code> class. Note that in + logback, the level class is final and cannot be derived, as a + much more flexible approach exist in the form of Marker objects. + </p> + + <p> + If a given logger is not assigned a level, then it inherits + one from its closest ancestor with an assigned level. More + formally: + </p> + + <div class="definition"> + <div class="deftitle">Level Inheritance</div> + <p> + The effective level for a given logger <em>L</em>, is equal to + the first non-null level in its hierarchy, starting at + <em>L</em> itself and proceeding upwards in the hierarchy + towards the root logger. + </p> + </div> + + <p> + To ensure that all loggers can eventually inherit a level, the + root logger always has an assigned level. By default, this level + is DEBUG. + </p> + <p> + Below are four examples with various assigned level values and + the resulting effective (inherited) levels according to the + level inheritance rule. + </p> + + <em>Example 1</em> + <table> + <tr> + <th> + Logger name + </th> + <th> + Assigned level + </th> + + <th> + Effective level + </th> + </tr> + <tr> + <td>root</td> + <td>DEBUG</td> + <td>DEBUG</td> + </tr> + <tr> + <td>X</td> + <td>none</td> + <td>DEBUG</td> + </tr> + + <tr> + <td>X.Y</td> + <td>none</td> + <td>DEBUG</td> + </tr> + <tr> + <td>X.Y.Z</td> + <td>none</td> + <td>DEBUG</td> + </tr> + </table> + + <p> In example 1 above, only the root logger is assigned a level. + This level value, <code>DEBUG</code>, is inherited by the other + loggers <code>X</code>, <code>X.Y</code> and <code>X.Y.Z</code> + </p> + + <em>Example 2</em> + <table> + <tr> + <th> + Logger name + </th> + <th> + Assigned level + </th> + + <th> + Effective level + </th> + </tr> + <tr align="left"> + <td>root</td> + <td>ERROR</td> + <td>ERROR</td> + </tr> + <tr align="left"> + <td>X</td> + <td>INFO</td> + <td>INFO</td> + </tr> + + <tr align="left"> + <td>X.Y</td> + <td>DEBUG</td> + <td>DEBUG</td> + </tr> + <tr align="left"> + <td>X.Y.Z</td> + <td>WARN</td> + <td>WARN</td> + </tr> + </table> + + <p>In example 2 above, all loggers have an assigned level value. + Level inheritence does not come into play. + </p> + + <em>Example 3</em> + <table> + <tr> + <th> + Logger name + </th> + <th> + Assigned level + </th> + <th> + Effective level + </th> + </tr> + <tr align="left"> + <td>root</td> + <td>DEBUG</td> + <td>DEBUG</td> + </tr> + + <tr align="left"> + <td>X</td> + <td>INFO</td> + <td>INFO</td> + </tr> + <tr align="left"> + <td>X.Y</td> + <td>none</td> + <td>INFO</td> + </tr> + <tr align="left"> + <td>X.Y.Z</td> + <td>ERROR</td> + <td>ERROR</td> + </tr> + </table> + <p> + In example 3 above, the loggers <code>root</code>, <code>X</code> + and <code>X.Y.Z</code> are assigned the levels <code>DEBUG</code>, + <code>INFO</code> and <code>ERROR</code> + respectively. Logger <code>X.Y</code> + inherits its level value from its parent <code>X</code>. + </p> + <em>Example 4</em> + <table> + + <tr> + <th> + Logger name + </th> + <th> + Assigned level + </th> + <th> + Effective level + </th> + </tr> + <tr align="left"> + <td>root</td> + <td>DEBUG</td> + <td>DEBUG</td> + </tr> + + <tr align="left"> + <td>X</td> + <td>INFO</td> + <td>INFO</td> + </tr> + <tr align="left"> + <td>X.Y</td> + <td>none</td> + <td>INFO</td> + </tr> + <tr align="left"> + <td>X.Y.Z</td> + <td>none</td> + <td>INFO</td> + </tr> + </table> + + + <p>In example 4 above, the loggers <code>root</code> and + <code>X</code> and are assigned the levels <code>DEBUG</code> and + <code>INFO</code> respectively. The loggers <code>X.Y</code> and + <code>X.Y.Z</code> inherit their level value from their nearest + parent <code>X</code>, which has an assigned level. + </p> + + <a name="PrintintMethods" /> + <h3>Printing methods</h3> + + <p>By definition, the printing method determines the level of a + logging request. For example, if <code>L</code> is a logger + instance, then the statement <code>L.info("..")</code> is a + logging statement of level INFO. + </p> + + <p>A logging request is said to be <em>enabled</em> if its level is higher than or equal to the level of its logger. Otherwise, the - request is said to be <em>disabled</em>. A logger without - an + request is said to be <em>disabled</em>. A logger without an assigned level will inherit one from the context. This rule is - summarized below. </p> - <div class="definition"> - <div class="deftitle">Basic Selection Rule</div> - <p>A log request of level <em>p</em> in a logger - with an - effective level <em>q</em>, is enabled if <em>p - >= q</em>. </p> - </div> - <p>This rule is at the heart of logback. It assumes - that levels are ordered as follows: <code>DEBUG < INFO - < WARN < ERROR< OFF</code>. </p> - <p>In a more graphic way, here is how the selection - rule works. In - the following table, the vertical header shows the the level of - the logging request, designated by <em>p</em>, while the - horizontal header shows effective level of the logger, designated - by <em>q</em>. </p> - <table class="bodyTable"> - <tbody> - <tr class="b"> - <th><span style=""><em>p</em>/<em>q</em></span></th> - <th>DEBUG</th> - <th>INFO</th> - <th>WARN</th> - <th>ERROR</th> - <th>OFF</th> - </tr> - <tr class="a"> - <th>DEBUG</th> - <td><span class="greenBold">YES</span></td> - <td><span class="redBold">NO</span></td> - <td><span class="redBold">NO</span></td> - <td><span class="redBold">NO</span></td> - <td><span class="redBold">NO</span></td> - </tr> - <tr class="b"> - <th>INFO</th> - <td><span class="greenBold">YES</span></td> - <td><span class="greenBold">YES</span></td> + summarized below. + </p> + + <div class="definition"> + <div class="deftitle">Basic Selection Rule</div> + + <p>A log request of level <em>p</em> in a logger with an + effective level <em>q</em>, is enabled if <em>p >= q</em>. + </p> + </div> + + <p> + This rule is at the heart of logback. It assumes + that levels are ordered as follows: + <code>DEBUG < INFO < WARN < ERROR< OFF</code>. + </p> + + <p>In a more graphic way, here is how the selection rule works. In + the following table, the vertical header shows the the level of + the logging request, designated by <em>p</em>, while the + horizontal header shows effective level of the logger, designated + by <em>q</em>. + </p> + + <table> + <tr> + <th><span style="align:center"><em>p</em>/<em>q</em></span></th> + <th>DEBUG</th> + <th>INFO</th> + <th>WARN</th> + <th>ERROR</th> + <th>OFF</th> + </tr> + <tr> + <th>DEBUG</th> + <td><span class="greenBold">YES</span></td> + <td><span class="redBold">NO</span></td> + <td><span class="redBold">NO</span></td> + <td><span class="redBold">NO</span></td> <td><span class="redBold">NO</span></td> + </tr> + <tr> + <th>INFO</th> + <td><span class="greenBold">YES</span></td> + <td><span class="greenBold">YES</span></td> + <td><span class="redBold">NO</span></td> + <td><span class="redBold">NO</span></td> <td><span class="redBold">NO</span></td> + </tr> + <tr> + <th>WARN</th> + <td><span class="greenBold">YES</span></td> + <td><span class="greenBold">YES</span></td> + <td><span class="greenBold">YES</span></td> + <td><span class="redBold">NO</span></td> <td><span class="redBold">NO</span></td> - </tr> - <tr class="a"> - <th>WARN</th> - <td><span class="greenBold">YES</span></td> - <td><span class="greenBold">YES</span></td> - <td><span class="greenBold">YES</span></td> + </tr> + <tr> + <th>ERROR</th> + <td><span class="greenBold">YES</span></td> + <td><span class="greenBold">YES</span></td> + <td><span class="greenBold">YES</span></td> + <td><span class="greenBold">YES</span></td> <td><span class="redBold">NO</span></td> - <td><span class="redBold">NO</span></td> - </tr> - <tr class="b"> - <th>ERROR</th> - <td><span class="greenBold">YES</span></td> - <td><span class="greenBold">YES</span></td> - <td><span class="greenBold">YES</span></td> - <td><span class="greenBold">YES</span></td> - <td><span class="redBold">NO</span></td> - </tr> - </tbody> - </table> - <p>Here is an example of - the basic selection rule.</p> - <div class="source"> - <pre>// get a logger instance named "com.foo", with an <span class="blue">INFO</span> level. <br />Logger logger = LoggerFactory.getLogger("com.foo");<br />//set its Level to <span class="blue">INFO</span><br />logger.setLevel(Level. <span class="blue">INFO</span>);<br />Logger barlogger = LoggerFactory.getLogger("com.foo.Bar");<br />// This request is enabled, because <span class="green bold">WARN</span> >= <span class="blue">INFO</span><br />logger.<span class="green bold">warn</span>("Low fuel level.");<br />// This request is disabled, because <span class="green bold">DEBUG</span> < <span class="blue">INFO</span>. <br />logger.<span class="green bold">debug</span>("Starting search for nearest gas station.");<br />// The logger instance barlogger, named "com.foo.Bar", <br />// will inherit its level from the logger named <br />// "com.foo" Thus, the following request is enabled // because <span class="green bold">INFO</span> >= <span class="blue">INFO</span>. <br />barlogger.<span class="green bold">info</span>("Located nearest gas station.");<br />// This request is disabled, because <span class="green bold">DEBUG</span> < <span class="blue">INFO</span>. <br />barlogger.<span class="green bold">debug</span>("Exiting gas station search");</pre> - </div> - <a name="RetrievingLoggers"></a> - <h3>Retrieving Loggers</h3> - <p>Calling the <code><a href="../apidocs/org/slf4j/LoggerFactory.html#getLogger%28java.lang.String%29">LoggerFactory.getLogger</a></code> method with the same name will always return a reference to - the exact same logger object. </p> - <p>For example, in</p> - <div class="source"> - <pre>Logger x = LoggerFactory.getLogger("wombat"); <br />Logger y = LoggerFactory.getLogger("wombat");</pre> - </div> - <p> <code>x</code> and <code>y</code> refer to <em>exactly</em> the same logger object. </p> - <p> Thus, it is possible to configure a logger and then to - retrieve the same instance somewhere else in the code - without passing around references. In fundamental - contradiction to biological parenthood, where parents always - preceed their children, logback loggers can be - created and configured in any order. In particular, a - "parent" logger will find and link to its descendants even - if it is instantiated after them. </p> - <p> Configuration of the logback environment is typically done - at application initialization. The preferred way is by - reading a configuration file. This approach will be - discussed shortly. </p> - <p> Logback makes it easy to name loggers by <em>software - component</em>. This can be accomplished by instantiating a - logger in each class, with the logger name equal to the fully - qualified name of the class. This is a useful and - straightforward method of defining loggers. As the log output - bears the name of the generating logger, this naming strategy - makes it easy to identify the origin of a log message. However, - this is only one possible, albeit common, strategy for naming - loggers. Logback does not restrict the possible set of - loggers. As a developer, you are free to name loggers as you - wish. </p> - <p>Nevertheless, naming loggers after the class where - they are - located seems to be the best general strategy known so far. </p> - <a name="AppendersAndLayouts"></a> - <h3>Appenders and Layouts</h3> - <p>The ability to selectively enable or disable logging requests - based on their logger is only part of the picture. Logback - allows logging requests to print to multiple destinations. In - logback speak, an output destination is called an - appender. Currently, appenders exist for the console, files, - remote socket servers, to MySQL, PostgreSQL, Oracle and other - databases, JMS, and remote UNIX Syslog daemons. </p> - <p>More than one appender can be attached to a logger.</p> - <p> The <code><a href="../apidocs/ch/qos/logback/classic/Logger.html#addAppender%28ch.qos.logback.core.Appender%29">addAppender</a></code> method adds an appender to a - given logger. Each enabled logging request for a given logger - will be forwarded to all the appenders in that logger as well as - the appenders higher in the hierarchy. In other words, appenders are - inherited additively from the logger hierarchy. For example, if a - console appender is added to the root logger, then all enabled - logging requests will at least print on the console. If in - addition a file appender is added to a logger, say <em>L</em>, - then enabled logging requests for <em>L</em> and <em>L</em>'s - children will print on a file <em>and</em> on the console. - It is - possible to override this default behavior so that appender - accumulation is no longer additive by setting the additivity flag - of a logger to false. </p> - <p> The rules governing appender additivity are summarized - below. </p> - <div class="definition"> - <div class="deftitle">Appender Additivity</div> - <p>The output of a log statement of logger <em>L</em> will go to all the appenders in <em>L</em> and its ancestors. This is the meaning of the term - "appender additivity". </p> - <p> However, if an ancestor of logger <em>L</em>, say <em>P</em>, has the additivity flag set to false, then <em>L</em>'s output will be directed to all the appenders - in <em>L</em> and it's ancestors upto and including <em>P</em> but not the appenders in any of the ancestors of <em>P</em>. </p> - <p> Loggers have their additivity flag set to true by - default. </p> - </div> - The table below shows an example: - <table class="bodyTable"> - <tbody> - <tr class="a"> - <th>Logger Name</th> - <th>Attached Appenders</th> - <th>Additivity Flag</th> - <th>Output Targets</th> - <th>Comment</th> - </tr> - <tr class="b"> - <td>root</td> - <td>A1</td> - <td>not applicable</td> - <td>A1</td> - <td>Since the root logger stands at the top of the logger - hiearchy, the additivity flag does not apply to it. </td> - </tr> - <tr class="a"> - <td>x</td> - <td>A-x1, A-x2</td> - <td>true</td> - <td>A1, A-x1, A-x2</td> - <td>Appenders of "x" and of root.</td> - </tr> - <tr class="b"> - <td>x.y</td> - <td>none</td> - <td>true</td> - <td>A1, A-x1, A-x2</td> - <td>Appenders of "x" and of root.</td> - </tr> - <tr class="a"> - <td>x.y.z</td> - <td>A-xyz1</td> - <td>true</td> - <td>A1, A-x1, A-x2, A-xyz1</td> - <td>Appenders of "x.y.z", "x" and of root.</td> - </tr> - <tr class="b"> - <td>security</td> - <td>A-sec</td> - <td><span class="blue">false</span></td> + </tr> + </table> + + <p>Here is an example of the basic selection rule.</p> + + <div class="source"><pre>// get a logger instance named "com.foo", with an <span class="blue">INFO</span> level. +Logger logger = LoggerFactory.getLogger("com.foo"); +//set its Level to <span class="blue">INFO</span> +logger.setLevel(Level. <span class="blue">INFO</span>); +Logger barlogger = LoggerFactory.getLogger("com.foo.Bar"); + +// This request is enabled, because <span class="green bold">WARN</span> >= <span class="blue">INFO</span> +logger.<span class="green bold">warn</span>("Low fuel level."); + +// This request is disabled, because <span class="green bold">DEBUG</span> < <span class="blue">INFO</span>. +logger.<span class="green bold">debug</span>("Starting search for nearest gas station."); + +// The logger instance barlogger, named "com.foo.Bar", +// will inherit its level from the logger named +// "com.foo" Thus, the following request is enabled +// because <span class="green bold">INFO</span> >= <span class="blue">INFO</span>. +barlogger.<span class="green bold">info</span>("Located nearest gas station."); + +// This request is disabled, because <span class="green bold">DEBUG</span> < <span class="blue">INFO</span>. +barlogger.<span class="green bold">debug</span>("Exiting gas station search");</pre></div> + + <a name="RetrievingLoggers" /> + <h3>Retrieving Loggers</h3> + <p> + Calling the <code><a href="../apidocs/org/slf4j/LoggerFactory.html#getLogger(java.lang.String)">LoggerFactory.getLogger</a></code> + method with the same name will always return a reference to + the exact same logger object. + </p> + + <p>For example, in</p> + <div class="source"><pre>Logger x = LoggerFactory.getLogger("wombat"); +Logger y = LoggerFactory.getLogger("wombat");</pre></div> + + <p> + <code>x</code> and <code>y</code> refer to + <em>exactly</em> the same logger object. + </p> + + <p> + Thus, it is possible to configure a logger and then to + retrieve the same instance somewhere else in the code + without passing around references. In fundamental + contradiction to biological parenthood, where parents always + preceed their children, logback loggers can be + created and configured in any order. In particular, a + "parent" logger will find and link to its descendants even + if it is instantiated after them. + </p> + <p> + Configuration of the logback environment is typically done + at application initialization. The preferred way is by + reading a configuration file. This approach will be + discussed shortly. + </p> + <p> + Logback makes it easy to name loggers by <em>software + component</em>. This can be accomplished by instantiating a + logger in each class, with the logger name equal to the fully + qualified name of the class. This is a useful and + straightforward method of defining loggers. As the log output + bears the name of the generating logger, this naming strategy + makes it easy to identify the origin of a log message. However, + this is only one possible, albeit common, strategy for naming + loggers. Logback does not restrict the possible set of + loggers. As a developer, you are free to name loggers as you + wish. + </p> + + <p>Nevertheless, naming loggers after the class where they are + located seems to be the best general strategy known so far. + </p> + + <a name="AppendersAndLayouts" /> + <h3>Appenders and Layouts</h3> + + <p> + The ability to selectively enable or disable logging requests + based on their logger is only part of the picture. Logback + allows logging requests to print to multiple destinations. In + logback speak, an output destination is called an + appender. Currently, appenders exist for the console, files, + remote socket servers, to MySQL, PostgreSQL, Oracle and other + databases, JMS, and remote UNIX Syslog daemons. + + <!--It is also possible to log asynchronously. --> + </p> + + <p>More than one appender can be attached to a logger.</p> + + <p> The <code><a href="../apidocs/ch/qos/logback/classic/Logger.html#addAppender(ch.qos.logback.core.Appender)">addAppender</a></code> method adds an appender to a + given logger. Each enabled logging request for a given logger + will be forwarded to all the appenders in that logger as well as + the appenders higher in the hierarchy. In other words, appenders are + inherited additively from the logger hierarchy. For example, if a + console appender is added to the root logger, then all enabled + logging requests will at least print on the console. If in + addition a file appender is added to a logger, say <em>L</em>, + then enabled logging requests for <em>L</em> and <em>L</em>'s + children will print on a file <em>and</em> on the console. It is + possible to override this default behavior so that appender + accumulation is no longer additive by setting the additivity flag + of a logger to false. + </p> + + <p> + The rules governing appender additivity are summarized + below. + </p> + <div class="definition"> + + <div class="deftitle">Appender Additivity</div> + + <p> + The output of a log statement of logger <em>L</em> + will go to all the appenders in <em>L</em> + and its ancestors. This is the meaning of the term + "appender additivity". + </p> + + <p> + However, if an ancestor of logger <em>L</em>, say + <em>P</em>, has the additivity flag set to false, then + <em>L</em>'s output will be directed to all the appenders in + <em>L</em> and it's ancestors upto and including + <em>P</em> but not the appenders in any of the ancestors of + <em>P</em>. + </p> + + <p> + Loggers have their additivity flag set to true by + default. + </p> + + </div> + The table below shows an example: + + <table class="bodyTable"> + <tr> + <th>Logger Name</th> + <th>Attached Appenders</th> + <th>Additivity Flag</th> + <th>Output Targets</th> + <th>Comment</th> + </tr> + <tr> + <td>root</td> + <td>A1</td> + <td>not applicable</td> + <td>A1</td> + + <td>Since the root logger stands at the top of the logger + hiearchy, the additivity flag does not apply to it. + </td> + </tr> + <tr> + <td>x</td> + <td>A-x1, A-x2</td> + <td>true</td> + <td>A1, A-x1, A-x2</td> + <td>Appenders of "x" and of root.</td> + </tr> + <tr> + <td>x.y</td> + <td>none</td> + <td>true</td> + <td>A1, A-x1, A-x2</td> + <td>Appenders of "x" and of root.</td> + </tr> + <tr> + <td>x.y.z</td> + <td>A-xyz1</td> + <td>true</td> + <td>A1, A-x1, A-x2, A-xyz1</td> + <td>Appenders of "x.y.z", "x" and of root.</td> + </tr> + <tr> + <td>security</td> + <td>A-sec</td> + <td class="blue"><span class="blue">false</span></td> + <td>A-sec</td> + + <td> + No appender accumulation since the additivity flag is set to + <code>false</code>. Only appender A-sec will be used. + </td> + </tr> + <tr> + <td>security.access</td> + <td>none</td> + <td>true</td> <td>A-sec</td> - <td>No appender accumulation since the additivity flag is set to <code>false</code>. Only appender A-sec will be used. </td> - </tr> - <tr class="a"> - <td>security.access</td> - <td>none</td> - <td>true</td> - <td>A-sec</td> - <td>Only appenders of "security" because the additivity - flag in "security" is set to <code>false</code>. </td> - </tr> - </tbody> - </table> - <p> More often than not, users wish to customize not only the - output destination but also the output format. This is - accomplished by associating a <em>layout</em> with an appender. The layout is responsible for formatting - the logging request according to the user's wishes, whereas - an appender takes care of sending the formatted output to - its destination. The <code>PatternLayout</code>, part of - the standard - logback distribution, lets the user specify the output - format according to conversion patterns similar to the C - language <code>printf</code> function. </p> - <p> For example, the PatternLayout with the conversion pattern - "%-4relative [%thread] %-5level %logger{32} - %msg%n" will output - something akin to: </p> - <div class="source"> - <pre>176 [main] DEBUG chapter2.HelloWorld2 - Hello world.</pre> - </div> - <p>The first field is the number of milliseconds elapsed since - the start of the program. The second field is the thread - making the log request. The third field is the level of the - log request. The fourth field is the name of the logger - associated with the log request. The text after the '-' is - the message of the request. </p> - <a name="ParametrizedLogging"></a> - <h3>Parameterized logging</h3> - <p>Given that loggers in logback-classic implement the <a href="http://www.slf4j.org/api/org/slf4j/Logger.html">SLF4J's - Logger interface</a>, certain printing methods admit more than - one parameter. These printing method variants are mainly - intended to improve performance while minimizing the impact on - the readability of the code. </p> - <p> For some Logger <code>logger</code>, writing, </p> - <div class="source"> - <pre>logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));</pre> - </div> - <p>incurs the cost of constructing the message parameter, that - is converting both integer <code>i</code> and <code>entry[i]</code> to a String, and concatenating intermediate strings. This, - regardless of whether the message will be logged or not. </p> - <p> One possible way to avoid the cost of parameter construction - is by surrounding the log statement with a test. Here is an - example. </p> - <div class="source"> - <pre>if(logger.isDebugEnabled()) { <br /> logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));<br />}</pre> - </div> - <p>This way you will not incur the cost of parameter - construction if debugging is disabled for <code>logger</code>. - On the other hand, if the logger is enabled for the DEBUG - level, you will incur the cost of evaluating whether the - logger is enabled or not, twice: once in <code>debugEnabled</code> and once in <code>debug</code>. This is an insignificant - overhead because evaluating a - logger takes less than 1% of the time it takes to actually - log a request. </p> - <h4>Better alternative</h4> - <p>There exists a convenient alternative based on message - formats. Assuming <code>entry</code> is an object, you can - write: </p> - <div class="source"> - <pre>Object entry = new SomeObject(); <br />logger.debug("The entry is {}.", entry);</pre> - </div> - <p>After evaluting whether to log or not, and only if the - decision - is positive, will the logger implementation format the message - and replace the '{}' pair with the string value of <code>entry</code>. In other words, this form does not - incur - the cost of parameter construction in case the log statement is - disabled. </p> - <p> The following two lines will yield the exact same output. - However, in case of a <em>disabled</em> logging statement, the second variant will outperform the first variant - by a - factor of at least 30. </p> - <div class="source"> - <pre>logger.debug("The new entry is "+entry+".");<br />logger.debug("The new entry is {}.", entry);</pre> - </div> - <p>A two argument variant is also availalble. For example, you - can write: </p> - <div class="source"> - <pre>logger.debug("The new entry is {}. It replaces {}.", entry, oldEntry);</pre> - </div> - <p>If three or more arguments need to be passed, an <code>Object[]</code> variant is also availalble. For - example, you - can write: </p> - <div class="source"> - <pre>Object[] paramArray = {newVal, below, above};<br />logger.debug("Value {} was inserted between {} and {}.", paramArray);</pre> - </div> - <a name="Configuration"></a> - <h3>Configuration</h3> - <p>Inserting log requests into the application code requires a - fair amount of planning and effort. Observation shows that - approximately four percent of code is dedicated to - logging. Consequently, even moderately sized applications will - contain thousands of logging statements embedded within its - code. Given their number, it becomes imperative to manage these - log statements without the need to modify them manually. </p> - <div class="highlight"> - <p>In order to run the examples in this introduction, you need + <td> + Only appenders of "security" because the additivity + flag in "security" is set to + <code>false</code>. + </td> + </tr> + </table> + + + <p> + More often than not, users wish to customize not only the + output destination but also the output format. This is + accomplished by associating a <em>layout</em> + with an appender. The layout is responsible for formatting + the logging request according to the user's wishes, whereas + an appender takes care of sending the formatted output to + its destination. The <code>PatternLayout</code>, part of the standard + logback distribution, lets the user specify the output + format according to conversion patterns similar to the C + language <code>printf</code> + function. + </p> + + <p> + For example, the PatternLayout with the conversion pattern + "%-4relative [%thread] %-5level %logger{32} - %msg%n" will output something akin to: + </p> + + <div class="source"><pre>176 [main] DEBUG chapter2.HelloWorld2 - Hello world.</pre></div> + + <p> + The first field is the number of milliseconds elapsed since + the start of the program. The second field is the thread + making the log request. The third field is the level of the + log request. The fourth field is the name of the logger + associated with the log request. The text after the '-' is + the message of the request. + </p> + + <a name="ParametrizedLogging" /> + <h3>Parameterized logging</h3> + + <p> + Given that loggers in logback-classic implement the <a + href="http://www.slf4j.org/api/org/slf4j/Logger.html">SLF4J's + Logger interface</a>, certain printing methods admit more than + one parameter. These printing method variants are mainly + intended to improve performance while minimizing the impact on + the readability of the code. + </p> + + <p> + For some Logger <code>logger</code>, writing, + </p> + + <div class="source"><pre>logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));</pre></div> + + <p> + incurs the cost of constructing the message parameter, that + is converting both integer <code>i</code> and <code>entry[i]</code> + to a String, and concatenating intermediate strings. This, + regardless of whether the message will be logged or not. + </p> + + <p> + One possible way to avoid the cost of parameter construction + is by surrounding the log statement with a test. Here is an + example. + </p> + + <div class="source"><pre>if(logger.isDebugEnabled()) { + logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i])); +}</pre></div> + + + <p> + This way you will not incur the cost of parameter + construction if debugging is disabled for <code>logger</code>. + On the other hand, if the logger is enabled for the DEBUG + level, you will incur the cost of evaluating whether the + logger is enabled or not, twice: once in <code>debugEnabled</code> + and once in <code>debug</code>. + This is an insignificant overhead because evaluating a + logger takes less than 1% of the time it takes to actually + log a request. + </p> + + + + <h4>Better alternative</h4> + + <p> + There exists a convenient alternative based on message + formats. Assuming <code>entry</code> is an object, you can write: + </p> + + + <div class="source"><pre>Object entry = new SomeObject(); +logger.debug("The entry is {}.", entry);</pre></div> + + <p> + After evaluting whether to log or not, and only if the decision + is positive, will the logger implementation format the message + and replace the '{}' pair with the string value of + <code>entry</code>. In other words, this form does not incur + the cost of parameter construction in case the log statement is + disabled. + </p> + + + <p> + The following two lines will yield the exact same output. + However, in case of a <em>disabled</em> + logging statement, the second variant will outperform the first variant by a + factor of at least 30. + </p> + + <div class="source"><pre>logger.debug("The new entry is "+entry+"."); +logger.debug("The new entry is {}.", entry);</pre></div> + + + <p> + A two argument variant is also availalble. For example, you + can write: + </p> + + <div class="source"><pre>logger.debug("The new entry is {}. It replaces {}.", entry, oldEntry);</pre></div> + + <p>If three or more arguments need to be passed, an + <code>Object[]</code> variant is also availalble. For example, you + can write: + </p> + + + <div class="source"><pre>Object[] paramArray = {newVal, below, above}; +logger.debug("Value {} was inserted between {} and {}.", paramArray);</pre></div> + + <a name="Configuration" /> + <h3>Configuration</h3> + + <p>Inserting log requests into the application code requires a + fair amount of planning and effort. Observation shows that + approximately four percent of code is dedicated to + logging. Consequently, even moderately sized applications will + contain thousands of logging statements embedded within its + code. Given their number, it becomes imperative to manage these + log statements without the need to modify them manually. + </p> + + <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> - <p>The logback environment is fully configurable - programmatically. - However, it is far more flexible to configure logback using - configuration files. In logback, configuration files are written - in XML format. </p> - <p>Existing log4j users can convert their <em>log4j.properties</em> files to <em>logback.xml</em> using our <a href="http://logback.qos.ch/translator/">PropertiesTranslator</a> web-application. </p> - <p> Configuring logback from a XML file is an easy task. One just needs to - instanciate a <code>JoranConfigurator</code> and pass the - configuration - file, as the following example demonstrate. </p> - <em>Example 2.1: Logback configuration from file (<a href="../xref/chapter2/MyAppWithConfigFile.html">logback-examples/src/main/java/chapter2/MyAppWithConfigFile.java</a>)</em> - <div class="source"> - <pre>package chapter2;<br />//Import SLF4J classes.<br />import org.slf4j.Logger;<br />import org.slf4j.LoggerFactory;<br />import ch.qos.logback.classic.LoggerContext;<br />import ch.qos.logback.classic.joran.JoranConfigurator;<br />import ch.qos.logback.core.util.StatusPrinter;<br /><br />public class MyAppWithConfigFile {<br /><br /> public static void main(String[] args) {<br /> Logger logger = LoggerFactory.getLogger(MyAppWithConfigFile.class);<br /> LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();<br /> JoranConfigurator configurator = new JoranConfigurator();<br /> configurator.setContext(lc);<br /> configurator.doConfigure(args[0]);<br /> logger.info("Entering application.");<br /> Bar bar = new Bar();<br /> bar.doIt();<br /> logger.info("Exiting application.");<br /> StatusPrinter.print(lc.getStatusManager());<br /> }<br />}</pre> - </div> - <p>This class defines a logger instance variable. It then - instantiates a <code>Bar</code> object. The <code>Bar</code> class is listed below: </p> - <em>Example 2.2: Sample logging class (<a href="../xref/chapter2/Bar.html">logback-examples/src/main/java/chapter2/Bar.java</a>)</em> - <div class="source"> - <pre>package chapter2;<br />import org.slf4j.Logger;<br />import org.slf4j.LoggerFactory;<br /><br />class Bar {<br /> Logger logger = LoggerFactory.getLogger(Bar.class); public void doIt() {<br /> logger.debug("doing my job");<br /> }<br />}</pre> - </div> - <p><em>MyAppWithConfigFile</em> configures logback by using the <code>JoranConfigurator</code>. Joran is a XML interpreter, - similar to the - commons-digester API, but offering several advantages over - commons-digester. Here, it parses the xml file and runs actions - depending on the tags it finds. To setup the <code>JoranConfigurator</code> properly, we passed the <code>LoggerContext</code>. A <code>LoggerContext</code> is the class that creates and - manages - Loggers in logback. It is also the class that implements the <code>org.slf4j.ILoggerFactory</code> interface. </p> - <p> All - other classes only need to retrieve an instance of <code>org.slf4j.Logger</code> by calling <code>LoggerFactory.getLogger()</code>, and then log away. - For - example, the only dependence of the <code>Bar</code> class - is on <code>org.slf4j.Logger</code> and <code>org.slf4j.LoggerFactory</code>. Except code that - configures + Please refer to the <a href="../setup.html">setup page</a> + for further details. + </p> + </div> + + <p>The logback environment is fully configurable programmatically. + However, it is far more flexible to configure logback using + configuration files. In logback, configuration files are written + in XML format. + </p> + + <p>Existing log4j users can convert their + <em>log4j.properties</em> files to <em>logback.xml</em> using our <a + href="http://logback.qos.ch/translator/">PropertiesTranslator</a> + web-application. + </p> + + <p> + Configuring logback from a XML file is an easy task. One just needs to + instanciate a <code>JoranConfigurator</code> and pass the configuration + file, as the following example demonstrate. + </p> + + <em>Example 2.1: Logback configuration from file (<a + href="../xref/chapter2/MyAppWithConfigFile.html">logback-examples/src/main/java/chapter2/MyAppWithConfigFile.java</a>)</em> + +<div class="source"><pre>package chapter2; + +//Import SLF4J classes. +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import ch.qos.logback.classic.LoggerContext; +import ch.qos.logback.classic.joran.JoranConfigurator; +import ch.qos.logback.core.util.StatusPrinter; + +public class MyAppWithConfigFile { + + public static void main(String[] args) { + Logger logger = LoggerFactory.getLogger(MyAppWithConfigFile.class); + LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); + + JoranConfigurator configurator = new JoranConfigurator(); + configurator.setContext(lc); + configurator.doConfigure(args[0]); + + logger.info("Entering application."); + Bar bar = new Bar(); + bar.doIt(); + logger.info("Exiting application."); + + StatusPrinter.print(lc.getStatusManager()); + } +}</pre></div> + + + <p>This class defines a logger instance variable. + It then instantiates a <code>Bar</code> + object. The <code>Bar</code> class is listed below: + </p> + + <em>Example 2.2: Sample logging class (<a href="../xref/chapter2/Bar.html">logback-examples/src/main/java/chapter2/Bar.java</a>)</em> +<div class="source"><pre>package chapter2; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +class Bar { + + Logger logger = LoggerFactory.getLogger(Bar.class); + + public void doIt() { + logger.debug("doing my job"); + } +}</pre></div> + + <p><em>MyAppWithConfigFile</em> configures logback by using the + <code>JoranConfigurator</code>. Joran is a XML interpreter, similar to the + commons-digester API, but offering several advantages over + commons-digester. Here, it parses the xml file and runs actions + depending on the tags it finds. To setup the <code>JoranConfigurator</code> + properly, we passed the <code>LoggerContext</code>. A + <code>LoggerContext</code> is the class that creates and manages + Loggers in logback. It is also the class that implements the + <code>org.slf4j.ILoggerFactory</code> interface. + </p> + <p> + All + other classes only need to retrieve an instance of + <code>org.slf4j.Logger</code> by calling + <code>LoggerFactory.getLogger()</code>, and then log away. For + example, the only dependence of the <code>Bar</code> class is on + <code>org.slf4j.Logger</code> and + <code>org.slf4j.LoggerFactory</code>. Except code that configures logback (if such code exists) user code does not need to depend on - logback, but on SLF4J instead. </p> - <p>Let us configure logback with the + logback, but on SLF4J instead. + </p> + + <p>Let us configure logback with the next XML configuration file:</p> - <em>Example 2.3: Basic configuration with a xml file - (logback-examples/src/main/java/chapter2/sample-config-1.xml)</em> - <div class="source"> - <pre><?xml version="1.0" encoding="UTF-8" ?><br /><configuration><br /><br /> <appender name="STDOUT"<br /> class="ch.qos.logback.core.ConsoleAppender"><br /> <layout class="ch.qos.logback.classic.PatternLayout"><br /> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern><br /> </layout><br /> </appender><br /><br /> <root><br /> <level value="debug" /><br /> <appender-ref ref="STDOUT" /><br /> </root><br /><br /></configuration></pre> - </div> - <p>We first created an <code>Appender</code>, named <em>STDOUT</em> that is of <code>ConsoleAppender</code> type. Its layout - is managed - by a <code>PatternLayout</code>, that uses the value of - the <em>pattern</em> parameter - to generate the logging statement. We then configured the root - logger, set its level to DEBUG, and linked the newly configured <code>ConsoleAppender</code> to the root logger.</p> - <p>Note that we've set the root logger level explicitly. Since - root - logger have a DEBUG level by default we could have omitted this.</p> - <p>To run this example, use this command:</p> - <div class="source"> - <pre>java chapter2.MyAppWithConfigFile src/main/java/chapter2/sample-config-1.xml</pre> - </div> - <p> Here is what you should see in the console: </p> - <div class="source"> - <pre>18:15:26.718 [main] INFO chapter2.MyAppWithConfigFile - Entering application.<br />18:15:26.718 [main] DEBUG chapter2.Bar - doing my job<br />18:15:26.718 [main] INFO chapter2.MyAppWithConfigFile - Exiting application.</pre> - </div> - <p>Logging to the console is a rather simple example. Let's now - configure logback so that it logs on the console, but also to a - custom file.</p> - <em>Example 2.4: Configuring logback with multiple appenders - (logback-examples/src/main/java/chapter2/sample-config-2.xml)</em> - <div class="source"> - <pre><?xml version="1.0" encoding="UTF-8" ?><br /><configuration><br /><br /> <appender name="STDOUT"<br /> class="ch.qos.logback.core.ConsoleAppender"><br /> <layout class="ch.qos.logback.classic.PatternLayout"><br /> <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern><br /> </layout><br /> </appender><br /><br /> <appender name="FILE"<br /> class="ch.qos.logback.core.FileAppender"><br /> <layout class="ch.qos.logback.classic.PatternLayout"><br /> <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern><br /> </layout><br /> <File>sample-log.txt</File><br /> </appender><br /><br /> <root><br /> <level value="debug" /><br /> <appender-ref ref="STDOUT" /><br /> <appender-ref ref="FILE" /><br /> </root><br /><br /></configuration></pre> - </div> - <p>Now, - all the logging statements are directed to the console and - to a file named <em>sample-log.txt</em>. As you can see, - the - configuration needed to add an Appender is rather small. The options - are declared as xml element, in either Appender configuration. They are - read and their value are assigned to the corresponding attribute in - the specified java class. </p> - <p>Suppose that we do not want to see the DEBUG level - statements in - the chapter2 package anymore. This is done by adding the following - bold xml snippet to the configuration file, right before the <code><root></code> element.</p> - <em>Example 2.5: Configuring a specific logger - (logback-examples/src/main/java/chapter2/sample-config-3.xml)</em> - <div class="source"> - <pre><?xml version="1.0" encoding="UTF-8" ?><br /><configuration><br /><br /> <appender name="STDOUT"<br /> class="ch.qos.logback.core.ConsoleAppender"><br /> <layout class="ch.qos.logback.classic.PatternLayout"><br /> <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern><br /> </layout><br /> </appender><br /> <appender name="FILE"<br /> class="ch.qos.logback.core.FileAppender"><br /> <layout class="ch.qos.logback.classic.PatternLayout"><br /> <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern><br /> </layout><br /> <File>sample-log.txt</File><br /> </appender><br /><b><br /></b> <b><logger name="chapter2"><br /></b> <b><level value="info" /><br /></b> <b></logger><br /></b><br /> <root><br /> <level value="debug" /><br /> <appender-ref ref="STDOUT" /><br /> <app ender-ref ref="FILE" /><br /> </root><br /><br /></configuration><br /> -</pre> - </div> - <p>Once done, the output is modified to show only statements of - level INFO and higher:</p> - <div class="source"> - <pre>0 [main] INFO chapter2.MyAppWithConfigFile - Entering application.<br />0 [main] INFO chapter2.MyAppWithConfigFile - Exiting application.</pre> - </div> - <p>Note - that to obtain these different logging behaviors we did not - need to recompile code. We could just as easily have logged to a UNIX - Syslog daemon, redirected all chapter2 output to a log visualizer, or - forwarded logging events to a remote logback server, which would log - according to local server policy, for example by forwarding the log - event to a second logback server.</p> - <p>Until now, we always had to specifically load the - configuration file and pass it - to a logback component. However, this step is not necessary in most - cases. When logback - is not configured by instanciating <code>JoranConfigurator</code> objects, it follows a simple policy to configure itself. </p> - <ul> - <li>Logback first tries to find a file called <em>logback.xml</em> within the classpath.</li> - <li>If no such file is found, it checks for another file called <em>logback-test.xml</em>.</li> - <li>In case none of these files are found, logback configures - itself automatically using the <a href="../xref/ch/qos/logback/classic/BasicConfigurator.html"><code>BasicConfigurator</code> </a> class.</li> - </ul> - <p> The first two checks allow for two environments to cooperate nicely. - When the application - using logback is in development and test process, a special file can be - used to setup - a logging environment that is developer-friendly. Once in production - environment, the presence of a <em>logback.xml</em> file - overrides any <em>logback-test.xml</em> configuration. </p> - <p> The last step is meant to provide very basic logging functionnality in - case no configuration - file is provided. In that case, the logging requests are output to the - console. </p> - <p> Letting logback load its configuration file is the most often used way - of configuring. It allows the user to only import SLF4J classes in her - code. </p> - <p>The last step of logback's configuration policy - permits the use of a - minimal - logging configuration right out of the box. Remember the very first - example of the introduction. The output was generated due to this - feature. </p> - <a name="UnderTheHood"></a> - <h3>A peak under the hood</h3> - <p>After we have introduced the essential logback components, we - are - now ready to describe the steps that the logback framework takes when - the user invokes a logger's printing method. Let us now analyze the - steps logback takes when the user invokes the <code>info()</code> method of a logger named <em>com.wombat</em>. </p> - <h4>1. Get the filter chain decision</h4> - <p>Logback's <code>TurboFilter</code> chain is - called. These filters may - be used to prodvide a context-wide threshold, or to filter out certain - events based on basic logging informations such as <code>Marker</code>, <code>Level</code>, <code>Logger</code>, - message, or the <code>Throwable</code> that was provided in the logging request. - If the reply of the filter chain is <code>FilterReply.DENY</code>, - then the - logging request is dropped. If it is <code>FilterReply.NEUTRAL</code>, - then - the next step is processed. In case the reply is <code>FilterReply.ACCEPT</code>, - the next step is skipped and the logging request is directly processed - to step 3. </p> - <h4>2. Apply the Logger level filter</h4> - <p>Logback compares the effective level of the <em>com.wombat</em> logger - with the level of the request (in this example: <em>INFO</em>). - If the logging - request is disabled, then logback will drop the request without further - processing. </p> - <h4>3. Create a <code>LoggingEvent</code> object</h4> - <p>If the request passed the previous filter, or if the <code>TurboFilter</code> chain - gave a <code>FilterReply.ACCEPT</code> result, logback - will create a <code>ch.qos.logback.classic.LoggingEvent</code> object - containing all the relevant parameters of the request such as the - logger of the request, the request - level, the message, the exception that might have been passed along the - request, - the current time, the current thread, several information about the - class that issued the logging request and the <code>MDC</code> map. Note that some of these fields - are initialized lazily, that is only when they are actually needed. </p> - <h4>4. Invoking appenders</h4> - <p>After the creation of a <code>LoggingEvent</code> object, logback will proceed to invoke the <code>doAppend()</code> methods of all the applicable appenders, that is, the appenders - inherited from the logger context. </p> - <p> All appenders shipped with the logback distribution extend the <code>AppenderBase</code> abstract class that implements the <code>doAppend</code> method in a synchronized block ensuring thread-safety. The <code>doAppend()</code> method of <code>AppenderBase</code> also invokes custom filters attached to the appender, if any such - filters exist. Custom filters, which can be dynamically attached to any - appender, are presented Chapter 6. </p> - <h4>5. Formatting the <code>LoggingEvent</code></h4> - <p>It is responsibility of the invoked appender to format the - logging - event. However, most (but not all) appenders delegate the task of - formatting the logging event to their layout. Their layout formats the <code>LoggingEvent</code> instance and returns the result as a String. Note that some appenders, - such as the <code>SocketAppender</code>, - do not transform the logging event into a string but serialize it - instead. Consequently, they do not require nor have a layout. </p> - <h4>6. Sending out the <code>LoggingEvent</code></h4> - <p>After the logging event is fully formatted it is sent to its - destination by each appender. </p> - <p> Here is a sequence UML diagram to show how everything works. You might - want to click on the image to display its bigger version. </p> - <a href="underTheHood.html"><img src="images/chapter2/underTheHoodSequence2_small.gif" /></a> <a name="Performance"></a> - <h3>Performance</h3> - <p>One of the often-cited arguments against logging is its - computational - cost. This is a legitimate concern as even moderately sized - applications can generate thousands of log requests. Much effort is - spent measuring and tweaking logging performance. - Independently of these efforts, the user should still be aware of the - following performance issues. </p> - <h4>1. Logging performance when logging is turned off - entirely</h4> - <p>You can turn off logging entirely by setting the level of the - root logger - to <code>Level.OFF</code>, - the highest possible level. When logging is turned off entirely, the - cost of a log request consists of a method invocation plus an integer - comparison. On a 3.2Ghz Pentium D machine this cost is typically around - 20 nanoseconds. </p> - <p>However, any method invocation involves the "hidden" cost of - parameter construction. For example, for some logger <em>x</em> writing, </p> - <div class="source"> - <pre>x.debug("Entry number: " + i + "is " + entry[i]);</pre> - </div> - <p> incurs the cost of constructing the message parameter, i.e. converting - both integer <code>i</code> and <code>entry[i]</code> to a string, and concatenating intermediate strings, regardless of - whether the message will be logged or not. </p> - <p>The cost of parameter construction can be quite high and - depends on the - size of the parameters involved. To avoid the cost of parameter - construction you can use logback's parametrized logging: </p> - <div class="source"> - <pre>x.debug("Entry number: {} is {}", i, entry[i]);</pre> - </div> - <p> This will not incur the cost of parameter construction. Compared to the - previous call to the <code>debug()</code> method, this call will be faster by a very wide margin. The message - will be formatted only if the request is processed to the appenders. If - it is processed, the component that formats the message offers high - performance and does not impact negatively the overall process. It - respectively takes 2 and 4 microseconds to format a message with 1 and - 3 parameters. </p> - <p>Please notice that, despite the performance points - that we just - discussed, inserting logging statements in tight-loops or very - frequently invoked code is a lose-lose proposal - and will not result in high performance. They will slow down your - application even if logging is turned off or generate massive (and - hence useless) output if enabled. </p> - <h4>2. The performance of deciding whether to log or not to log - when logging is turned on.</h4> - <p>In logback, there is no need to walk the whole logger - hierarchy. A logger knows - its effective level (that is, its level, once level inheritance has - been - taken into consideration) when it is created. Should the level of a - parent logger - be changed, then all child loggers will be contacted and handle the - change. Thus, before - accepting or denying a request based on the effective level, the logger - does not need - to search its ancestors. </p> - <p> Given this situation, it takes the same time to decide whether to log - or not when logging - is turned on as it takes when logging is turned off. </p> - <h4>3. Actual logging (formatting and writing to the - output device)</h4> - <p>This is the cost of formatting the log output and sending it - to its - target destination. Here again, a serious effort was made to make - layouts (formatters) perform as quickly as possible. The same is true - for appenders. The typical cost of actually logging is about 9 to 12 - microseconds when logging to a file on the local machine. - It goes up to 1 millisecond when logging to a database on a remote - server. </p> - <p>Although feature-rich, one of the foremost design - goals of logback - was speed of execution, a requirement which is second only to - reliability. Some logback components have been rewritten many times to - improve performance. </p> + + <em>Example 2.3: Basic configuration with a xml file (logback-examples/src/main/java/chapter2/sample-config-1.xml)</em> +<div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?> + +<configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> + + <p>We first created an <code>Appender</code>, named <em>STDOUT</em> + that is of <code>ConsoleAppender</code> type. Its layout is managed + by a <code>PatternLayout</code>, that uses the value of the <em>pattern</em> parameter + to generate the logging statement. We then configured the root + logger, set its level to DEBUG, and linked the newly configured + <code>ConsoleAppender</code> to the root logger.</p> + + <p>Note that we've set the root logger level explicitly. Since root + logger have a DEBUG level by default we could have omitted this.</p> + + <p>To run this example, use this command:</p> + +<div class="source"><pre>java chapter2.MyAppWithConfigFile src/main/java/chapter2/sample-config-1.xml</pre></div> + + <p> + Here is what you should see in the console: + </p> + +<div class="source"><pre>18:15:26.718 [main] INFO chapter2.MyAppWithConfigFile - Entering application. +18:15:26.718 [main] DEBUG chapter2.Bar - doing my job +18:15:26.718 [main] INFO chapter2.MyAppWithConfigFile - Exiting application.</pre></div> + + + <p>Logging to the console is a rather simple example. Let's now + configure logback so that it logs on the console, but also to a + custom file.</p> + +<em>Example 2.4: Configuring logback with multiple appenders (logback-examples/src/main/java/chapter2/sample-config-2.xml)</em> +<div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?> + +<configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern> + </layout> + </appender> + + <appender name="FILE" + class="ch.qos.logback.core.FileAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern> + </layout> + <File>sample-log.txt</File> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + <appender-ref ref="FILE" /> + </root> +</configuration></pre></div> + + <p>Now, all the logging statements are directed to the console and + to a file named <em>sample-log.txt</em>. As you can see, the + configuration needed to add an Appender is rather small. The options + are declared as xml element, in either Appender configuration. They are + read and their value are assigned to the corresponding attribute in + the specified java class. + </p> + + <p>Suppose that we do not want to see the DEBUG level statements in + the chapter2 package anymore. This is done by adding the following + bold xml snippet to the configuration file, right before the + <code><root></code> element.</p> + +<em>Example 2.5: Configuring a specific logger (logback-examples/src/main/java/chapter2/sample-config-3.xml)</em> +<div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?> + +<configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern> + </layout> + </appender> + + <appender name="FILE" + class="ch.qos.logback.core.FileAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern> + </layout> + <File>sample-log.txt</File> + </appender> +<b> + <logger name="chapter2"> + <level value="info" /> + </logger> +</b> + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + <appender-ref ref="FILE" /> + </root> +</configuration> +</pre></div> + + <p>Once done, the output is modified to show only statements of level INFO and higher:</p> + +<div class="source"><pre>0 [main] INFO chapter2.MyAppWithConfigFile - Entering application. +0 [main] INFO chapter2.MyAppWithConfigFile - Exiting application.</pre></div> + + <p>Note that to obtain these different logging behaviors we did not need to recompile code. + We could just as easily have logged to a UNIX Syslog daemon, redirected all chapter2 output + to a log visualizer, or forwarded logging events to a remote logback server, + which would log according to local server policy, for example by forwarding the log event + to a second logback server.</p> + + + <p> + Until now, we always had to specifically load the configuration file and pass it + to a logback component. However, this step is not necessary in most cases. When logback + is not configured by instanciating <code>JoranConfigurator</code> objects, it follows + a simple policy to configure itself. + </p> + + <ul> + <p>Logback first tries to find a file called <em>logback.xml</em> within the classpath.</p> + <p>If no such file is found, it checks for another file called <em>logback-test.xml</em>.</p> + <p>In case none of these files are found, logback configures itself automatically using the + <a href="../xref/ch/qos/logback/classic/BasicConfigurator.html"><code>BasicConfigurator</code> + </a> class.</p> + </ul> + + <p> + The first two checks allow for two environments to cooperate nicely. When the application + using logback is in development and test process, a special file can be used to setup + a logging environment that is developer-friendly. Once in production environment, the + presence of a <em>logback.xml</em> file overrides any <em>logback-test.xml</em> + configuration. + </p> + + <p> + The last step is meant to provide very basic logging functionnality in case no configuration + file is provided. In that case, the logging requests are output to the console. + </p> + + <p> + Letting logback load its configuration file is the most often used way of + configuring. It allows the user to only import SLF4J classes in her code. + </p> + + <p> + The last step of logback's configuration policy permits the use of a minimal + logging configuration right out of the box. Remember the very first example of + the introduction. The output was generated due to this feature. + </p> + +<a name="UnderTheHood" /> +<h3>A peak under the hood</h3> + +<p> +After we have introduced the essential logback components, we are now +ready to describe the steps that the logback framework takes when the user invokes +a logger's printing method. Let us now analyze the steps logback takes when the +user invokes the <code>info()</code> method of a +logger named <em>com.wombat</em>. +</p> + +<h4>1. Get the filter chain decision</h4> + +<p> +Logback's <code>TurboFilter</code> chain is called. These filters may +be used to prodvide a context-wide threshold, or to filter out certain +events based on basic logging informations such as <code>Marker</code>, +<code>Level</code>, <code>Logger</code>, message, or the <code>Throwable</code> +that was provided in the logging request. +If the reply of the filter chain is <code>FilterReply.DENY</code>, then the +logging request is dropped. If it is <code>FilterReply.NEUTRAL</code>, then +the next step is processed. In case the reply is <code>FilterReply.ACCEPT</code>, +the next step is skipped and the logging request is directly processed to step 3. +</p> + +<h4>2. Apply the Logger level filter</h4> + +<p> +Logback compares the effective level of the <em>com.wombat</em> logger +with the level of the request (in this example: <em>INFO</em>). If the logging +request is disabled, then logback will drop the request without further processing. +</p> + +<h4>3. Create a <code>LoggingEvent</code> object</h4> + +<p> +If the request passed the previous filter, or if the <code>TurboFilter</code> chain +gave a <code>FilterReply.ACCEPT</code> result, logback will create a +<code>ch.qos.logback.classic.LoggingEvent</code> object containing all the +relevant parameters of the request such as the logger of the request, the request +level, the message, the exception that might have been passed along the request, +the current time, the current thread, several information about the class that +issued the logging request and the <code>MDC</code> map. Note that some of these fields +are initialized lazily, that is only when they are actually needed. +</p> + +<h4>4. Invoking appenders</h4> + +<p> +After the creation of a <code>LoggingEvent</code> object, logback will proceed +to invoke the <code>doAppend()</code> methods of all the applicable appenders, +that is, the appenders inherited from the logger context. +</p> +<p> +All appenders shipped with the logback distribution extend the +<code>AppenderBase</code> abstract class that implements the +<code>doAppend</code> method in a synchronized block ensuring thread-safety. +The <code>doAppend()</code> method of <code>AppenderBase</code> also invokes +custom filters attached to the appender, if any such filters exist. +Custom filters, which can be dynamically attached to any appender, +are presented Chapter 6. +</p> + +<h4>5. Formatting the <code>LoggingEvent</code></h4> + +<p> +It is responsibility of the invoked appender to format the +logging event. However, most (but not all) appenders delegate +the task of formatting the logging event to their layout. Their +layout formats the <code>LoggingEvent</code> instance and returns the +result as a String. Note that some appenders, such as the +<code>SocketAppender</code>, do not transform the logging event +into a string but serialize it instead. +Consequently, they do not require nor have a layout. +</p> + +<h4>6. Sending out the <code>LoggingEvent</code></h4> + +<p> +After the logging event is fully formatted it is sent to +its destination by each appender. +</p> + +<p> +Here is a sequence UML diagram to show how everything works. You might +want to click on the image to display its bigger version. +</p> + +<a href="underTheHood.html"><img src="images/chapter2/underTheHoodSequence2_small.gif" /></a> + +<a name="Performance" /> +<h3>Performance</h3> + +<p> +One of the often-cited arguments against logging is its computational cost. +This is a legitimate concern as even moderately sized applications can generate +thousands of log requests. Much effort is spent measuring and tweaking +logging performance. +Independently of these efforts, the user should still be aware of the following +performance issues. +</p> + +<h4>1. Logging performance when logging is turned off entirely</h4> + +<p> +You can turn off logging entirely by setting the level of the root logger +to <code>Level.OFF</code>, the highest possible level. +When logging is turned off entirely, +the cost of a log request consists of a method invocation plus an +integer comparison. On a 3.2Ghz Pentium D machine this cost is typically +around 20 nanoseconds. +</p> + +<p> +However, any method invocation involves the "hidden" cost of parameter construction. +For example, for some logger <em>x</em> writing, +</p> + +<div class="source"><pre>x.debug("Entry number: " + i + "is " + entry[i]);</pre></div> + +<p> +incurs the cost of constructing the message parameter, i.e. converting both +integer <code>i</code> and <code>entry[i]</code> to a string, and concatenating +intermediate strings, regardless of whether the message will be logged or not. +</p> + +<p> +The cost of parameter construction can be quite high and depends on the size +of the parameters involved. To avoid the cost of parameter construction +you can use logback's parametrized logging: +</p> + +<div class="source"><pre>x.debug("Entry number: {} is {}", i, entry[i]);</pre></div> + +<p> +This will not incur the cost of parameter construction. Compared to the +previous call to the <code>debug()</code> method, this call will be faster by +a very wide margin. +The message will be formatted only if the request is processed to the appenders. +If it is processed, the component that formats the message offers high performance +and does not impact negatively the overall process. +It respectively takes 2 and 4 microseconds to format a message with 1 and 3 parameters. +</p> + +<p> +Please notice that, despite the performance points that we just discussed, inserting +logging statements in tight-loops or very frequently invoked code is a lose-lose proposal +and will not result in high performance. They will slow down your application even +if logging is turned off or generate massive (and hence useless) output if enabled. +</p> + +<h4>2. The performance of deciding whether to log or not to log when logging is turned on.</h4> + +<p> +In logback, there is no need to walk the whole logger hierarchy. A logger knows +its effective level (that is, its level, once level inheritance has been +taken into consideration) when it is created. Should the level of a parent logger +be changed, then all child loggers will be contacted and handle the change. Thus, before +accepting or denying a request based on the effective level, the logger does not need +to search its ancestors. +</p> + +<p> +Given this situation, it takes the same time to decide whether to log or not when logging +is turned on as it takes when logging is turned off. +</p> + +<h4>3. Actual logging (formatting and writing to the output device)</h4> + +<p> +This is the cost of formatting the log output and sending it to its +target destination. Here again, a serious effort was made to make +layouts (formatters) perform as quickly as possible. +The same is true for appenders. The typical cost of actually logging is +about 9 to 12 microseconds when logging to a file on the local machine. +It goes up to 1 millisecond when logging to a database on a remote server. +</p> + +<p> +Although feature-rich, one of the foremost design goals of logback was speed +of execution, a requirement which is second only to reliability. Some logback +components have been rewritten many times to improve performance. +</p> + <script src="../templates/footer.js"></script> </div> Modified: logback/trunk/logback-site/src/site/resources/manual/contextSelector.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/manual/contextSelector.html (original) +++ logback/trunk/logback-site/src/site/resources/manual/contextSelector.html Mon Feb 5 14:28:49 2007 @@ -16,31 +16,36 @@ <div id="right"> <script src="../templates/right.js"></script> </div> -<div id="content"><br /> - <h2>Chapter 8: Context Selector</h2> +<div id="content"> + + <h2>Chapter 8: Context Selector</h2> <div class="author"> - Authors: Ceki G�lc�, S�bastien Pennec + Authors: Ceki Gülcü, Sébastien Pennec </div> - <table class="bodyTable"> - <tr class="a"> - <td> - <a 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"></img> + <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>Copyright © 2000-2006, QOS.ch</p> <p> - + <!--Creative Commons License--> This work is licensed under a - <a href="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + <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> @@ -135,10 +140,10 @@ nested in a <em>Configuration</em> element: </p> -<div class="source"><pre><Call class="java.lang.System" name="setProperty"> - <Arg>logback.ContextSelector</Arg> - <Arg>JNDI</Arg> -</Call></pre></div> +<div class="source"><pre><Call class="java.lang.System" name="setProperty"> + <Arg>logback.ContextSelector</Arg> + <Arg>JNDI</Arg> +</Call></pre></div> <p> Be aware that adding a <em>-Dlogback.ContextSelector=JNDI</em> to the java @@ -169,24 +174,24 @@ <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> +<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> +<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 @@ -207,8 +212,8 @@ 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> +<div class="source"><pre><listener> + <listener-class>ch.qos.logback.classic.selector.servlet.ContextDetachingSCL</listener-class> </listener</pre></div> @@ -242,14 +247,14 @@ 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> +<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> @@ -258,7 +263,7 @@ in the <em>web.xml</em> file, as in: </p> -<div class="source"><pre><display-name>Name_Of_My_WebApp</display-name></pre></div> +<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 Modified: logback/trunk/logback-site/src/site/resources/manual/filters.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/manual/filters.html (original) +++ logback/trunk/logback-site/src/site/resources/manual/filters.html Mon Feb 5 14:28:49 2007 @@ -16,30 +16,36 @@ <div id="right"> <script src="../templates/right.js"></script> </div> -<div id="content"> <h2>Chapter 6: Filter chains</h2> +<div id="content"> + + <h2>Chapter 6: Filter chains</h2> <div class="author"> - Authors: Ceki G�lc�, S�bastien Pennec + Authors: Ceki Gülcü, Sébastien Pennec </div> - <table class="bodyTable"> - <tr class="a"> - <td> - <a 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"></img> + <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>Copyright © 2000-2006, QOS.ch</p> <p> - + <!--Creative Commons License--> This work is licensed under a - <a href="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + <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> @@ -72,7 +78,7 @@ <h2>Logback Classic</h2> - <a name="Filter"></a> + <a name="Filter" /> <p><code>Filter</code> objects all implement the <a href="../xref/ch/qos/logback/core/filter/Filter.html"><code>Filter</code></a> abscract class. The <code>decide(Object event)</code> method is passed a @@ -87,7 +93,7 @@ Figure 6.1 depicts a sample filter chain consisting of three filters. </p> - <img src="images/chapter6/filterChain.gif" alt="A sample filter chain"></img> + <img src="images/chapter6/filterChain.gif" alt="A sample filter chain"/> <p> Filters are based on ternary logic. The <code>decide(Object event)</code> @@ -136,7 +142,7 @@ public FilterReply decide(Object eventObject) { LoggingEvent event = (LoggingEvent)eventObject; - if (event.getMessage().contains("sample")) { + if (event.getMessage().contains("sample")) { return FilterReply.ACCEPT; } else { return FilterReply.NEUTRAL; @@ -151,22 +157,22 @@ </p> <em>Example 6.2: SampleFilter configuration (logback-examples/src/main/java/chapter6/SampleFilterConfig.xml)</em> -<div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <b><Filter class="chapter6.SampleFilter" /></b> +<div class="source"><pre><configuration> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <b><Filter class="chapter6.SampleFilter" /></b> - <layout class="ch.qos.logback.classic.PatternLayout"> - <pattern> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern> %-4relative [%thread] %-5level %logger - %msg%n - </pattern> - </layout> - </appender> + </pattern> + </layout> + </appender> - <root> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + <root> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p> Thanks to Joran, logback's powerful configuration framework, adding @@ -198,25 +204,25 @@ </p> <em>Example 6.3: Sample LevelFilter configuration (logback-examples/src/main/java/chapter6/LevelFilterConfig.xml)</em> -<div class="source"><pre><configuration> - <appender name="CONSOLE" - class="ch.qos.logback.core.ConsoleAppender"> - <b><filter class="ch.qos.logback.classic.filter.LevelFilter"> - <level>INFO</level> - <onMatch>ACCEPT</onMatch> - <onMismatch>DENY</onMismatch> - </filter></b> - <layout class="ch.qos.logback.classic.PatternLayout"> - <pattern> +<div class="source"><pre><configuration> + <appender name="CONSOLE" + class="ch.qos.logback.core.ConsoleAppender"> + <b><filter class="ch.qos.logback.classic.filter.LevelFilter"> + <level>INFO</level> + <onMatch>ACCEPT</onMatch> + <onMismatch>DENY</onMismatch> + </filter></b> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern> %-4relative [%thread] %-5level %logger{30} - %msg%n - </pattern> - </layout> - </appender> - <root> - <level value="DEBUG" /> - <appender-ref ref="CONSOLE" /> - </root> -</configuration></pre></div> + </pattern> + </layout> + </appender> + <root> + <level value="DEBUG" /> + <appender-ref ref="CONSOLE" /> + </root> +</configuration></pre></div> <p> The second filter that ships with logback is @@ -228,23 +234,23 @@ </p> <em>Example 6.4: Sample ThresholdFilter configuration (logback-examples/src/main/java/chapter6/ThresholdFilterConfig.xml)</em> -<div class="source"><pre><configuration> - <appender name="CONSOLE" - class="ch.qos.logback.core.ConsoleAppender"> - <b><filter class="ch.qos.logback.classic.filter.ThresholdFilter"> - <level>INFO</level> - </filter></b> - <layout class="ch.qos.logback.classic.PatternLayout"> - <pattern> +<div class="source"><pre><configuration> + <appender name="CONSOLE" + class="ch.qos.logback.core.ConsoleAppender"> + <b><filter class="ch.qos.logback.classic.filter.ThresholdFilter"> + <level>INFO</level> + </filter></b> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern> %-4relative [%thread] %-5level %logger{30} - %msg%n - </pattern> - </layout> - </appender> - <root> - <level value="DEBUG" /> - <appender-ref ref="CONSOLE" /> - </root> -</configuration></pre></div> + </pattern> + </layout> + </appender> + <root> + <level value="DEBUG" /> + <appender-ref ref="CONSOLE" /> + </root> +</configuration></pre></div> <h3>Evaluator Filters</h3> @@ -265,7 +271,7 @@ or <code>AbstractMatcherFilter</code> classes. </p> - <a name="EventEvaluator"></a> + <a name="EventEvaluator" /> <h3>Event Evaluators</h3> <p> @@ -279,29 +285,29 @@ </p> <em>Example 6.5: Basic event evaluator usage (logback-examples/src/main/java/chapter6/basicEventEvaluator.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <b><filter class="ch.qos.logback.core.filter.EvaluatorFilter"> - <evaluator name="myEval"> - <expression>message.contains("billing")</expression> - </evaluator> - <OnMismatch>NEUTRAL</OnMismatch> - <OnMatch>DENY</OnMatch> - </filter></b> - <layout class="ch.qos.logback.classic.PatternLayout"> - <pattern> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <b><filter class="ch.qos.logback.core.filter.EvaluatorFilter"> + <evaluator name="myEval"> + <expression>message.contains("billing")</expression> + </evaluator> + <OnMismatch>NEUTRAL</OnMismatch> + <OnMatch>DENY</OnMatch> + </filter></b> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern> %-4relative [%thread] %-5level %logger - %msg%n - </pattern> - </layout> - </appender> - - <root> - <level value="INFO" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + </pattern> + </layout> + </appender> + + <root> + <level value="INFO" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p> The bold part in the previous configuration adds an <code>EvaluatorFilter</code> @@ -316,13 +322,13 @@ The implicit variables available to the <code>EventEvaluator</code> are described below: </p> - <table class="bodyTable"> - <tr class="b"> + <table> + <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> - <tr class="a"> + <tr> <td>event </td> <td><code>LoggingEvent</code></td> @@ -332,14 +338,14 @@ variable. </td> </tr> - <tr class="b"> + <tr> <td>message </td> <td><code>String</code></td> <td>The message created with the logging request. </td> </tr> - <tr class="a"> + <tr> <td>logger </td> <td><code>LoggerRemoteView</code></td> @@ -349,7 +355,7 @@ performs much better when serialized. </td> </tr> - <tr class="b"> + <tr> <td>level </td> <td><code>int</code></td> @@ -359,30 +365,30 @@ using <em>level > INFO</em> is a correct expression. </td> </tr> - <tr class="a"> + <tr> <td>timeStamp </td> <td><code>long</code></td> <td>The timestamp corresponding to the logging event's creation. </td> </tr> - <tr class="b"> + <tr> <td>marker </td> <td><code>Marker</code></td> <td>The <code>Marker</code> object associated with the logging request. </td> </tr> - <tr class="a"> + <tr> <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>. + following expression: <em>mdc.get("myKey")</em>. </td> </tr> - <tr class="b"> + <tr> <td>throwable </td> <td><code>Throwable</code></td> @@ -436,17 +442,17 @@ can use an <code>EvaluatorFilter</code> configured as follows: </p> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> ... - <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> - <evaluator name="myEval"> - <expression>message.contains("billing")</expression> - </evaluator> - <OnMismatch>NEUTRAL</OnMismatch> - <OnMatch>DENY</OnMatch> - </filter> + <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> + <evaluator name="myEval"> + <expression>message.contains("billing")</expression> + </evaluator> + <OnMismatch>NEUTRAL</OnMismatch> + <OnMatch>DENY</OnMatch> + </filter> ... -</configuration></pre></div> +</configuration></pre></div> <p> This filter will deny any logging event whose message @@ -465,7 +471,7 @@ 0 [main] INFO chapter6.FilterEvents - logging statement 9</pre></div> - <a name="TurboFilter"></a> + <a name="TurboFilter" /> <h3>TurboFilters</h3> <p> @@ -546,7 +552,7 @@ @Override public void start() { - if (marker != null && marker.trim().length() > 0) { + if (marker != null && marker.trim().length() > 0) { markerToAccept = MarkerFactory.getMarker(marker); super.start(); } @@ -572,24 +578,24 @@ </p> <em>Example 6.7: Basic custom <code>TurboFilter</code> configuration (logback-examples/src/main/java/chapter6/sampleTurboFilterConfig.xml)</em> -<div class="source"><pre><configuration> - <b><turboFilter class="chapter6.SampleTurboFilter"> - <Marker>sample</Marker> - </turboFilter></b> - - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <pattern> +<div class="source"><pre><configuration> + <b><turboFilter class="chapter6.SampleTurboFilter"> + <Marker>sample</Marker> + </turboFilter></b> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern> %-4relative [%thread] %-5level %logger - %msg%n - </pattern> - </layout> - </appender> - - <root> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + </pattern> + </layout> + </appender> + + <root> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p> Logback classic ships with several <code>TurboFilter</code> classes ready for use. @@ -607,30 +613,30 @@ <em>Example 6.8: <code>MDCFilter</code> and <code>MarkerFilter</code> configuration (logback-examples/src/main/java/chapter6/turboFilters.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <turboFilter class="ch.qos.logback.classic.turbo.MDCFilter"> - <MDCKey>username</MDCKey> - <Value>sebastien</Value> - <OnMatch>ACCEPT</OnMatch> - </turboFilter> + <turboFilter class="ch.qos.logback.classic.turbo.MDCFilter"> + <MDCKey>username</MDCKey> + <Value>sebastien</Value> + <OnMatch>ACCEPT</OnMatch> + </turboFilter> - <turboFilter class="ch.qos.logback.classic.turbo.MarkerFilter"> - <Marker>billing</Marker> - <OnMatch>DENY</OnMatch> - </turboFilter> - - <appender name="console" class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%date [%thread] %-5level %logger - %msg%n</Pattern> - </layout> - </appender> - - <root> - <level value="info"/> - <appender-ref ref="console" /> - </root> -</configuration></pre></div> + <turboFilter class="ch.qos.logback.classic.turbo.MarkerFilter"> + <Marker>billing</Marker> + <OnMatch>DENY</OnMatch> + </turboFilter> + + <appender name="console" class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%date [%thread] %-5level %logger - %msg%n</Pattern> + </layout> + </appender> + + <root> + <level value="info"/> + <appender-ref ref="console" /> + </root> +</configuration></pre></div> <p> You can see this configuration in action by issuing the following command: @@ -712,26 +718,26 @@ </p> <em>Example 6.9: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <b><filter class="ch.qos.logback.core.filter.EvaluatorFilter"> - <evaluator name="myEval"> - <expression>event.getStatusCode() == 404</expression> - </evaluator> - <OnMismatch>NEUTRAL</OnMismatch> - <OnMatch>ACCEPT</OnMatch> - </filter></b> - <layout class="ch.qos.logback.access.PatternLayout"> - <pattern> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <b><filter class="ch.qos.logback.core.filter.EvaluatorFilter"> + <evaluator name="myEval"> + <expression>event.getStatusCode() == 404</expression> + </evaluator> + <OnMismatch>NEUTRAL</OnMismatch> + <OnMatch>ACCEPT</OnMatch> + </filter></b> + <layout class="ch.qos.logback.access.PatternLayout"> + <pattern> %h %l %u %t %r %s %b - </pattern> - </layout> - </appender> + </pattern> + </layout> + </appender> - <appender-ref ref="STDOUT" /> -</configuration></pre></div> + <appender-ref ref="STDOUT" /> +</configuration></pre></div> <p> We might imagine a slightly more complex use of filters to ensure the display of 404 errors, but @@ -740,34 +746,34 @@ </p> <em>Example 6.10: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator2.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <b><filter class="ch.qos.logback.core.filter.EvaluatorFilter"> - <evaluator name="Eval404"> - <expression>event.getStatusCode() == 404</expression> - </evaluator> - <OnMismatch>NEUTRAL</OnMismatch> - <OnMatch>ACCEPT</OnMatch> - </filter> - <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> - <evaluator name="EvalCSS"> - <expression>event.getRequestURI().contains("css")</expression> - </evaluator> - <OnMismatch>NEUTRAL</OnMismatch> - <OnMatch>DENY</OnMatch> - </filter></b> - <layout class="ch.qos.logback.access.PatternLayout"> - <pattern> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <b><filter class="ch.qos.logback.core.filter.EvaluatorFilter"> + <evaluator name="Eval404"> + <expression>event.getStatusCode() == 404</expression> + </evaluator> + <OnMismatch>NEUTRAL</OnMismatch> + <OnMatch>ACCEPT</OnMatch> + </filter> + <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> + <evaluator name="EvalCSS"> + <expression>event.getRequestURI().contains("css")</expression> + </evaluator> + <OnMismatch>NEUTRAL</OnMismatch> + <OnMatch>DENY</OnMatch> + </filter></b> + <layout class="ch.qos.logback.access.PatternLayout"> + <pattern> %h %l %u %t %r %s %b - </pattern> - </layout> - </appender> - - <appender-ref ref="STDOUT" /> -</configuration></pre></div> -<script src="../templates/footer.js"></script> -</div> + </pattern> + </layout> + </appender> + + <appender-ref ref="STDOUT" /> +</configuration></pre></div> + + </div> </body> </html> Modified: logback/trunk/logback-site/src/site/resources/manual/index.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/manual/index.html (original) +++ logback/trunk/logback-site/src/site/resources/manual/index.html Mon Feb 5 14:28:49 2007 @@ -16,7 +16,9 @@ <div id="right"> <script src="../templates/right.js"></script> </div> -<div id="content"> <h2>The logback manual</h2> +<div id="content"> + + <h2>The logback manual</h2> <p>The complete logback manual documents the latest version of logback framework. In over 100 pages and dozens of concrete @@ -25,15 +27,15 @@ <div> <ul> - <li>the overall logback architecture</li> - <li>discussion of best logback practices and anti-patterns</li> - <li>logback configuration scripts in XML format</li> - <li>appenders</li> - <li>layouts</li> - <li>filter chains</li> - <li>logback diagnostic contexts</li> - <li>logback default initialization</li> - <li>logback in Servlet Containers</li> + <li><p>the overall logback architecture</p></li> + <li><p>discussion of best logback practices and anti-patterns</p></li> + <li><p>logback configuration scripts in XML format</p></li> + <li><p>appenders</p></li> + <li><p>layouts</p></li> + <li><p>filter chains</p></li> + <li><p>logback diagnostic contexts</p></li> + <li><p>logback default initialization</p></li> + <li><p>logback in Servlet Containers</p></li> </ul> </div> @@ -41,8 +43,10 @@ <div class="highlight"> <p> If you wish to print chapters in this document, we recommend - that you do so using <a href="http://www.getfirefox.com">Firefox 2</a>, with <em>Adapt to - page size</em> enabled, or <a href="http://www.opera.com">Opera</a>. + that you do so using <a + href="http://www.getfirefox.com">Firefox 2</a>, with <em>Adapt to + page size</em> enabled, or <a + href="http://www.opera.com">Opera</a>. </p> <p> To run the examples provided in this book, you might have @@ -54,7 +58,7 @@ <p>The logback manual describes the logback API in considerable detail, including its features and design rationale. Authored by - Ceki G�lc� and S�bastien Pennec, the main + Ceki Gülcü and Sébastien Pennec, the main contributors to the logback project, the logback manual is intended for developers already familiar with the Java language but new to logback, as much as for experienced logback users. With @@ -66,35 +70,35 @@ <p>Without further ado, here are the contents of the manual:</p> <ul> - <li> + <li><p> <a href="introduction.html"><b>Chapter 1: Introduction to logback</b></a> - </li> - <li> + </p></li> + <li><p> <a href="architecture.html"><b>Chapter 2: Architecture</b></a> - </li> - <li> + </p></li> + <li><p> <a href="joran.html"><b>Chapter 3: Logback configuration with Joran</b></a> - </li> + </p></li> - <li> + <li><p> <a href="appenders.html"><b>Chapter 4: Appenders</b></a> - </li> + </p></li> - <li> + <li><p> <a href="layouts.html"><b>Chapter 5: Layouts</b></a> - </li> + </p></li> - <li> + <li><p> <a href="filters.html"><b>Chapter 6: Filter chains</b></a> - </li> + </p></li> - <li> + <li><p> <a href="mdc.html"><b>Chapter 7: Diagnostic Context</b></a> - </li> + </p></li> - <li> + <li><p> <a href="contextSelector.html"><b>Chapter 8: Context Selector</b></a> - </li> + </p></li> </ul> </div> Modified: logback/trunk/logback-site/src/site/resources/manual/introduction.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/manual/introduction.html (original) +++ logback/trunk/logback-site/src/site/resources/manual/introduction.html Mon Feb 5 14:28:49 2007 @@ -17,32 +17,36 @@ <script src="../templates/right.js"></script> </div> <div id="content"> - <h2>Introduction</h2> + <h2>Introduction</h2> <div class="author"> - Authors: Ceki G�lc�, S�bastien Pennec + Authors: Ceki Gülcü, Sébastien Pennec </div> - <table class="bodyTable"> - <tr class="a"> - <td> - <a 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"></img> + <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>Copyright © 2000-2006, QOS.ch</p> <p> - + <!--Creative Commons License--> This work is licensed under a - <a href="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + <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> @@ -53,7 +57,7 @@ <p> Logback is intended as a successor to the popular log4j project. - It was designed by Ceki G�lc�, the log4j founder. + It was designed by Ceki Gülcü, the log4j founder. It builds upon a decade long experience gained in designing industrial-strength logging systems. The resulting product, logback is faster with a smaller footprint than all @@ -81,7 +85,7 @@ </p> </div> - <a name="Requirements"></a> + <a name="Requirements" /> <h3>Requirements</h3> <p>Logback-classic module requires the presence @@ -102,8 +106,8 @@ public static void main(String[] args) { - Logger logger = LoggerFactory.getLogger("chapter1.HelloWorld1"); - logger.debug("Hello world."); + Logger logger = LoggerFactory.getLogger("chapter1.HelloWorld1"); + logger.debug("Hello world."); } }</pre></div> @@ -122,10 +126,10 @@ is assigned a <code>Logger</code> instance retreived by invoking the static method <code>getLogger</code> in the <code>LoggerFactory</code> class. - This logger is named "chapter1.HelloWorld1". The main method proceeds to call the - <code>debug</code> method of this logger passing "Hello World" as an argument. + This logger is named "chapter1.HelloWorld1". The main method proceeds to call the + <code>debug</code> method of this logger passing "Hello World" as an argument. We say that the main - method contains a logging statement of level debug with the message "Hello world". + method contains a logging statement of level debug with the message "Hello world". </p> <p> @@ -174,8 +178,8 @@ public class HelloWorld2 { public static void main(String[] args) { - Logger logger = LoggerFactory.getLogger("chapter1.HelloWorld2"); - logger.debug("Hello world."); + Logger logger = LoggerFactory.getLogger("chapter1.HelloWorld2"); + logger.debug("Hello world."); <b>LoggerStatusPrinter.printStatusInDefaultContext();</b> } }</pre></div> @@ -216,7 +220,7 @@ logging in your application. </p> - <ol type="1"> + <ol> <p>Configure the logback environment. You can do so in several more or less sophisticated ways. More on this later.</p> @@ -232,7 +236,7 @@ produce logging output on the configured appenders.</p> </ol> - <a name="BuildingLogback"></a> + <a name="BuildingLogback" /> <h3>Building logback</h3> <p> @@ -259,6 +263,11 @@ of the LGPL License. In particular you may not call the modified version <em>logback</em> or claim that it is endorsed by the QOS.ch. </p> + + + + + <script src="../templates/footer.js"></script> </div> </body> Modified: logback/trunk/logback-site/src/site/resources/manual/joran.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/manual/joran.html (original) +++ logback/trunk/logback-site/src/site/resources/manual/joran.html Mon Feb 5 14:28:49 2007 @@ -18,31 +18,35 @@ </div> <div id="content"> - <h2>Chapter 3: Logback configuration with Joran</h2> + <h2>Chapter 3: Logback configuration with Joran</h2> <div class="author"> - Authors: Ceki G�lc�, S�bastien Pennec + Authors: Ceki Gülcü, Sébastien Pennec </div> - <table class="bodyTable"> - <tr class="a"> - <td> - <a 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"></img> + <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>Copyright © 2000-2006, QOS.ch</p> <p> - + <!--Creative Commons License--> This work is licensed under a - <a href="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + <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> @@ -118,11 +122,11 @@ final static Logger logger = LoggerFactory.getLogger(MyApp1.class); public static void main(String[] args) { - logger.info("Entering application."); + logger.info("Entering application."); Foo foo = new Foo(); foo.doIt(); - logger.info("Exiting application."); + logger.info("Exiting application."); } }</pre></div> @@ -205,11 +209,11 @@ je.printStackTrace(); } - logger.info("Entering application."); + logger.info("Entering application."); Foo foo = new Foo(); foo.doIt(); - logger.info("Exiting application."); + logger.info("Exiting application."); } }</pre></div> @@ -222,20 +226,20 @@ </p> <em>Example 3.3: Basic configuration file (logback-examples/src/main/java/chapter3/sample0.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</Pattern> - </layout> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</Pattern> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p> Assuming the current directory is <em>logback-examples</em>, try running the @@ -262,20 +266,20 @@ </p> <em>Example 3.4: Basic configuration file using debug mode (logback-examples/src/main/java/chapter3/sample1.xml)</em> -<div class="source"><pre><configuration debug="true"> +<div class="source"><pre><configuration debug="true"> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</Pattern> - </layout> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</Pattern> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p> This should cause logback to print internal configuration messages in @@ -355,27 +359,27 @@ </p> <em>Example 3.5: Setting the level of a logger (logback-examples/src/main/java/chapter3/sample2.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</Pattern> - </layout> - </appender> - - <b><logger name="chapter3"> - <level value="INFO" /> - </logger></b> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</Pattern> + </layout> + </appender> + + <b><logger name="chapter3"> + <level value="INFO" /> + </logger></b> - <root> - <!-- The following level element is not necessary since the --> - <!-- level of the root level is set to DEBUG by default. --> - <level value="DEBUG" /> - <appender-ref ref="STDOUT" /> - </root> + <root> + <!-- The following level element is not necessary since the --> + <!-- level of the root level is set to DEBUG by default. --> + <level value="DEBUG" /> + <appender-ref ref="STDOUT" /> + </root> -</configuration></pre></div> +</configuration></pre></div> <p> This new configuration will yield the following output, when used with the @@ -393,33 +397,33 @@ </p> <em>Example 3.6: Setting the level of multiple loggers (logback-examples/src/main/java/chapter3/sample3.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern> %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n - </Pattern> - </layout> - </appender> - - <b><logger name="chapter3"> - <level value="INFO" /> - </logger> - - <logger name="chapter3.Foo"> - <level value="DEBUG" /> - </logger></b> - - <root> - <!-- The following level element is not necessary since the --> - <!-- level of the root level is set to DEBUG by default. --> - <level value="DEBUG" /> - <appender-ref ref="STDOUT" /> - </root> + </Pattern> + </layout> + </appender> + + <b><logger name="chapter3"> + <level value="INFO" /> + </logger> + + <logger name="chapter3.Foo"> + <level value="DEBUG" /> + </logger></b> + + <root> + <!-- The following level element is not necessary since the --> + <!-- level of the root level is set to DEBUG by default. --> + <level value="DEBUG" /> + <appender-ref ref="STDOUT" /> + </root> -</configuration></pre></div> +</configuration></pre></div> <p> Running <code>MyApp2</code> with this configuration file will result in the @@ -435,28 +439,28 @@ file, the logger settings, more specifically their levels, are summarized in the following table. </p> -<table class="bodyTable"> - <tr class="b"> +<table> + <tr> <th>Logger name</th> <th>Assigned Level</th> <th>Effective Level</th> </tr> - <tr class="a"> + <tr> <td>root</td> <td><code>DEBUG</code></td> <td><code>DEBUG</code></td> </tr> - <tr class="b"> + <tr> <td>chapter3</td> <td><code>INFO</code></td> <td><code>INFO</code></td> </tr> - <tr class="a"> + <tr> <td>chapter3.MyApp2</td> <td><code>null</code></td> <td><code>INFO</code></td> </tr> - <tr class="b"> + <tr> <td>chapter3.Foo</td> <td><code>DEBUG</code></td> <td><code>DEBUG</code></td> @@ -473,55 +477,55 @@ where the appenders are attached. The configuration file <em>sample4.xml</em> is a case in point: </p> <em>Example 3.7: Logger level sample (logback-examples/src/main/java/chapter3/sample4.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern> %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n - </Pattern> - </layout> - </appender> - - <b><logger name="chapter3"> - <level value="INFO" /> - </logger></b> - - <root> - <b><level value="OFF" /></b> - <appender-ref ref="STDOUT" /> - </root> + </Pattern> + </layout> + </appender> + + <b><logger name="chapter3"> + <level value="INFO" /> + </logger></b> + + <root> + <b><level value="OFF" /></b> + <appender-ref ref="STDOUT" /> + </root> -</configuration></pre></div> +</configuration></pre></div> <p> The following table lists the loggers and their level setting after applying the <em>sample4.xml</em> configuration file. </p> -<table class="bodyTable"> - <tr class="a"> +<table> + <tr> <th>Logger name</th> <th>Assigned Level</th> <th>Effective Level</th> </tr> - <tr class="b"> + <tr> <td>root</td> <td><code>OFF</code></td> <td><code>OFF</code></td> </tr> - <tr class="a"> + <tr> <td>chapter3</td> <td><code>INFO</code></td> <td><code>INFO</code></td> </tr> - <tr class="b"> + <tr> <td>chapter3.MyApp2</td> <td><code>null</code></td> <td><code>INFO</code></td> </tr> - <tr class="a"> + <tr> <td>chapter3.Foo</td> <td><code>null</code></td> <td><code>INFO</code></td> @@ -575,41 +579,41 @@ </p> <em>Example 3.8: Multiple loggers (logback-examples/src/main/java/chapter3/multiple.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="<b>FILE</b>" - class="ch.qos.logback.core.rolling.RollingFileAppender"> - <file>myApp.log</file> + <appender name="<b>FILE</b>" + class="ch.qos.logback.core.rolling.RollingFileAppender"> + <file>myApp.log</file> <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> + class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> + <FileNamePattern> myApp-%d{yyyy-MM-dd-HH-mm-ss}.log - </FileNamePattern> - </rollingPolicy> + </FileNamePattern> + </rollingPolicy> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern> %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> - </layout> - </appender> - - <appender name="<b>STDOUT</b>" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> + </Pattern> + </layout> + </appender> + + <appender name="<b>STDOUT</b>" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern> %msg%n - </Pattern> - </layout> - </appender> - - <root> - <level value="debug" /> - <b><appender-ref ref="FILE" /> - <appender-ref ref="STDOUT" /></b> - </root> -</configuration></pre></div> + </Pattern> + </layout> + </appender> + + <root> + <level value="debug" /> + <b><appender-ref ref="FILE" /> + <appender-ref ref="STDOUT" /></b> + </root> +</configuration></pre></div> <p> This configuration scripts defines two appenders called <em>FILE</em> and <em>STDOUT</em>. @@ -637,26 +641,26 @@ </p> <em>Example 3.9: Duplicate appender (logback-examples/src/main/java/chapter3/duplicate.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern> %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n - </Pattern> - </layout> - </appender> - - <logger name="chapter3"> - <appender-ref ref="STDOUT" /> - </logger> - - <root> - <level value="debug" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + </Pattern> + </layout> + </appender> + + <logger name="chapter3"> + <appender-ref ref="STDOUT" /> + </logger> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p> Running <code>MyApp2</code> with <em>duplicate.xml</em> will yield the following output: @@ -686,40 +690,40 @@ </p> <em>Example 3.10: Multiple appender (logback-examples/src/main/java/chapter3/restricted.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> - <file>myApp.log</file> + <appender name="FILE" + class="ch.qos.logback.core.rolling.RollingFileAppender"> + <file>myApp.log</file> <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> + class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> + <FileNamePattern> myApp-%d{yyyy-MM-dd-HH-mm-ss}.log - </FileNamePattern> - </rollingPolicy> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> + </FileNamePattern> + </rollingPolicy> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern> %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> - </layout> - </appender> - - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%msg%n</Pattern> - </layout> - </appender> - - <logger name="chapter3"> - <appender-ref ref="FILE" /> - </logger> - - <root> - <level value="debug" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + </Pattern> + </layout> + </appender> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%msg%n</Pattern> + </layout> + </appender> + + <logger name="chapter3"> + <appender-ref ref="FILE" /> + </logger> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p> In this example, the console appender will log all the messages (for all loggers in the system) @@ -736,40 +740,40 @@ </p> <em>Example 3.11: Additivity flag (logback-examples/src/main/java/chapter3/additivityFlag.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> - <file>foo.log</file> + <appender name="FILE" + class="ch.qos.logback.core.rolling.RollingFileAppender"> + <file>foo.log</file> <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> + class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> + <FileNamePattern> foo-%d{yyyy-MM-dd-HH-mm-ss}.log - </FileNamePattern> - </rollingPolicy> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> + </FileNamePattern> + </rollingPolicy> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern> %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> - </layout> - </appender> - - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%msg%n</Pattern> - </layout> - </appender> - - <logger name="chapter3.Foo" <b>additivity="false"</b>> - <appender-ref ref="FILE" /> - </logger> - - <root> - <level value="debug" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + </Pattern> + </layout> + </appender> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%msg%n</Pattern> + </layout> + </appender> + + <logger name="chapter3.Foo" <b>additivity="false"</b>> + <appender-ref ref="FILE" /> + </logger> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p> This example, the appender named <em>FILE</em> is attached to the <em>chapter3.Foo</em> @@ -797,7 +801,7 @@ and if not found there, it is then searched in system properties. The corresponding value replaces <em>${aKey}</em> sequence. For example, if <em>java.home</em> system property is set to <em>/home/xyz</em>, -then every occurrence of the sequence <em>c:\Program Files\Java\jdk1.5.0_10\jre</em> will be +then every occurrence of the sequence <em>${java.home}</em> will be interpreted as <em>/home/xyz</em>. </p> @@ -808,31 +812,31 @@ </p> <em>Example 3.12: Simple Variable substitution (logback-examples/src/main/java/chapter3/variableSubstitution1.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <b><substitutionProperty name="user.home.dir" value="/Users/seb" /></b> + <b><substitutionProperty name="user.home.dir" value="/Users/seb" /></b> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> - <b><file>${user.home.dir}/myApp.log</file></b> + <appender name="FILE" + class="ch.qos.logback.core.rolling.RollingFileAppender"> + <b><file>${user.home.dir}/myApp.log</file></b> <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> + class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> + <FileNamePattern> myApp-%d{yyyy-MM-dd-HH}.log - </FileNamePattern> - </rollingPolicy> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> + </FileNamePattern> + </rollingPolicy> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern> %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> - </layout> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="FILE" /> - </root> -</configuration></pre></div> + </Pattern> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="FILE" /> + </root> +</configuration></pre></div> <p> @@ -841,29 +845,29 @@ </p> <em>Example 3.13: System Variable substitution (logback-examples/src/main/java/chapter3/variableSubstitution2.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> - <b><file>${user.home.dir}/myApp.log</file></b> + <appender name="FILE" + class="ch.qos.logback.core.rolling.RollingFileAppender"> + <b><file>${user.home.dir}/myApp.log</file></b> <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> + class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> + <FileNamePattern> myApp-%d{yyyy-MM-dd-HH}.log - </FileNamePattern> - </rollingPolicy> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> + </FileNamePattern> + </rollingPolicy> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern> %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> - </layout> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="FILE" /> - </root> -</configuration></pre></div> + </Pattern> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="FILE" /> + </root> +</configuration></pre></div> <p> When many variables are used, it is often more convenient to create @@ -872,31 +876,31 @@ </p> <em>Example 3.14: Variable substitution using a separate file (logback-examples/src/main/java/chapter3/variableSubstitution3.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <substitutionProperty file="variables1.properties" /> + <substitutionProperty file="variables1.properties" /> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> - <b><file>${user.home.dir}/myApp.log</file></b> + <appender name="FILE" + class="ch.qos.logback.core.rolling.RollingFileAppender"> + <b><file>${user.home.dir}/myApp.log</file></b> <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> + class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> + <FileNamePattern> myApp-%d{yyyy-MM-dd-HH}.log - </FileNamePattern> - </rollingPolicy> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> + </FileNamePattern> + </rollingPolicy> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern> %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> - </layout> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="FILE" /> - </root> -</configuration></pre></div> + </Pattern> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="FILE" /> + </root> +</configuration></pre></div> <p> This configuration file contains a link to another file called <em>variables.properties</em>. @@ -929,34 +933,34 @@ </p> <em>Example 3.17: Variable substitution using a separate file (logback-examples/src/main/java/chapter3/variableSubstitution4.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <substitutionProperty file="variables1.properties" /> + <substitutionProperty file="variables1.properties" /> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> - <b><file>${destination}</file></b> + <appender name="FILE" + class="ch.qos.logback.core.rolling.RollingFileAppender"> + <b><file>${destination}</file></b> <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> + class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> + <FileNamePattern> myApp-%d{yyyy-MM-dd-HH}.log - </FileNamePattern> - </rollingPolicy> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> + </FileNamePattern> + </rollingPolicy> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern> %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> - </layout> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="FILE" /> - </root> -</configuration></pre></div> + </Pattern> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="FILE" /> + </root> +</configuration></pre></div> -<a name="Joran"></a> +<a name="Joran" /> <h2>Using Joran in your own application</h2> <p>As we've seen, logback relies on Joran, a @@ -997,7 +1001,8 @@ as importantly, the code of the DOMConfigurator consists of loops dealing with children elements containing many interspersed if/else statements. One could not help but notice that that particular code -reeked of redundancy. The <a href="http://jakarta.apache.org/commons/digester/">digester +reeked of redundancy. The <a +href="http://jakarta.apache.org/commons/digester/">digester project</a> has shown that it is possible to parse XML files using pattern matching rules. At parse time, digester will apply the rules that match previously stated patterns. Rule classes are usually quite @@ -1016,12 +1021,12 @@ and actions lies at the core of Joran. Quite remarkably, one can deal with quite complex requirements by using simple patterns, or more precisely with exact matches and wildcard matches. For example, the -pattern <em>a/b</em> will match a <code><b></code> element nested within -an <code><a></code> element but not a <code><c></code> element, -even if nested within a <code><b></code> element. It is also +pattern <em>a/b</em> will match a <code><b></code> element nested within +an <code><a></code> element but not a <code><c></code> element, +even if nested within a <code><b></code> element. It is also possible to match a particular XML element, regardless of its nesting level, by using the <em>*</em> wildcard character. For example, the pattern -<em>*/a</em> will match an <code><a></code> element at any nesting +<em>*/a</em> will match an <code><a></code> element at any nesting position within the document. Other types of patterns, for example <em>a/*</em>, are not currently supported by Joran. </p> @@ -1106,7 +1111,7 @@ <code>StatusManager</code>. </p> -<a name="helloWorld"></a> +<a name="helloWorld" /> <h3>A hello world example</h3> <p>The <em>logback-examples/src/main/java/chapter3/helloWorld/</em> directory includes a @@ -1119,7 +1124,7 @@ The <em>hello.xml</em> file contains only one element, without any other nested elements. The <a href="../xref/chapter3/helloWorld/HelloWorldAction.html"> <code>HelloWorldAction</code></a> class is -a trivial implementation: it only prints "Hello World" in the console when +a trivial implementation: it only prints "Hello World" in the console when it's <code>begin()</code> method is called. </p> <p> @@ -1151,7 +1156,7 @@ will be issued, displaying <em>Hello World</em> in the console. </p> -<a name="calculator"></a> +<a name="calculator" /> <h3>Collaborating actions</h3> <p> The <em>logback-examples/src/main/java/joran/calculator/</em> directory includes several actions @@ -1192,11 +1197,11 @@ <p>It contains the following elements:</p> <em>Example 3.18: Calculator configuration file (logback-examples/src/main/java/chapter3/calculator/calculator2.xml)</em> -<div class="source"><pre><computation name="toto"> - <literal value="7"/> - <literal value="3"/> +<div class="source"><pre><computation name="toto"> + <literal value="7"/> + <literal value="3"/> <add/> - <literal value="3"/> + <literal value="3"/> <multiply/> </computation></pre></div> <p> @@ -1218,14 +1223,14 @@ <em>calculator3.xml</em>:</p> <em>Example 3.19: Calculator configuration file (logback-examples/src/main/java/chapter3/calculator/calculator3.xml)</em> -<div class="source"><pre><computation name="toto"> +<div class="source"><pre><computation name="toto"> <computation> - <literal value="7"/> - <literal value="3"/> + <literal value="7"/> + <literal value="3"/> <add/> </computation> - <literal value="3"/> + <literal value="3"/> <multiply/> </computation></pre></div> @@ -1236,7 +1241,7 @@ of XML will guarantee that a value saved by one <code>begin()</code> will be consumed only by the matching <code>end()</code> method.</p> -<a name="newRule"></a> +<a name="newRule" /> <h3>New-rule action</h3> <p>Joran includes an action which allows the Joran interpreter to lean new rules on the fly while interpreting the XML file containing the @@ -1247,7 +1252,7 @@ <code>NewRuleCalculator</code></a> class contains the same setup as we have seen so far, but for one line:</p> -<div class="source"><pre>ruleStore.addRule(new Pattern("/computation/new-rule"), new NewRuleAction());</pre></div> +<source>ruleStore.addRule(new Pattern("/computation/new-rule"), new NewRuleAction());</source> <p>By adding this line, we ask Joran to allow new rules to be learnt at parsing time. It works pretty much like the other rules: it has a @@ -1260,31 +1265,31 @@ <p>Here is how new rules can be declared in an xml file:</p> -<div class="source"><pre><new-rule pattern="*/computation/literal" actionClass="chapter3.calculator.LiteralAction"/></pre></div> +<div class="source"><pre><new-rule pattern="*/computation/literal" actionClass="chapter3.calculator.LiteralAction"/></pre></div> <p>Using new rule declarations, the preceding example, involving the calculation, could be expressed this way:</p> <em>Example 3.20: Configuration file using new rules on the fly (logback-examples/src/main/java/chapter3/newrule/new-rule.xml)</em> -<div class="source"><pre><computation name="toto"> - <new-rule pattern="*/computation/literal" - actionClass="chapter3.calculator.LiteralAction"/> - <new-rule pattern="*/computation/add" - actionClass="chapter3.calculator.AddAction"/> - <new-rule pattern="*/computation/multiply" - actionClass="chapter3.calculator.MultiplyAction"/> +<div class="source"><pre><computation name="toto"> + <new-rule pattern="*/computation/literal" + actionClass="chapter3.calculator.LiteralAction"/> + <new-rule pattern="*/computation/add" + actionClass="chapter3.calculator.AddAction"/> + <new-rule pattern="*/computation/multiply" + actionClass="chapter3.calculator.MultiplyAction"/> <computation> - <literal value="7"/> - <literal value="3"/> + <literal value="7"/> + <literal value="3"/> <add/> </computation> - <literal value="3"/> + <literal value="3"/> <multiply/> </computation></pre></div> -<a name="implicit"></a> +<a name="implicit" /> <h3>Implicit actions </h3> <p>The rules defined thus far are called explicit rules because they require an explicit pattern, hence fixing the tag name of the elements @@ -1327,8 +1332,8 @@ instantiate the class specified in a nested component and attach it to the parent component by using setter method of the parent component and the nested element's name. Under certain circumstances, -a nested action needs to be applied to an element say <a> and also -to another element <b> nested within <a>. The current +a nested action needs to be applied to an element say <a> and also +to another element <b> nested within <a>. The current implementation of <code>NestedComponentIA</code> is capable of handling multiply nested elements requiring intervention by the same implicit action. @@ -1349,7 +1354,7 @@ <code>NOPAction</code></a> class does nothing. It is used to set the context of the <em>foo</em> element, using this line:</p> -<div class="source"><pre>ruleStore.addRule(new Pattern("*/foo"), new NOPAction());</pre></div> +<source>ruleStore.addRule(new Pattern("*/foo"), new NOPAction());</source> <p>After that, the implicit action, namely <a href="../xref/chapter3/implicit/PrintMeImplicitAction.html"> @@ -1357,7 +1362,7 @@ is added to the <code>RuleStore</code>. This is done by simply adding a new instance of the action to the <code>Joran interpreter</code></p> -<div class="source"><pre>ji.addImplicitAction(new PrintMeImplicitAction());</pre></div> +<source>ji.addImplicitAction(new PrintMeImplicitAction());</source> <p>When called, the <code>isApplicable()</code> method of <code>PrintMeImplicitAction</code> checks the value of the <em>printme</em> attribute. If the value is <code>true</code>, @@ -1368,13 +1373,13 @@ <em>Example 3.21: Usage of implicit rules (logback-examples/src/main/java/chapter3/implicit/implicit1.xml)</em> <div class="source"><pre><foo> - <xyz printme="true"> - <abc printme="true"/> + <xyz printme="true"> + <abc printme="true"/> </xyz> <xyz/> - <foo printme="true"/> + <foo printme="true"/> </foo></pre></div> @@ -1390,10 +1395,10 @@ <p>Running the example yields the following output:</p> -<div class="source"><pre>Element <xyz> asked to be printed. -Element <abc> asked to be printed. +<div class="source"><pre>Element <xyz> asked to be printed. +Element <abc> asked to be printed. ERROR in ch.qos.logback.core.joran.spi.ExecutionContext@1c5c1 - no applicable action \ -for <xyz>, current pattern is [/foo/xyz]</pre></div> +for <xyz>, current pattern is [/foo/xyz]</pre></div> <p>The last line was printed because of a call to <code>StatusPrinter</code> at the end of the main class.</p> @@ -1404,6 +1409,12 @@ thousands of elements. </p> + + + + + + <script src="../templates/footer.js"></script> </div> </body> Modified: logback/trunk/logback-site/src/site/resources/manual/layouts.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/manual/layouts.html (original) +++ logback/trunk/logback-site/src/site/resources/manual/layouts.html Mon Feb 5 14:28:49 2007 @@ -16,32 +16,38 @@ <div id="right"> <script src="../templates/right.js"></script> </div> -<div id="content"> <h2>Chapter 5: Layouts</h2> +<div id="content"> + + <h2>Chapter 5: Layouts</h2> <div class="author"> - Authors: Ceki G�lc�, S�bastien Pennec + Authors: Ceki Gülcü, Sébastien Pennec </div> - <table class="bodyTable"> - <tr class="a"> - <td> - <a 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"></img> + <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>Copyright © 2000-2006, QOS.ch</p> <p> - + <!--Creative Commons License--> This work is licensed under a - <a href="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + <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> @@ -71,7 +77,7 @@ an event (of any type) and returns a String. A synopsis of the <code>Layout</code> interface is shown below. </p> - <div class="source"><pre>public interface Layout<E> extends ContextAware, LifeCycle { + <div class="source"><pre>public interface Layout<E> extends ContextAware, LifeCycle { String doLayout(E event); String getHeader(); @@ -114,18 +120,18 @@ import ch.qos.logback.classic.spi.LoggingEvent; import ch.qos.logback.core.LayoutBase; -public class MySampleLayout extends LayoutBase<LoggingEvent> { +public class MySampleLayout extends LayoutBase<LoggingEvent> { public String doLayout(LoggingEvent event) { StringBuffer sbuf = new StringBuffer(128); sbuf.append(event.getTimeStamp() - LoggingEvent.getStartTime()); - sbuf.append(" "); + sbuf.append(" "); sbuf.append(event.getLevel()); - sbuf.append(" ["); + sbuf.append(" ["); sbuf.append(event.getThreadName()); - sbuf.append("] "); + sbuf.append("] "); sbuf.append(event.getLoggerRemoteView().getName()); - sbuf.append(" - "); + sbuf.append(" - "); sbuf.append(event.getFormattedMessage()); sbuf.append(LINE_SEP); return sbuf.toString(); @@ -143,7 +149,7 @@ the developer to concentrate on the formatting she expects from her <code>Layout</code>. Note that the <code>LayoutBase</code> class is generic. By extending it, we precise the type that it will - have to handle, by adding <em><LoggingEvent></em> after its declaration. + have to handle, by adding <em><LoggingEvent></em> after its declaration. </p> <p>The marginally more interesting <code>doLayout(LoggingEvent event)</code> @@ -157,7 +163,7 @@ In the above listing of the <code>Layout</code> class, we had omitted the class static <code>LINE_SEP</code> field which is simply assigned the value returned by - <code>System.getProperty("line.separator")</code> + <code>System.getProperty("line.separator")</code> method. After adding system dependent line separator character(s), the format method returns the string buffer as a String. @@ -172,18 +178,18 @@ <em>Example 5.0: Configuration of MySampleLayout (logback-examples/src/main/java/chapter5/sampleLayoutConfig.xml)</em> -<div class="source"><pre><configuration> - - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <b><layout class="chapter5.MySampleLayout" /></b> - </appender> +<div class="source"><pre><configuration> - <root> - <level value="debug" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <b><layout class="chapter5.MySampleLayout" /></b> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p>The sample application <a href="../xref/chapter5/SampleLogging.html"> <code>chapter5.SampleLogging</code></a> configures logback with the @@ -223,7 +229,7 @@ import ch.qos.logback.classic.spi.LoggingEvent; import ch.qos.logback.core.LayoutBase; -public class MySampleLayout2 extends LayoutBase<LoggingEvent> { +public class MySampleLayout2 extends LayoutBase<LoggingEvent> { String prefix = null; boolean printThreadName = true; @@ -239,20 +245,20 @@ public String doLayout(LoggingEvent event) { StringBuffer sbuf = new StringBuffer(128); <b>if (prefix != null) { - sbuf.append(prefix + ": "); + sbuf.append(prefix + ": "); }</b> sbuf.append(event.getTimeStamp() - LoggingEvent.getStartTime()); - sbuf.append(" "); + sbuf.append(" "); sbuf.append(event.getLevel()); <b>if (printThreadName) { - sbuf.append(" ["); + sbuf.append(" ["); sbuf.append(event.getThreadName()); - sbuf.append("] "); + sbuf.append("] "); } else { - sbuf.append(" "); + sbuf.append(" "); }</b> sbuf.append(event.getLoggerRemoteView().getName()); - sbuf.append(" - "); + sbuf.append(" - "); sbuf.append(event.getFormattedMessage()); sbuf.append(LINE_SEP); return sbuf.toString(); @@ -263,21 +269,21 @@ the two setter methods are the only addition to the original class. Yet, it is sufficient to allow the user to configure these attributes, as shown in the configuration file below:</p> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="chapter5.MySampleLayout2"> - <b><prefix>MyPrefix</prefix> - <printThreadName>false</printThreadName></b> - </layout> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="chapter5.MySampleLayout2"> + <b><prefix>MyPrefix</prefix> + <printThreadName>false</printThreadName></b> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p> Note that the <code>PrintThreadName</code> attribute is a boolean @@ -286,7 +292,7 @@ </p> - <a name="PatternLayout"></a> + <a name="PatternLayout" /> <h3>PatternLayout</h3> <p> @@ -331,33 +337,33 @@ public class PatternSample { static public void main(String[] args) throws Exception { - Logger rootLogger = (Logger)LoggerFactory.getLogger("root"); + Logger rootLogger = (Logger)LoggerFactory.getLogger("root"); <b>PatternLayout layout = new PatternLayout(); - layout.setPattern("%-5level [%thread]: %message%n"); + layout.setPattern("%-5level [%thread]: %message%n"); layout.start();</b> - ConsoleAppender<LoggingEvent> appender = new ConsoleAppender<LoggingEvent>(); + ConsoleAppender<LoggingEvent> appender = new ConsoleAppender<LoggingEvent>(); appender.setContext(rootLogger.getLoggerContext()); appender.setLayout(layout); appender.start(); rootLogger.addAppender(appender); - rootLogger.debug("Message 1"); - rootLogger.warn("Message 2"); + rootLogger.debug("Message 1"); + rootLogger.warn("Message 2"); } }</pre></div> <p> - The conversion pattern is set to be <b>"%-5level [%thread]: - %message%n"</b>. Running PatternSample will yield the following + The conversion pattern is set to be <b>"%-5level [%thread]: + %message%n"</b>. Running PatternSample will yield the following output on the console. </p> <div class="source"><pre>DEBUG [main]: Message 1 WARN [main]: Message 2</pre></div> <p> - Note that in the conversion pattern <b>"%-5level [%thread]: - %message%n"</b> there is no explicit separator between literal + Note that in the conversion pattern <b>"%-5level [%thread]: + %message%n"</b> there is no explicit separator between literal text and conversion specifiers. When parsing a conversion pattern, <code>PatternLayout</code> @@ -386,16 +392,16 @@ column, they should be considered as aliases. </p> - <table class="bodyTable"> + <table border="1" CELLPADDING="8"> <th>Conversion Word</th> <th>Effect</th> - <tr class="b"> - <td> - <b>c</b>{<em>length</em>} <br></br> - <b>l</b>{<em>length</em>} <br></br> - <b>lo</b>{<em>length</em>} <br></br> - <b>logger</b>{<em>length</em>} <br></br> + <tr> + <td align="center"> + <b>c</b>{<em>length</em>} <br /> + <b>l</b>{<em>length</em>} <br /> + <b>lo</b>{<em>length</em>} <br /> + <b>logger</b>{<em>length</em>} <br /> </td> <td> @@ -412,36 +418,36 @@ <p>The next table should clarify the matter.</p> - <table class="bodyTable"> - <tr class="a"> + <table BORDER="1" CELLPADDING="8"> + <tr> <th>Conversion Pattern</th> <th>Logger name</th> <th>Result</th> </tr> - <tr class="b"> + <tr> <td>%logger</td> <td>mainPackage.sub.sample.Bar</td> <td>mainPackage.sub.sample.Bar</td> </tr> - <tr class="a"> + <tr> <td>%logger{10}</td> <td>mainPackage.sub.sample.Bar</td> <td>m.s.s.Bar</td> </tr> - <tr class="b"> + <tr> <td>%logger{15}</td> <td>mainPackage.sub.sample.Bar</td> <td>m.s.sample.Bar</td> </tr> - <tr class="a"> + <tr> <td>%logger{16}</td> <td>mainPackage.sub.sample.Bar</td> <td>m.sub.sample.Bar</td> </tr> - <tr class="b"> + <tr> <td>%logger{26}</td> <td>mainPackage.sub.sample.Bar</td> <td>mainPackage.sub.sample.Bar</td> @@ -449,10 +455,10 @@ </table> </td> </tr> - <tr class="a"> - <td> - <b>C</b>{<em>length</em>} <br></br> - <b>class</b>{<em>length</em>} <br></br> + <tr> + <td align="center"> + <b>C</b>{<em>length</em>} <br /> + <b>class</b>{<em>length</em>} <br /> </td> <td> @@ -477,10 +483,10 @@ </td> </tr> - <tr class="b"> - <td> - <b>d</b>{<em>pattern</em>} <br></br> - <b>date</b>{<em>pattern</em>} <br></br> + <tr> + <td align="center"> + <b>d</b>{<em>pattern</em>} <br /> + <b>date</b>{<em>pattern</em>} <br /> </td> <td> <p>Used to output the date of the logging event. @@ -489,39 +495,39 @@ <p>The option admits the same syntax as the time pattern string of the <code>java.text.SimpleDateFormat</code>.</p> <p>A shortcut to the ISO8601 format is available by - specifying the String <em>"ISO8601"</em> in the braces. If no option is set, - the converter uses <em>"ISO8601"</em> as the default value.</p> + specifying the String <em>"ISO8601"</em> in the braces. If no option is set, + the converter uses <em>"ISO8601"</em> as the default value.</p> <p>Here are some sample option values. They assume that the actual date is Friday 20th of October, 2006 and that the author finished his meal a short while ago.</p> - <table class="bodyTable"> - <tr class="a"> + <table BORDER="1" CELLPADDING="8"> + <tr> <th>Conversion Pattern</th> <th>Result</th> </tr> - <tr class="b"> + <tr> <td>%date</td> <td>2006-10-20 14:46:49,812</td> </tr> - <tr class="a"> + <tr> <td>%date{ISO8601}</td> <td>2006-10-20 14:46:49,812</td> </tr> - <tr class="b"> + <tr> <td>%date{HH:mm:ss.SSS}</td> <td>14:46:49.812</td> </tr> - <tr class="a"> - <td>%date{dd�MMM�yyyy�;HH:mm:ss.SSS}</td> + <tr> + <td>%date{dd MMM yyyy ;HH:mm:ss.SSS}</td> <td>20 oct. 2006;14:46:49.812 </td> </tr> </table> </td> </tr> - <tr class="b"> - <td> + <tr> + <td align="center"> <b>F / file</b> </td> @@ -538,8 +544,8 @@ </td> </tr> - <tr class="a"> - <td> + <tr> + <td align="center"> <b>caller{depth}</b> <b>caller{depth, evaluator-1, ... evaluator-n}</b> </td> @@ -586,8 +592,8 @@ </td> </tr> - <tr class="b"> - <td> + <tr> + <td align="center"> <b>L / line</b> </td> @@ -605,8 +611,8 @@ </tr> - <tr class="a"> - <td> + <tr> + <td align="center"> <b>m / msg / message</b> </td> <td> @@ -615,8 +621,8 @@ </td> </tr> - <tr class="b"> - <td> + <tr> + <td align="center"> <b>M / method</b> </td> @@ -633,8 +639,8 @@ </td> </tr> - <tr class="a"> - <td> + <tr> + <td align="center"> <b>n</b> </td> @@ -646,7 +652,7 @@ <p> This conversion word offers practically the same performance as using non-portable line - separator strings such as "\n", or "\r\n". Thus, + separator strings such as "\n", or "\r\n". Thus, it is the preferred way of specifying a line separator. </p> @@ -654,16 +660,16 @@ </tr> - <tr class="b"> - <td> + <tr> + <td align="center"> <b>p / le / level</b> </td> <td>Used to output the level of the logging event.</td> </tr> - <tr class="a"> + <tr> - <td> + <td align="center"> <b>r / relative</b> </td> @@ -675,8 +681,8 @@ </tr> - <tr class="b"> - <td> + <tr> + <td align="center"> <b>t / thread</b> </td> @@ -687,10 +693,10 @@ </tr> - <tr class="a"> - <td> - <b>X</b>{<em>key</em>} <br></br> - <b>mdc</b>{<em>key</em>} <br></br> + <tr> + <td align="center"> + <b>X</b>{<em>key</em>} <br /> + <b>mdc</b>{<em>key</em>} <br /> </td> <td> @@ -711,12 +717,13 @@ <p> If no option is given, then the entire content of the MDC will be output in the format - "key1=val1, key2=val2". + "key1=val1, key2=val2". </p> <p> See - <a href="http://logback.qos.ch/apidocs/ch/qos/logback/classic/MDC.html"> + <a + href="http://logback.qos.ch/apidocs/ch/qos/logback/classic/MDC.html"> MDC </a> class for more details. @@ -724,10 +731,10 @@ </td> </tr> - <tr class="b"> - <td> - <b>ex</b>{<em>length</em>} <br></br> - <b>throwable</b>{<em>length</em>} <br></br> + <tr> + <td align="center"> + <b>ex</b>{<em>length</em>} <br /> + <b>throwable</b>{<em>length</em>} <br /> <b>ex{length, evaluator-1, ..., evaluator-n}</b> <b>throwable{length, evaluator-1, ..., evaluator-n}</b> </td> @@ -749,31 +756,31 @@ <p>Here are some examples:</p> - <table class="bodyTable"> - <tr class="a"> + <table BORDER="1" CELLPADDING="8"> + <tr> <th>Conversion Pattern</th> <th>Result</th> </tr> - <tr class="b"> + <tr> <td>%ex</td> <td><pre>mainPackage.foo.bar.TestException: Houston we have a problem at mainPackage.foo.bar.TestThrower.fire(TestThrower.java:22) at mainPackage.foo.bar.TestThrower.readyToLaunch(TestThrower.java:17) at mainPackage.ExceptionLauncher.main(ExceptionLauncher.java:38)</pre></td> </tr> - <tr class="a"> + <tr> <td>%ex{short}</td> <td><pre>mainPackage.foo.bar.TestException: Houston we have a problem at mainPackage.foo.bar.TestThrower.fire(TestThrower.java:22)</pre></td> </tr> - <tr class="b"> + <tr> <td>%ex{full}</td> <td><pre>mainPackage.foo.bar.TestException: Houston we have a problem at mainPackage.foo.bar.TestThrower.fire(TestThrower.java:22) at mainPackage.foo.bar.TestThrower.readyToLaunch(TestThrower.java:17) at mainPackage.ExceptionLauncher.main(ExceptionLauncher.java:38)</pre></td> </tr> - <tr class="a"> + <tr> <td>%ex{2}</td> <td><pre>mainPackage.foo.bar.TestException: Houston we have a problem at mainPackage.foo.bar.TestThrower.fire(TestThrower.java:22) @@ -792,8 +799,8 @@ </td> </tr> - <tr class="b"> - <td> + <tr> + <td align="center"> <b>marker</b> </td> @@ -811,9 +818,9 @@ </p> </td> </tr> - <tr class="a"> + <tr> - <td> + <td align="center"> <b>%</b> </td> @@ -872,48 +879,48 @@ conversion specifier. </p> - <table class="bodyTable"> + <table BORDER="1" CELLPADDING="8"> <th>Format modifier</th> <th>Left justify</th> <th>Minimum width</th> <th>Maximum width</th> <th>Comment</th> - <tr class="b"> - <td>%20logger</td> - <td>false</td> - <td>20</td> - <td>none</td> + <tr> + <td align="center">%20logger</td> + <td align="center">false</td> + <td align="center">20</td> + <td align="center">none</td> <td> Left pad with spaces if the category name is less than 20 characters long. </td> </tr> - <tr class="a"> - <td>%-20logger</td> - <td>true</td> - <td>20</td> - <td>none</td> + <tr> + <td align="center">%-20logger</td> + <td align="center">true</td> + <td align="center">20</td> + <td align="center">none</td> <td> Right pad with spaces if the logger name is less than 20 characters long. </td> </tr> - <tr class="b"> - <td>%.30logger</td> - <td>NA</td> - <td>none</td> - <td>30</td> + <tr> + <td align="center">%.30logger</td> + <td align="center">NA</td> + <td align="center">none</td> + <td align="center">30</td> <td> Truncate from the beginning if the logger name is longer than 30 characters. </td> </tr> - <tr class="a"> - <td>%20.30logger</td> - <td>false</td> - <td>20</td> - <td>30</td> + <tr> + <td align="center">%20.30logger</td> + <td align="center">false</td> + <td align="center">20</td> + <td align="center">30</td> <td> Left pad with spaces if the logger name is shorter than 20 characters. However, if logger name is @@ -921,11 +928,11 @@ beginning. </td> </tr> - <tr class="b"> - <td>%-20.30logger</td> - <td>true</td> - <td>20</td> - <td>30</td> + <tr> + <td align="center">%-20.30logger</td> + <td align="center">true</td> + <td align="center">20</td> + <td align="center">30</td> <td> Right pad with spaces if the logger name is shorter than 20 characters. However, if logger name is @@ -933,11 +940,11 @@ <em>beginning</em>. </td> </tr> - <tr class="a"> - <td>%.-30logger</td> - <td>NA</td> - <td>none</td> - <td>30</td> + <tr> + <td align="center">%.-30logger</td> + <td align="center">NA</td> + <td align="center">none</td> + <td align="center">30</td> <td> Truncate from the <em>end</em> if the logger name is longer than 30 characters. @@ -948,29 +955,29 @@ <p>Here are some examples of the format modifier truncation:</p> - <table class="bodyTable"> + <table BORDER="1" CELLPADDING="8"> <th>Format modifier</th> <th>Logger name</th> <th>Result</th> - <tr class="b"> - <td>[%-20.20logger]</td> - <td>main.Name</td> - <td><pre>[main.Name ]</pre></td> - </tr> - <tr class="a"> - <td>[%20.-20logger]</td> - <td>main.Name</td> - <td><pre>[ main.Name]</pre></td> - </tr> - <tr class="b"> - <td>[%-10.10logger]</td> - <td>main.foo.foo.bar.Name</td> - <td><pre>[o.bar.Name]</pre></td> - </tr> - <tr class="a"> - <td>[%10.-10logger]</td> - <td>main.foo.foo.bar.Name</td> - <td><pre>[main.foo.f]</pre></td> + <tr> + <td align="center">[%-20.20logger]</td> + <td align="center">main.Name</td> + <td align="center"><pre>[main.Name ]</pre></td> + </tr> + <tr> + <td align="center">[%20.-20logger]</td> + <td align="center">main.Name</td> + <td align="center"><pre>[ main.Name]</pre></td> + </tr> + <tr> + <td align="center">[%-10.10logger]</td> + <td align="center">main.foo.foo.bar.Name</td> + <td align="center"><pre>[o.bar.Name]</pre></td> + </tr> + <tr> + <td align="center">[%10.-10logger]</td> + <td align="center">main.foo.foo.bar.Name</td> + <td align="center"><pre>[main.foo.f]</pre></td> </tr> </table> @@ -988,12 +995,12 @@ simply adds the evaluator names to the option list, as shown below:</p> <div class="source"><pre> - <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <param name="Pattern" value="%-4relative [%thread] %-5level - %msg%n \ - <b>%caller{2, DISP_CALLER_EVAL, OTHER_EVAL_NAME, THIRD_EVAL_NAME}</b>" /> - </layout> - </appender></pre></div> + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <param name="Pattern" value="%-4relative [%thread] %-5level - %msg%n \ + <b>%caller{2, DISP_CALLER_EVAL, OTHER_EVAL_NAME, THIRD_EVAL_NAME}</b>" /> + </layout> + </appender></pre></div> @@ -1037,24 +1044,24 @@ Example 5.2: Sample usage of EventEvaluators (logback-examples/src/main/java/chapter5/callerEvaluatorConfig.xml) </em> - <div class="source"><pre><configuration> - <b><evaluator name="DISP_CALLER_EVAL"> - <Expression>logger.getName().contains("chapter5") &amp;&amp; \ - message.contains("who calls thee")</Expression> - </evaluator></b> - - <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <param name="Pattern" value="%-4relative [%thread] %-5level - %msg%n \ - <b>%caller{2, DISP_CALLER_EVAL}</b>" /> - </layout> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + <div class="source"><pre><configuration> + <b><evaluator name="DISP_CALLER_EVAL"> + <Expression>logger.getName().contains("chapter5") &amp;&amp; \ + message.contains("who calls thee")</Expression> + </evaluator></b> + + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <param name="Pattern" value="%-4relative [%thread] %-5level - %msg%n \ + <b>%caller{2, DISP_CALLER_EVAL}</b>" /> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p>Please note that the & value cannot be written like one would do in a java class, because of XML encoding rules.</p> <p>Let us test this configuration with the following code.</p> @@ -1089,9 +1096,9 @@ for (int i = 0; i < 5; i++) { if (i == 3) { - logger.debug("who calls thee?"); + logger.debug("who calls thee?"); } else { - logger.debug("I know me " + i); + logger.debug("I know me " + i); } } } @@ -1162,10 +1169,10 @@ } for (int i = 0; i < 5; i++) { if (i == 3) { - logger.debug("logging statement " + i, new TestException( - "do not display this")); + logger.debug("logging statement " + i, new TestException( + "do not display this")); } else { - logger.debug("logging statement " + i, new Exception("display")); + logger.debug("logging statement " + i, new Exception("display")); } } } @@ -1176,27 +1183,27 @@ Example 5.3: Sample usage of EventEvaluators (logback-examples/src/main/java/chapter5/exceptionEvaluatorConfig.xml) </em> - <div class="source"><pre><configuration> + <div class="source"><pre><configuration> - <b><evaluator name="DISPLAY_EX_EVAL"> - <Expression>throwable != null && throwable instanceof \ - chapter5.TestException</Expression> - </evaluator></b> + <b><evaluator name="DISPLAY_EX_EVAL"> + <Expression>throwable != null && throwable instanceof \ + chapter5.TestException</Expression> + </evaluator></b> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <param name="Pattern" - value="%-4relative [%thread] %-5level - %msg \ - <b>%ex{full, DISPLAY_EX_EVAL}</b>%n" /> - </layout> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <param name="Pattern" + value="%-4relative [%thread] %-5level - %msg \ + <b>%ex{full, DISPLAY_EX_EVAL}</b>%n" /> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p> With this configuration, each time an instance of the @@ -1235,10 +1242,10 @@ public class MySampleConverter extends ClassicConverter { - private static final String END_COLOR = "\u001b[m"; + private static final String END_COLOR = "\u001b[m"; - private static final String ERROR_COLOR = "\u001b[0;31m"; - private static final String WARN_COLOR = "\u001b[0;33m"; + private static final String ERROR_COLOR = "\u001b[0;31m"; + private static final String WARN_COLOR = "\u001b[0;33m"; @Override <b>public String convert(LoggingEvent event) { @@ -1260,7 +1267,7 @@ case Level.WARN_INT: return WARN_COLOR; default: - return ""; + return ""; } } } @@ -1276,22 +1283,22 @@ conversion word in the configuration file, as shown below:</p> <em> Example 5.4: Sample Converter Example (src/main/java/chapter5/mySampleConverterConfig.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <b><conversionRule conversionWord="sample" converterClass="chapter5.MySampleConverter" /></b> + <b><conversionRule conversionWord="sample" converterClass="chapter5.MySampleConverter" /></b> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <b><Pattern>%-4relative [%thread] %sample - %msg%n</Pattern></b> - </layout> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <b><Pattern>%-4relative [%thread] %sample - %msg%n</Pattern></b> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> <p>In this configuration file, once the new conversion word has been declared, we just use it within a <code>PatternLayout</code> pattern element, as if @@ -1304,7 +1311,7 @@ the use of options, in her custom <code>Converter</code> objects. </p> - <a name="ClassicHTMLLayout"></a> + <a name="ClassicHTMLLayout"/> <h3>HTMLLayout</h3> <p><a href="../xref/ch/qos/logback/classic/html/HTMLLayout.html"> <code>HTMLLayout</code></a> outputs events in an HTML table. Each row of the table corresponds to a @@ -1312,7 +1319,7 @@ <p>Here is a sample of the output that can be obtained using <code>HTMLLayout</code> along with the default CSS stylesheet:</p> - <img src="images/chapter5/htmlLayout1.gif" alt="HTML Layout Sample Image"></img> + <img src="images/chapter5/htmlLayout1.gif" alt="HTML Layout Sample Image"/> <p> The content of the table columns are specified using a @@ -1364,13 +1371,13 @@ page. In that case, the following xml element can be nested into the <code><layout></code> element. </p> -<div class="source"><pre><layout> +<div class="source"><pre><layout> ... - <cssBuilder class="ch.qos.logback.core.html.UrlCssBuilder"> - <param name="url" value="path_to_StyleFile.css" /> - </cssBuilder> + <cssBuilder class="ch.qos.logback.core.html.UrlCssBuilder"> + <param name="url" value="path_to_StyleFile.css" /> + </cssBuilder> ... -</layout></pre></div> +</layout></pre></div> <p>In case one does not want to customize the html output, an internal CSS style is used.</p> @@ -1385,19 +1392,19 @@ the following configuration would be typical. </p> <div class="source"><pre><configuration> - <appender name="SMTP" class="ch.qos.logback.classic.net.SMTPAppender"> - <layout class="ch.qos.logback.classic.html.HTMLLayout"> - <param name="pattern" value="%relative%thread%mdc%level%class%msg" /> + <appender name="SMTP" class="ch.qos.logback.classic.net.SMTPAppender"> + <layout class="ch.qos.logback.classic.html.HTMLLayout"> + <param name="pattern" value="%relative%thread%mdc%level%class%msg" /> </layout> - <param name="From" value="sender.email@domain.net" /> - <param name="SMTPHost" value="mail.domain.net" /> - <param name="Subject" value="LastEvent: %class - %msg" /> - <param name="To" value="destination.email@domain.net" /> + <param name="From" value="sender.email@domain.net" /> + <param name="SMTPHost" value="mail.domain.net" /> + <param name="Subject" value="LastEvent: %class - %msg" /> + <param name="To" value="destination.email@domain.net" /> </appender> <root> - <level value="debug" /> - <appender-ref ref="SMTP" /> + <level value="debug" /> + <appender-ref ref="SMTP" /> </root> </configuration></pre></div> @@ -1405,27 +1412,27 @@ case, one can specify a rolling policy to archive log messages automatically. One real world example could use the configuration below.</p> -<div class="source"><pre><configuration> - <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> - <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <ActiveFileName>lastLogEntries.html</ActiveFileName> - <FileNamePattern>logEntries.%d{yyyy-MM-dd}.log</FileNamePattern> - </rollingPolicy> +<div class="source"><pre><configuration> + <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> + <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> + <ActiveFileName>lastLogEntries.html</ActiveFileName> + <FileNamePattern>logEntries.%d{yyyy-MM-dd}.log</FileNamePattern> + </rollingPolicy> - <layout class="ch.qos.logback.classic.html.HTMLLayout"> - <cssBuilder class="ch.qos.logback.core.html.UrlCssBuilder"> - <url>address_of_a_custom_stylesheet.css</url> - </cssBuilder> - <Pattern>%relative%thread%mdc%level%logger%msg</Pattern> - <b><Title>Logging Events</Title></b> - </layout> - </appender> - - <root> - <level value="debug" /> - <appender-ref ref="FILE" /> - </root> -</configuration></pre></div> + <layout class="ch.qos.logback.classic.html.HTMLLayout"> + <cssBuilder class="ch.qos.logback.core.html.UrlCssBuilder"> + <url>address_of_a_custom_stylesheet.css</url> + </cssBuilder> + <Pattern>%relative%thread%mdc%level%logger%msg</Pattern> + <b><Title>Logging Events</Title></b> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="FILE" /> + </root> +</configuration></pre></div> <h2>Logback access</h2> @@ -1437,7 +1444,7 @@ <p>Writing a custom <code>Layout</code> for logback access is nearly identical as to writing a <code>Layout</code> for the classic module.</p> - <a name="AccessPatternLayout"></a> + <a name="AccessPatternLayout" /> <h3>PatternLayout</h3> <p>Access' <a href="../xref/ch/qos/logback/access/PatternLayout.html"> <code>PatternLayout</code></a> work the exact same way as it's classic counterpart. @@ -1448,62 +1455,62 @@ <p>Here are the conversion specifier one can use with logback access <code>PatternLayout</code>.</p> - <table class="bodyTable"> - <th>Conversion Word</th> - <th>Effect</th> + <table border="1" CELLPADDING="8"> + <th align="center">Conversion Word</th> + <th align="center">Effect</th> - <tr class="b"> - <td><b>a / remoteIP</b></td> + <tr> + <td align="center"><b>a / remoteIP</b></td> <td> <p> Remote IP address. </p> </td> </tr> - <tr class="a"> - <td><b>A / localIP</b></td> + <tr> + <td align="center"><b>A / localIP</b></td> <td> <p> Local IP address. </p> </td> </tr> - <tr class="b"> - <td><b>b / B / byteSent</b></td> + <tr> + <td align="center"><b>b / B / byteSent</b></td> <td> <p> Response's content length. </p> </td> </tr> - <tr class="a"> - <td><b>h / clientHost</b></td> + <tr> + <td align="center"><b>h / clientHost</b></td> <td> <p> Remote host. </p> </td> </tr> - <tr class="b"> - <td><b>H / protocol</b></td> + <tr> + <td align="center"><b>H / protocol</b></td> <td> <p> Request protocol. </p> </td> </tr> - <tr class="a"> - <td><b>l</b></td> + <tr> + <td align="center"><b>l</b></td> <td> <p> Remote log name. In logback-access, this converter always - returns the value "-". + returns the value "-". </p> </td> </tr> - <tr class="b"> - <td><b>reqParameter{paramName}</b></td> + <tr> + <td align="center"><b>reqParameter{paramName}</b></td> <td> <p> Parameter of the response. @@ -1514,8 +1521,8 @@ displays the corresponding parameter.</p> </td> </tr> - <tr class="a"> - <td><b>i{header} / header{header}</b></td> + <tr> + <td align="center"><b>i{header} / header{header}</b></td> <td> <p> Request header. @@ -1528,32 +1535,32 @@ </p> </td> </tr> - <tr class="b"> - <td><b>m / requestMethod</b></td> + <tr> + <td align="center"><b>m / requestMethod</b></td> <td> <p> Request method. </p> </td> </tr> - <tr class="a"> - <td><b>r / requestURL</b></td> + <tr> + <td align="center"><b>r / requestURL</b></td> <td> <p> URL requested. </p> </td> </tr> - <tr class="b"> - <td><b>s / statusCode</b></td> + <tr> + <td align="center"><b>s / statusCode</b></td> <td> <p> Status code of the request. </p> </td> </tr> - <tr class="a"> - <td><b>t / date</b></td> + <tr> + <td align="center"><b>t / date</b></td> <td> <p> Used to output the date of the logging event. @@ -1574,7 +1581,7 @@ <b>%d{HH:mm:ss,SSS}</b> , <b> - %d{dd�MMM�yyyy�;HH:mm:ss,SSS} + %d{dd MMM yyyy ;HH:mm:ss,SSS} </b> or <b>%d{DATE}</b> @@ -1583,40 +1590,40 @@ </p> </td> </tr> - <tr class="b"> - <td><b>u / user</b></td> + <tr> + <td align="center"><b>u / user</b></td> <td> <p> Remote user. </p> </td> </tr> - <tr class="a"> - <td><b>U / requestURI</b></td> + <tr> + <td align="center"><b>U / requestURI</b></td> <td> <p> Requested URI. </p> </td> </tr> - <tr class="b"> - <td><b>v / server</b></td> + <tr> + <td align="center"><b>v / server</b></td> <td> <p> Server name. </p> </td> </tr> - <tr class="a"> - <td><b>localPort</b></td> + <tr> + <td align="center"><b>localPort</b></td> <td> <p> Local port. </p> </td> </tr> - <tr class="b"> - <td><b>reqAttribute{attributeName}</b></td> + <tr> + <td align="center"><b>reqAttribute{attributeName}</b></td> <td> <p> Attribute of the request. @@ -1627,8 +1634,8 @@ displays the corresponding attribute.</p> </td> </tr> - <tr class="a"> - <td><b>reqCookie{cookie}</b></td> + <tr> + <td align="center"><b>reqCookie{cookie}</b></td> <td> <p> Request cookie. @@ -1638,8 +1645,8 @@ <p><b>%cookie{COOKIE_NAME}</b> displays corresponding cookie.</p> </td> </tr> - <tr class="b"> - <td><b>responseHeader{header}</b></td> + <tr> + <td align="center"><b>responseHeader{header}</b></td> <td> <p> Header of the response. @@ -1649,8 +1656,8 @@ <p><b>%header{Referer}</b> displays the referer of the response.</p> </td> </tr> - <tr class="a"> - <td><b>requestContent</b></td> + <tr> + <td align="center"><b>requestContent</b></td> <td> <p> This conversion word displays the content of the request, that is the @@ -1665,8 +1672,8 @@ </p> </td> </tr> - <tr class="b"> - <td><b>fullRequest</b></td> + <tr> + <td align="center"><b>fullRequest</b></td> <td> <p> This conversion word takes all the available headers of the @@ -1674,8 +1681,8 @@ </p> </td> </tr> - <tr class="a"> - <td><b>responseContent</b></td> + <tr> + <td align="center"><b>responseContent</b></td> <td> <p> This conversion word displays the content of the response, that is the @@ -1690,8 +1697,8 @@ </p> </td> </tr> - <tr class="b"> - <td><b>fullResponse</b></td> + <tr> + <td align="center"><b>fullResponse</b></td> <td> <p> This conversion word takes all the available headers of the @@ -1709,16 +1716,16 @@ <p><em>combined</em></p> </ul> - <p>The <em>common</em> keyword corresponds to the pattern <em>%h %l %u %t \"%r\" %s %b</em> + <p>The <em>common</em> keyword corresponds to the pattern <em>%h %l %u %t \"%r\" %s %b</em> which displays client host, remote log name, user, date, requested URL, status code and response's content length</p> <p>The <em>combined</em> keyword is a shortcut to - <em>%h %l %u %t \"%r\" %s %b \"%i{Referer}\" \"%i{User-Agent}\"</em>. This pattern begins + <em>%h %l %u %t \"%r\" %s %b \"%i{Referer}\" \"%i{User-Agent}\"</em>. This pattern begins much like the <em>common</em> pattern but also displays two request headers, namely referer, and user-agent.</p> - <a name="AccessHTMLLayout"></a> + <a name="AccessHTMLLayout" /> <h3>HTMLLayout</h3> <p>The access version of @@ -1737,7 +1744,7 @@ </ul> <p>Here is what you can expect from a configured access <code>HTMLLayout</code>:</p> - <img src="images/chapter5/htmlLayoutAccess.gif" alt="Access HTML Layout Sample Image"></img> + <img src="images/chapter5/htmlLayoutAccess.gif" alt="Access HTML Layout Sample Image"/> <p>What's better than a real world example? Our own log4j properties to logback configuration <a href="http://logback.qos.ch/translator/">translator</a> @@ -1748,8 +1755,6 @@ <p>Just like any access log, it can be altered simply by visiting the <a href="http://logback.qos.ch/translator/">translator</a> application.</p> - - <script src="../templates/footer.js"></script> </div> </body> Modified: logback/trunk/logback-site/src/site/resources/manual/mdc.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/manual/mdc.html (original) +++ logback/trunk/logback-site/src/site/resources/manual/mdc.html Mon Feb 5 14:28:49 2007 @@ -17,30 +17,34 @@ <script src="../templates/right.js"></script> </div> <div id="content"> - <h2>Chapter 7: Diagnostic Context</h2> + <h2>Chapter 7: Diagnostic Context</h2> <div class="author"> - Authors: Ceki G�lc�, S�bastien Pennec + Authors: Ceki Gülcü, Sébastien Pennec </div> - <table class="bodyTable"> - <tr class="a"> - <td> - <a 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"></img> + <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>Copyright © 2000-2006, QOS.ch</p> <p> - + <!--Creative Commons License--> This work is licensed under a - <a href="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + <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> @@ -98,7 +102,7 @@ <b>public static void clear();</b> //Returns the keys in the MDC as a Set. The returned value can be null. - <b>public static Set<String> getKeys();</b> + <b>public static Set<String> getKeys();</b> }</pre></div> <p> @@ -133,33 +137,33 @@ static public void main(String[] args) throws Exception { // You can put values in the MDC at any time. We first put the // first name - <b>MDC.put("first", "Dorothy");</b> + <b>MDC.put("first", "Dorothy");</b> // Configure logback PatternLayout layout = new PatternLayout(); - layout.setPattern("%X{first} %X{last} - %m%n"); + layout.setPattern("%X{first} %X{last} - %m%n"); layout.start(); - ConsoleAppender<LoggingEvent> appender = new ConsoleAppender<LoggingEvent>(); + ConsoleAppender<LoggingEvent> appender = new ConsoleAppender<LoggingEvent>(); appender.setLayout(layout); appender.start(); - Logger root = (Logger)LoggerFactory.getLogger("root"); + Logger root = (Logger)LoggerFactory.getLogger("root"); root.addAppender(appender); // get a logger Logger logger = (Logger)LoggerFactory.getLogger(SimpleMDC.class); // We now put the last name - <b>MDC.put("last", "Parker");</b> + <b>MDC.put("last", "Parker");</b> // The most beautiful two words in the English language according // to Dorothy Parker: - logger.info("Check enclosed."); - logger.debug("The most beautiful two words in English."); + logger.info("Check enclosed."); + logger.debug("The most beautiful two words in English."); - MDC.put("first", "Richard"); - MDC.put("last", "Nixon"); - logger.info("I am not a crook."); - logger.info("Attributed to the former US president. 17 Nov 1973."); + MDC.put("first", "Richard"); + MDC.put("last", "Nixon"); + logger.info("I am not a crook."); + logger.info("Attributed to the former US president. 17 Nov 1973."); } }</pre></div> @@ -281,9 +285,9 @@ public int[] factor(int number) throws RemoteException { // The client's host is an important source of information. try { - <b>MDC.put("client", NumberCruncherServer.getClientHost());</b> + <b>MDC.put("client", NumberCruncherServer.getClientHost());</b> } catch (java.rmi.server.ServerNotActiveException e) { - logger.warn("Caught unexpected ServerNotActiveException.", e); + logger.warn("Caught unexpected ServerNotActiveException.", e); } // The information contained within the request is another source @@ -291,28 +295,28 @@ // date of request, request ID etc. In servlet type environments, // useful information is contained in the HttpRequest or in the // HttpSession. - <b>MDC.put("number", String.valueOf(number));</b> + <b>MDC.put("number", String.valueOf(number));</b> - logger.info("Beginning to factor."); + logger.info("Beginning to factor."); if (number <= 0) { throw new IllegalArgumentException(number + - " is not a positive integer."); + " is not a positive integer."); } else if (number == 1) { return new int[] { 1 }; } - Vector<Integer> factors = new Vector<Integer>(); + Vector<Integer> factors = new Vector<Integer>(); int n = number; for (int i = 2; (i <= n) && ((i * i) <= number); i++) { // It is bad practice to place log requests within tight loops. // It is done here to show interleaved log output from // different requests. - logger.debug("Trying " + i + " as a factor."); + logger.debug("Trying " + i + " as a factor."); if ((n % i) == 0) { - logger.info("Found factor " + i); + logger.info("Found factor " + i); factors.addElement(new Integer(i)); do { @@ -326,7 +330,7 @@ } if (n != 1) { - logger.info("Found factor " + n); + logger.info("Found factor " + n); factors.addElement(new Integer(n)); } @@ -339,16 +343,16 @@ } <b>// clean up - MDC.remove("client"); - MDC.remove("number");</b> + MDC.remove("client"); + MDC.remove("number");</b> return result; } static void usage(String msg) { System.err.println(msg); - System.err.println("Usage: java chapter7.NumberCruncherServer configFile\n" + - " where configFile is a logback configuration file."); + System.err.println("Usage: java chapter7.NumberCruncherServer configFile\n" + + " where configFile is a logback configuration file."); System.exit(1); } @@ -361,12 +365,12 @@ public static void main(String[] args) { if (args.length != 1) { - usage("Wrong number of arguments."); + usage("Wrong number of arguments."); } String configFile = args[0]; - if (configFile.endsWith(".xml")) { + if (configFile.endsWith(".xml")) { try { LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); JoranConfigurator configurator = new JoranConfigurator(); @@ -382,13 +386,13 @@ try { ncs = new NumberCruncherServer(); - logger.info("Creating registry."); + logger.info("Creating registry."); Registry registry = LocateRegistry.createRegistry(Registry.REGISTRY_PORT); - registry.rebind("Factor", ncs); - logger.info("NumberCruncherServer bound and ready."); + registry.rebind("Factor", ncs); + logger.info("NumberCruncherServer bound and ready."); } catch (Exception e) { - logger.error("Could not bind NumberCruncherServer.", e); + logger.error("Could not bind NumberCruncherServer.", e); return; } @@ -422,20 +426,20 @@ The <em>mdc1.xml</em> configuration file is listed below: </p> <em>Example 7.4: Configuration file (logback-examples/src/main/java/chapter7/mdc1.xml)</em> -<div class="source"><pre><configuration> +<div class="source"><pre><configuration> - <appender name="CONSOLE" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%-4r [%thread] %-5level <b>C:%X{client} N:%X{number}</b> - %msg%n</Pattern> - </layout> - </appender> + <appender name="CONSOLE" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%-4r [%thread] %-5level <b>C:%X{client} N:%X{number}</b> - %msg%n</Pattern> + </layout> + </appender> - <root> - <level value ="debug"/> - <appender-ref ref="CONSOLE"/> - </root> -</configuration></pre></div> + <root> + <level value ="debug"/> + <appender-ref ref="CONSOLE"/> + </root> +</configuration></pre></div> <p> Note the use of the <em>%X</em> conversion specifier within the @@ -560,7 +564,7 @@ boolean userRegistered = false; - private final String userKey = "username"; + private final String userKey = "username"; public void destroy() { } @@ -593,7 +597,7 @@ } private void registerUsername(String username) { - if (username != null && username.trim().length() > 0) { + if (username != null && username.trim().length() > 0) { MDC.put(userKey, username); userRegistered = true; } @@ -620,6 +624,7 @@ request for another user without risking to display false information in the logs. </p> + <script src="../templates/footer.js"></script> </div> </body> Modified: logback/trunk/logback-site/src/site/resources/news.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/news.html (original) +++ logback/trunk/logback-site/src/site/resources/news.html Mon Feb 5 14:28:49 2007 @@ -19,8 +19,6 @@ </div> <div id="content"> - - <h2>Logback News</h2> <p>Here are the latest news about logback.</p> @@ -165,7 +163,7 @@ This release also provides some bug fixes. </p> - <hr width="80%" align="center"></hr> + <hr width="80%" align="center" /> <h3>October 26th, 2006 - Release of version 0.5</h3> @@ -183,7 +181,7 @@ documentation which is being continously improved. </p> - <hr width="80%" align="center"></hr> + <hr width="80%" align="center" /> <h3>October 9th, 2006 - Release of version 0.4</h3> <p> @@ -209,7 +207,7 @@ module. </p> - <hr width="80%" align="center"></hr> + <hr width="80%" align="center" /> <h3>September 8th, 2006 - Release of version 0.3</h3> <p> @@ -218,7 +216,7 @@ <p> This release offers several new Appenders, support for Mapped - Diagnostic Context, improved tests and documentation<br></br> + Diagnostic Context, improved tests and documentation<br /> </p> <p> @@ -227,12 +225,13 @@ </p> <p> - We also released a <a href="http://logback.qos.ch/translator/">PropertiesTranslator</a> + We also released a <a + href="http://logback.qos.ch/translator/">PropertiesTranslator</a> webapp that converts <em>log4j.properties</em> files to joran - configuration files (in XML format).<br></br> + configuration files (in XML format).<br /> </p> - <hr width="80%" align="center"></hr> + <hr width="80%" align="center" /> <h3>August 23th, 2006 - Release of version 0.2.5</h3> @@ -245,7 +244,7 @@ correction mande in the short introduction to logback-classic. </p> - <hr width="80%" align="center"></hr> + <hr width="80%" align="center" /> <h3>August 15th, 2006 - Release of version 0.2</h3> @@ -259,7 +258,7 @@ simpler and more efficient. </p> - <hr width="80%" align="center"></hr> + <hr width="80%" align="center" /> <h3>July 26th, 2006 - Release of version 0.1</h3> @@ -267,7 +266,7 @@ Version 0.1 of logback has been released. </p> - <hr width="80%" align="center"></hr> + <hr width="80%" align="center" /> <h3>February 9th, 2006 - Logback web-site goes live</h3> <p> Modified: logback/trunk/logback-site/src/site/resources/repos.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/repos.html (original) +++ logback/trunk/logback-site/src/site/resources/repos.html Mon Feb 5 14:28:49 2007 @@ -20,8 +20,10 @@ <div id="content"> - <h2>Source Repository</h2> - + <div class="section"> + <h2>Source Repository</h2> + </div> + <p> We keep the source code in revision control systems called Subversion. Developers have write access to the Subversion @@ -47,7 +49,8 @@ </p> <p> - <a href="http://svn.qos.ch/viewvc/logback/trunk/">http://svn.qos.ch/viewvc/logback/trunk/</a> + <a + href="http://svn.qos.ch/viewvc/logback/trunk/">http://svn.qos.ch/viewvc/logback/trunk/</a> </p> <div class="section"> @@ -63,7 +66,8 @@ <div class="section"> <p> Note that anonymous access allows read-only access only. For - read-write access please contact the logback <a href="mailinglist.html">developer list</a> . + read-write access please contact the logback <a + href="mailinglist.html">developer list</a> . </p> </div> @@ -72,7 +76,6 @@ - <script src="templates/footer.js"></script> </div> </body> Modified: logback/trunk/logback-site/src/site/resources/setup.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/setup.html (original) +++ logback/trunk/logback-site/src/site/resources/setup.html Mon Feb 5 14:28:49 2007 @@ -20,7 +20,7 @@ <div id="content"> - <h2>Classpath Setup</h2> +<h2>Classpath Setup</h2> <p> In order to run the examples provided in the documentation, @@ -28,10 +28,10 @@ </p> <ul> - <p>logback-core-1.0-SNAPSHOT.jar</p> - <p>logback-classic-1.0-SNAPSHOT.jar</p> - <p>logback-examples-1.0-SNAPSHOT.jar</p> - <p>slf4j-api-1.2.jar</p> + <p>logback-core-${version}.jar</p> + <p>logback-classic-${version}.jar</p> + <p>logback-examples-${version}.jar</p> + <p>slf4j-api-${slf4j.version}.jar</p> </ul> <h3>Example</h3> @@ -44,8 +44,8 @@ </p> <div class="source"><pre>java -cp - lib/slf4j-api-1.2.jar;../logback-core-1.0-SNAPSHOT.jar;\ - ../logback-classic-1.0-SNAPSHOT.jar;logback-examples-1.0-SNAPSHOT.jar\ + lib/slf4j-api-${slf4j.version}.jar;../logback-core-${version}.jar;\ + ../logback-classic-${version}.jar;logback-examples-${version}.jar\ chapter1.HelloWorld1</pre></div> <p> @@ -68,6 +68,7 @@ directory. </p> + Modified: logback/trunk/logback-site/src/site/resources/team.html ============================================================================== --- logback/trunk/logback-site/src/site/resources/team.html (original) +++ logback/trunk/logback-site/src/site/resources/team.html Mon Feb 5 14:28:49 2007 @@ -21,13 +21,13 @@ - <h2>Logback Team</h2> + <h2>Logback Team</h2> <p>Let us introduce you to the logback team members:</p> - <table class="bodyTable"> - <tr class="a"> - <td><img src="images/jeannoel.gif" alt="Jean-Noel"></img></td> + <table> + <tr> + <td><img src="images/jeannoel.gif" alt="Jean-Noel"/></td> <td> Jean-Noel Charpin has been designing and developing object oriented software and decision making systems since 1998. He is particularly interested in @@ -35,10 +35,10 @@ domain in order to improve quality and reliability. </td> </tr> - <tr class="b"> - <td><img src="images/ceki.gif" alt="Ceki"></img></td> + <tr> + <td><img src="images/ceki.gif" alt="Ceki"/></td> <td> - <p>Ceki G�lc� has been working on logging systems + <p>Ceki Gülcü has been working on logging systems since 1996. He is the founder of the log4j, slf4j and logback projects. Ceki enjoys writing software, a task far more difficult and time-consuming than what it seems at @@ -60,26 +60,24 @@ </td> </tr> - <tr class="a"> - <td><img src="images/seb.gif" alt="Sebastien"></img></td> + <tr> + <td><img src="images/seb.gif" alt="Sebastien"/></td> <td> - <p>S�bastien Pennec has been using computers for the most + <p>Sébastien Pennec has been using computers for the most part of his life, be it as a hobby, or during his studies or, more recently, as Software Engineer. He loves to write software in dynamic and enthusiastic environments, while learning new technologies and practices. </p> <p> - S�bastien's hobbys include writing articles about + Sébastien's hobbys include writing articles about Macintosh products on <a href="http://www.cuk.ch">cuk.ch</a>, digital photography and playing poker with his friends. </p> </td> </tr> </table> - - - +