Author: ceki Date: Thu May 24 19:20:54 2007 New Revision: 1534 Modified: logback/trunk/log4j-bridge/ (props changed) logback/trunk/logback-examples/src/main/java/chapter3/MyApp2.java logback/trunk/logback-site/src/site/pages/codes.html logback/trunk/logback-site/src/site/pages/manual/joran.html logback/trunk/logback-site/src/site/pages/news.html Log: improved docs Modified: logback/trunk/logback-examples/src/main/java/chapter3/MyApp2.java ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter3/MyApp2.java (original) +++ logback/trunk/logback-examples/src/main/java/chapter3/MyApp2.java Thu May 24 19:20:54 2007 @@ -22,6 +22,7 @@ final static Logger logger = LoggerFactory.getLogger(MyApp2.class); public static void main(String[] args) { + // assume logback is in use LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); Modified: logback/trunk/logback-site/src/site/pages/codes.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/codes.html (original) +++ logback/trunk/logback-site/src/site/pages/codes.html Thu May 24 19:20:54 2007 @@ -5,269 +5,397 @@ <title>Logback FAQ</title> <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" /> </head> + <body> - <script> -prefix=''; -</script> - -<script src="templates/header.js"></script> -<div id="left"> - <script src="templates/left.js"></script> -</div> -<div id="right"> - <script src="templates/right.js"></script> -</div> -<div id="content"> - - <h2><a name="top">Logback error messages and their meanings</a></h2><p><b>Generalities</b></p><ol type="1"><li><a href="#tbr_fnp_not_set"> - The - <b>FileNamePattern</b> - option must be set before using - <code>TimeBasedRollingPolicy</code> - or - <code>FixedWindowRollingPolicy</code> - . - </a></li><li><a href="#fwrp_parentFileName_not_set"> - <p>The File name option must be set before <code>FixedWindowRollingPolicy</code>.</p> - </a></li><li><a href="#socket_no_host"> - No remote host or address is set for - <code>SocketAppender</code> - . - </a></li><li><a href="#socket_no_port"> - No remote port is set for - <code>SocketAppender</code> - . - </a></li><li><a href="#smtp_no_layout"> - No - <code>Layout</code> - is set for appender - </a></li><li><a href="#sbtp_size_format"> - Specified number is not in proper int form, or - not expected format. - </a></li><li><a href="#rfa_no_tp"> - No <code>TriggeringPolicy</code> was set for the - <code>RollingFileAppender</code>. - </a></li><li><a href="#rfa_no_rp"> - No <code>RollingPolicy</code> was set for the - <code>RollingFileAppender</code>. - </a></li></ol> + <script > + prefix=''; + </script> + + <script src="templates/header.js"></script> + <div id="left"> + <script src="templates/left.js"></script> + </div> + <div id="right"> + <script src="templates/right.js"></script> + </div> + <div id="content"> + + <h2><a name="top">Logback error messages and their meanings</a></h2> + + + <ol type="1"> + + <li> + <a href="#null_CS">contextSelector cannot be null</a> + </li> + + <li> + <a href="#tbr_fnp_not_set">The <b>FileNamePattern</b> option + must be set before using <code>TimeBasedRollingPolicy</code> or + <code>FixedWindowRollingPolicy</code> + </a> + </li> + + <li> + <a href="#fwrp_parentFileName_not_set">The File name option + must be set before <code>FixedWindowRollingPolicy</code> + </a> + </li> + + <li> + <a href="#socket_no_host">No remote host or address is set + for <code>SocketAppender</code> + </a> + </li> + + <li> + <a href="#socket_no_port">No remote port is set for + <code>SocketAppender</code> + </a> + </li> + + + <li> + <a href="#smtp_no_layout"> + No <code>Layout</code> is set for appender + </a> + </li> + + <li> + <a href="#sbtp_size_format"> + Specified number is not in proper int form, or + not expected format. + </a> + </li> + + <li> + <a href="#rfa_no_tp"> + No <code>TriggeringPolicy</code> was set for the + <code>RollingFileAppender</code> + </a> + </li> + + <li> + <a href="#rfa_no_rp"> + No <code>RollingPolicy</code> was set for the + <code>RollingFileAppender</code> + </a> + </li> + </ol> + + <h2>Error codes and their meanings</h2> + <dl> + + <dt> + <a name="null_CS"> + contextSelector cannot be null + </a> + </dt> + + <dd> + + + </dd> + + <dt> + <a name="tbr_fnp_not_set"> + The <b>FileNamePattern</b> option must be set before using + <code>TimeBasedRollingPolicy</code> or + <code>FixedWindowRollingPolicy</code> + + </a> + </dt> + + <dd> + <p>The <b>FileNamePattern</b> option for both + <code>TimeBasedRollingPolicy</code> and + <code>FixedWindowRollingPolicy</code> is mandatory. + </p> + + <p>See the <a + href="http://logback.qos.ch/apidocs/ch/qos/logback/core/rolling/FixedWindowRollingPolicy.html"> + FixedWindowRollingPolicy javadoc + </a> for more information. + + </p> - <div class="section"><h2>Generalities</h2><dl><dt><a name="tbr_fnp_not_set"> - The - <b>FileNamePattern</b> - option must be set before using - <code>TimeBasedRollingPolicy</code> - or - <code>FixedWindowRollingPolicy</code> - . - </a></dt><dd> - <p> - The - <b>FileNamePattern</b> - option for both - <code>TimeBasedRollingPolicy</code> - and - <code>FixedWindowRollingPolicy</code> - is mandatory. - </p> - <p> - See the - <a href="http://logback.qos.ch/apidocs/ch/qos/logback/core/rolling/FixedWindowRollingPolicy.html"> - FixedWindowRollingPolicy javadoc - </a> - for more information. - </p> - <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="fwrp_parentFileName_not_set"> - <p>The File name option must be set before <code>FixedWindowRollingPolicy</code>.</p> - </a></dt><dd> - <p> - The <span class="option">File</span> option is mandatory with <code>FixedWindowRollingPolicy</code>. Moreover, the File option must be - set before the declaration configuring <code>FixedWindowRollingPolicy</code>. - </p> - <p> - See the logback manual's chapter about - <a href="http://logback.qos.ch/manual/appenders.html#FixedWindowRollingPolicy"> - FixedWindowRollingPolicy - </a> - for more information. - </p> - <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="socket_no_host"> - No remote host or address is set for - <code>SocketAppender</code> - . - </a></dt><dd> - <p> - A remote host or address is mandatory for - SocketAppender. - </p> - <p> - You can specify the remote host in the - configuration file like this: - </p> - <div class="source"><pre> + <table border="0"> + <tr> + <td align="right"><a href="#top">[top]</a></td> + </tr> + </table> + <hr /> + </dd> + + <dt> + <a name="fwrp_parentFileName_not_set"> + The File name option must be set before <code>FixedWindowRollingPolicy</code> + </a> + </dt> + + <dd> + <p>The <span class="option">File</span> option is mandatory with + <code>FixedWindowRollingPolicy</code>. Moreover, the File option + must be set before the declaration configuring + <code>FixedWindowRollingPolicy</code>. + </p> + + <p>See the logback manual's chapter about + <a href="http://logback.qos.ch/manual/appenders.html#FixedWindowRollingPolicy"> + FixedWindowRollingPolicy + </a> + for more information. + </p> + + <table border="0"> + <tr> + <td align="right"> + <a href="#top">[top]</a> + </td> + </tr> + </table> + <hr /> + + </dd> + + <dt> + <a name="socket_no_host">No remote host or address is set for + <code>SocketAppender</code> + </a> + </dt> + <dd> + <p>A remote host or address is mandatory for SocketAppender. + </p> + <p>You can specify the remote host in the configuration file + like this: + </p> + + <div class="source"><pre> <appender name="SOCKET" class="ch.qos.logback.classic.net.SocketAppender"> ... <param name="remoteHost" value="127.0.0.1"></param> ... -</appender> - </pre></div> - <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="socket_no_port"> - No remote port is set for - <code>SocketAppender</code> - . - </a></dt><dd> - <p> - A remote port is mandatory for - SocketAppender. - </p> - <p> - You can specify the remote port in the - configuration file like this: - </p> - <div class="source"><pre> +</appender></pre> + </div> + + <table border="0"> + <tr> + <td align="right"> + <a href="#top">[top]</a> + </td> + </tr> + </table> + <hr /> + </dd> + + <dt> + <a name="socket_no_port">No remote port is set for + <code>SocketAppender</code> + </a> + </dt> + + <dd> + <p>A remote port is mandatory for SocketAppender. + </p> + + <p>You can specify the remote port in the configuration file + like this: + </p> + + <div class="source"><pre> <appender name="SOCKET" class="ch.qos.logback.classic.net.SocketAppender"> ... <param name="port" value="4560"></param> ... -</appender> - </pre></div> - <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="smtp_no_layout"> - No - <code>Layout</code> - is set for appender - </a></dt><dd> - <p> - A - <code>Layout</code> - is mandatory for - <code>SMTPAppender</code> - . It allows the appender format the logging - events before sending the email. Two layouts - are often used with - <code>SMTPAppender</code> - : - <code>PatternLayout</code> - and - <code>HTMLLayout</code> - . - </p> - <p> - You can specify the - <code>Layout</code> - in the configuration file like this: - </p> - <div class="source"><pre> +</appender></pre> + </div> + + <table border="0"> + <tr> + <td align="right"> + <a href="#top">[top]</a> + </td> + </tr> + </table> + <hr /> + </dd> + + <dt> + <a name="smtp_no_layout">No <code>Layout</code> is set for + appender</a> + </dt> + <dd> + <p>A <code>Layout</code> is mandatory for + <code>SMTPAppender</code> . It allows the appender format the + logging events before sending the email. Two layouts are often + used with <code>SMTPAppender</code> : + <code>PatternLayout</code> and <code>HTMLLayout</code> . + </p> + + <p>You can specify the <code>Layout</code> in the + configuration file like this: + </p> + + <div class="source"><pre> <appender name="SMTP" class="ch.qos.logback.classic.net.SMTPAppender"> ... <layout class="ch.qos.logback.classic.PatternLayout"> <param name="pattern" value="%-4relative [%thread] %-5level %class - %msg%n"></param> </layout> ... -</appender> - </pre></div> - <p> - You can see more examples in the - <a href="http://logback.qos.ch/apidocs/ch/qos/logback/classic/html/HTMLLayout.html"> - HTMLLayout javadoc - </a> - and the - <a href="http://logback.qos.ch/apidocs/ch/qos/logback/classic/PatternLayout.html"> - PatternLayout javadoc - </a> - . - </p> - <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="sbtp_size_format"> - Specified number is not in proper int form, or - not expected format. - </a></dt><dd> - <p> - When you specify the MaxFileSize to be used - by the SizeBasedRollingPolicy, logback - expects a rather precise format: - </p> - <ul> - <li>The number has to be an integer</li> - <li> - You can add 'KB', 'MB' or 'GB' after the - number. - </li> - </ul> - <p> - Here are some correct values: 500KB, 15MB, - 2GB. - </p> - <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="rfa_no_tp"> - No <code>TriggeringPolicy</code> was set for the - <code>RollingFileAppender</code>. - </a></dt><dd> - <p> - The <code>RollingFileAppender</code> must be set up with - a <code>TriggeringPolicy</code>. It permits the Appender - to know when the rollover must be activated. - </p> - <p> - To find more information about - <code>TriggeringPolicy</code> objects, please read the - following javadocs: - </p> - <ul> - <li> - <a href="http://logback.qos.ch/apidocs/ch/qos/logback/core/rolling/SizeBasedTriggeringPolicy.html"> - <code>SizeBasedTriggeringPolicy</code> - </a> - </li> - <li> - <a href="http://logback.qos.ch/apidocs/ch/qos/logback/core/rolling/TimeBasedRollingPolicy.html"> - <code>TimeBasedRollingPolicy</code> - </a> - </li> - </ul> - <p> - Please note that the <code>TimeBasedRollingPolicy</code> - is a TriggeringPolicy - <em>and</em> - and <code>RollingPolicy</code> at the same time. - </p> - <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="rfa_no_rp"> - No <code>RollingPolicy</code> was set for the - <code>RollingFileAppender</code>. - </a></dt><dd> - <p> - The <code>RollingFileAppender</code> must be set up with - a <code>RollingPolicy</code>. It permits the Appender - to know what to do when a rollover is requested. - </p> - <p> - To find more information about - <code>RollingPolicy</code> objects, please read the - following javadocs: - </p> - <ul> - <li> - <a href="http://logback.qos.ch/apidocs/ch/qos/logback/core/rolling/FixedWindowRollingPolicy.html"> - <code>FixedWindowRollingPolicy</code> - </a> - </li> - <li> - <a href="http://logback.qos.ch/apidocs/ch/qos/logback/core/rolling/TimeBasedRollingPolicy.html"> - <code>TimeBasedRollingPolicy</code> - </a> - </li> - </ul> - <p> - Please note that the <code>TimeBasedRollingPolicy</code> - is a <code>TriggeringPolicy</code> - <em>and</em> - and RollingPolicy at the same time. - </p> - <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table></dd></dl></div> +</appender></pre> + </div> - + + <p>You can see more examples in the + <a href="http://logback.qos.ch/apidocs/ch/qos/logback/classic/html/HTMLLayout.html"> + HTMLLayout javadoc + </a> and the + <a href="http://logback.qos.ch/apidocs/ch/qos/logback/classic/PatternLayout.html"> + PatternLayout javadoc + </a> + </p> + + <table border="0"> + <tr> + <td align="right"> + <a href="#top">[top]</a> + </td> + </tr> + </table> + <hr /> + + + </dd> + <dt> + <a name="sbtp_size_format">Specified number is not in proper + int form, or not expected format. + </a> + </dt> + + <dd> + <p>When you specify the MaxFileSize to be used by the + SizeBasedRollingPolicy, logback expects a rather precise + format: + </p> + + <ul> + <li>The number has to be an integer</li> + <li>You can add 'KB', 'MB' or 'GB' after the number. + </li> + </ul> + + <p>Here are some correct values: 500KB, 15MB, 2GB.</p> + + <table border="0"> + <tr> + <td align="right"> + <a href="#top">[top]</a> + </td> + </tr> + </table> + <hr /> + + </dd> + <dt> + <a name="rfa_no_tp">No <code>TriggeringPolicy</code> was set + for the <code>RollingFileAppender</code>. + </a> + </dt> + + <dd> + <p>The <code>RollingFileAppender</code> must be set up with a + <code>TriggeringPolicy</code>. It permits the Appender to know + when the rollover must be activated. + </p> + + <p>To find more information about <code>TriggeringPolicy</code> + objects, please read the following javadocs: + </p> + + <ul> + <li> + <a + href="http://logback.qos.ch/apidocs/ch/qos/logback/core/rolling/SizeBasedTriggeringPolicy.html"><code>SizeBasedTriggeringPolicy</code> + </a> + </li> + <li> + <a + href="http://logback.qos.ch/apidocs/ch/qos/logback/core/rolling/TimeBasedRollingPolicy.html"><code>TimeBasedRollingPolicy</code> + </a> + </li> + </ul> + + <p>Please note that the <code>TimeBasedRollingPolicy</code> + is a TriggeringPolicy <em>and</em> and + <code>RollingPolicy</code> at the same time. + </p> + + + <table border="0"> + <tr> + <td align="right"> + <a href="#top">[top]</a> + </td> + </tr> + </table> + <hr /> + + </dd> + <dt> + <a name="rfa_no_rp">No <code>RollingPolicy</code> was set + for the <code>RollingFileAppender</code>. + </a> + </dt> + + <dd> + <p>The <code>RollingFileAppender</code> must be set up with + a <code>RollingPolicy</code>. It permits the Appender to + know what to do when a rollover is requested. + </p> + + <p>To find more information about <code>RollingPolicy</code> + objects, please read the following javadocs: + </p> + + <ul> + <li> + <a href="http://logback.qos.ch/apidocs/ch/qos/logback/core/rolling/FixedWindowRollingPolicy.html"> + <code>FixedWindowRollingPolicy</code> + </a> + </li> + <li> + <a href="http://logback.qos.ch/apidocs/ch/qos/logback/core/rolling/TimeBasedRollingPolicy.html"> + <code>TimeBasedRollingPolicy</code> + </a> + </li> + </ul> + + <p>Please note that the <code>TimeBasedRollingPolicy</code> is a + <code>TriggeringPolicy</code> <em>and</em> and RollingPolicy at + the same time. + </p> + + + <table border="0"> + <tr> + <td align="right"> + <a href="#top">[top]</a> + </td> + </tr> + </table> + + </dd> + + + + + + </dl> - -<script src="templates/footer.js"></script> -</div> + <script src="templates/footer.js"></script> + </div> </body> </html> Modified: logback/trunk/logback-site/src/site/pages/manual/joran.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/joran.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/joran.html Thu May 24 19:20:54 2007 @@ -81,10 +81,10 @@ <p>Assuming the <em>logback-test.xml</em> file is placed under <em>src/test/resources</em> folder, Maven will ensure that it - won't be included in the artifact it produces. Thus, you can use a + won't be included in the artifact produced. Thus, you can use a different configuration file, namely <em>logback-test.xml</em> during testing, and another file, namely, <em>logback.xml</em>, in - production. + production. The same principle applies by analogy for Ant. </p> @@ -171,7 +171,10 @@ <!-- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXxx --> -<em>Example 3.2: Simple example of <code>BasicConfigurator</code> usage <a href="../xref/chapter3/MyApp2.html">(logback-examples/src/main/java/chapter3/MyApp2.java)</a></em> + <p><em>Example 3.2: Simple example of + <code>BasicConfigurator</code> usage <a + href="../xref/chapter3/MyApp2.html">(logback-examples/src/main/java/chapter3/MyApp2.java)</a></em></p> + <div class="source"><pre>package chapter3; import org.slf4j.Logger; @@ -186,16 +189,17 @@ final static Logger logger = LoggerFactory.getLogger(MyApp2.class); public static void main(String[] args) { - LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); + // assume logback is in use + <b>LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();</b> - try { -<b> JoranConfigurator configurator = new JoranConfigurator(); + <b>try { + JoranConfigurator configurator = new JoranConfigurator(); configurator.setContext(lc); lc.shutdownAndReset(); - configurator.doConfigure(args[0]);</b> + configurator.doConfigure(args[0]); } catch (JoranException je) { StatusPrinter.print(lc); - } + }</b> logger.info("Entering application."); @@ -205,16 +209,18 @@ } }</pre></div> -<p> -<code>MyApp2</code> fetches the <code>LoggerContext</code>, creates a new -<code>JoranConfigurator</code>, gives it the context and finally asks that -the configurator parses a configuration file. A basic configuration file, that -creates the same components as the default configuration would create, is -listed below: -</p> + <p><code>MyApp2</code> fetches the <code>LoggerContext</code> + currently in effect, creates a new <code>JoranConfigurator</code>, + gives it the context and finally asks that the configurator parses a + configuration file. A basic configuration file that creates the same + logging environment as would the default configuration is listed + below: + </p> -<em>Example 3.3: Basic configuration file (logback-examples/src/main/java/chapter3/sample0.xml)</em> -<div class="source"><pre><configuration> + <p><em>Example 3.3: Basic configuration file + (logback-examples/src/main/java/chapter3/sample0.xml)</em></p> + + <div class="source"><pre><configuration> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> @@ -229,29 +235,33 @@ </root> </configuration></pre></div> -<p> -Assuming the current directory is <em>logback-examples</em>, try running the -<code>MyApp2</code> class by issuing the following command: -</p> + <p>Assuming the current directory is <em>logback-examples</em>, try + running the <code>MyApp2</code> class by issuing the following + command: + </p> + + <div class="source"><pre>java chapter3.MyApp2 src/main/java/chapter3/sample0.xml</pre> + </div> + + <p> + The ouput of this command is very similar to the output of the + previous example, except that <code>MyApp2</code> retrieves a + logger called <em>chapter3.MyApp2</em> instead of + <code>chapter3.MyApp1</code>. The output will reflect the + difference. + </p> -<div class="source"><pre>java chapter3.MyApp2 src/main/java/chapter3/sample0.xml</pre></div> - -<p> -The ouput of this command is very similar to the output of the previous example, except -that <code>MyApp2</code> retrieves a logger called <em>chapter3.MyApp2</em> instead of -<code>chapter3.MyApp1</code>. The output will reflect the difference. -</p> - -<div class="source"><pre>16:09:00.593 [main] INFO chapter3.MyApp2 - Entering application. + <div class="source"><pre>16:09:00.593 [main] INFO chapter3.MyApp2 - Entering application. 16:09:00.593 [main] DEBUG chapter3.Foo - Did it again! 16:09:00.593 [main] INFO chapter3.MyApp2 - Exiting application.</pre></div> -<p> -It is often very useful to define the logback debug configuration property in order -to instruct logback to output internal configuration messages on the console. To achieve -this, one only needs to add an attribute to the main <em>configuration</em> element in the -configuration file, as shown above: -</p> + <p>It is often very useful to define the logback debug + configuration property in order to instruct logback to output + internal configuration messages on the console. To achieve this, + one only needs to add an attribute to the main + <em>configuration</em> element in the configuration file, as shown + above: + wec</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 <b>debug="true"</b>> Modified: logback/trunk/logback-site/src/site/pages/news.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/news.html (original) +++ logback/trunk/logback-site/src/site/pages/news.html Thu May 24 19:20:54 2007 @@ -36,6 +36,20 @@ reported</a> by Brian Suksomwong. </p> + <p>Fixed <a href="http://bugzilla.qos.ch/show_bug.cgi?id=63">bug + 63</a> as reported by La Canea Rosario. Calling log4j (bridge) with + the trace level will no longer cause an IllegalStateException to be + thrown. + </p> + + <p>Fixed <a href="http://bugzilla.qos.ch/show_bug.cgi?id=70">bug + 70</a> as reported by Dirk Ooms. The %throwable conversion word is + now recognized as documented in the logback manual. Moreover, the + manual now mentions the %nopex word which can be used to force + <code>PatternLayout</code> to ignore the exception contained in the + logging request. + </p> + <hr width="80%" align="center" />