Author: ceki Date: Mon Nov 27 22:02:54 2006 New Revision: 1009 Modified: logback/trunk/logback-site/src/site/resources/10reasons.ppt logback/trunk/logback-site/src/site/xdocTemplates/mailinglist.xml logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml Log: minor improvements in documentation Modified: logback/trunk/logback-site/src/site/resources/10reasons.ppt ============================================================================== Binary files. No diff available. Modified: logback/trunk/logback-site/src/site/xdocTemplates/mailinglist.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/mailinglist.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/mailinglist.xml Mon Nov 27 22:02:54 2006 @@ -62,11 +62,11 @@ <a href="http://www.qos.ch/pipermail/logback-announce/"> qos.ch - </a> + </a> | <a href="http://marc.theaimsgroup.com/?l=logback-announce"> MARC - </a> + </a> | <a href="http://www.nabble.com/Logback-Announce-f16251.html"> Nabble @@ -86,17 +86,17 @@ <a href="http://qos.ch/mailman/options/logback-user"> Unsubscribe - </a> + </a> </td> <td> <a href="http://www.qos.ch/pipermail/logback-user/"> qos.ch - </a> + </a> | <a href="http://marc.theaimsgroup.com/?l=logback-user"> MARC - </a> + </a> | <a href="http://www.nabble.com/Logback-User-f16252.html"> @@ -117,17 +117,17 @@ <a href="http://qos.ch/mailman/options/logback-dev"> Unsubscribe - </a> + </a> </td> <td> <a href="http://www.qos.ch/pipermail/logback-dev/"> qos.ch - </a> + </a> | <a href="http://marc.theaimsgroup.com/?l=logback-dev"> MARC - </a> + </a> | <a href="http://www.nabble.com/Logback-Dev-f16253.html"> Nabble @@ -135,5 +135,12 @@ </td> </tr> </table> + + <h2>On IRC</h2> + + <p>We can also be reached by IRC at <code><span + class="big">irc.freenode.net#logback</span>.</code> + </p> + </body> </document> Modified: logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml Mon Nov 27 22:02:54 2006 @@ -923,7 +923,7 @@ log a statement. </p> -<!-- ========= CEKI: STOPPED HERE =================== --> + <h4>Better alternative</h4> @@ -964,9 +964,9 @@ <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>If three or more arguments need to be passed, an + <code>Object[]</code> variant is also availalble. For example, you + can write: </p> @@ -975,32 +975,32 @@ <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>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> - <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 - expressed in XML. + + <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 expressed + in XML. </p> - <p> - Existing log4j users can convert their <em>log4j.properties</em> - files to <em>logback.xml</em> using <a - href="http://logback.qos.ch/translator/">PropertiesTranslator</a> - web-application. + + <p>Existing log4j users can convert their + <em>log4j.properties</em> files to <em>logback.xml</em> using <a + href="http://logback.qos.ch/translator/">PropertiesTranslator</a> + web-application. </p> - <p> - Let us give a taste of how logback configuration is done with the help of an - imaginary application <em>MyApp</em> that uses logback. + + <p>Let us give a taste of how logback configuration is done with + the help of a trivial application named <em>MyApp</em>. </p> - <em>Example 1.4: Basic configuration (logback-examples/src/main/java/chapter1/MyApp.java)</em> + + <em>Example 1.4: Basic configuration (<a href="xref/chapter1/MyApp.html">logback-examples/src/main/java/chapter1/MyApp.java</a>)</em> <div class="source"><pre>package chapter1; // Import SLF4J classes. @@ -1024,12 +1024,19 @@ logger.info("Exiting application."); } }</pre></div> - <p> - This class defines a logger instance variable - with the name MyApp. It then uses the Bar class, defined as shown below: + + <p>This class defines a logger instance variable with the name + <em>MyApp</em>. It then instantiates a <code>Bar</code> + object. The <code>Bar</code> class is listed below: </p> - <em>Example 1.4: Basic configuration (logback-examples/src/main/java/chapter1/Bar.java)</em> -<div class="source"><pre>class Bar { + + <em>Example 1.4: Basic configuration (<a href="xref/chapter1/Bar.html">logback-examples/src/main/java/chapter1/Bar.java</a>)</em> +<div class="source"><pre>package chapter1; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +class Bar { Logger logger = LoggerFactory.getLogger(Bar.class); @@ -1037,56 +1044,42 @@ logger.debug("doing my job"); } }</pre></div> - <p> - The invocation of the BasicConfigurator create, as we have seen, - a simple yet sufficient logback setup. By default, - the root Logger is assigned to Level.DEBUG. + + <p>The invocation of the <code>configureDefaultContext()</code> + method in <code>BasicConfigurator</code> creates, as we have seen + previously, a minimal logback setup. Note that, by default, the + root Logger is assigned to Level.DEBUG. </p> - <p>The BasicConfigurator has to be called only once. Any other class that wishes to - issue log statements only has to import the <em>Logger</em> class and use it.</p> + <p> The output of MyApp is: </p> -<div class="source"><pre>0 [main] INFO ch.qos.logback.classic.examples.MyApp - Entering application. -0 [main] DEBUG ch.qos.logback.classic.examples.Bar - doing my job -0 [main] INFO ch.qos.logback.classic.examples.MyApp - Exiting application.</pre></div> - - <p>Let's configure logback to do exactly the same output, this time - with an XML configuration file.</p> - <em>Example 1.4: Basic configuration (logback-examples/src/main/java/chapter1/sample-config-1.xml)</em> -<div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?> +<div class="source"><pre>22:05:21.461 [main] INFO chapter1.MyApp - Entering application. +22:05:21.461 [main] DEBUG chapter1.Bar - doing my job +22:05:21.461 [main] INFO chapter1.MyApp - Exiting application.</pre></div> -<configuration> +<!-- ========= CEKI: STOPPED HERE =================== --> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="ch.qos.logback.classic.PatternLayout"> - <param name="pattern" - value="%-4relative [%thread] %-5level %class - %msg%n" /> - </layout> - </appender> + <p><em>MyApp</em> configures logback by invoking + <code>BasicConfigurator.configureDefaultContext()</code>. 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>The previous example output logging information always in the + same fixed format. Fortunately, it is easy to modify an + application so that logging environment is configured at runtime. + </p> - <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> tye. Its layout - is managed by a PatternLayout, that uses the value of the "pattern" 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 examle, use this command:</p> - -<div class="source"><pre>java chapter1.MyApp sample-config-1.xml</pre></div> + <em>Example 1.5: Logback configuration from file ((<a + href="xref/chapter1/MyAppWithConfigFile.html">logback-examples/src/main/java/chapter1/MyAppWithConfigFile.java</a>)</em> - <p>The console output will be exactly the same as before. However, this time, we didn't need - to import and call the BasicConfigurator class, as you can see in the following code section: - </p> - <em>Example 1.5: Logback configuration from file (logback-examples/src/main/java/chapter1/MyAppWithConfigFile.java)</em> <div class="source"><pre>package chapter1; //Import SLF4J classes. @@ -1115,18 +1108,73 @@ StatusPrinter.print(lc.getStatusManager()); } }</pre></div> - <p> - We used the JoranConfigurator class to parse the configuration file we just created. - 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 JoranConfigurator 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>MyApp2 instructs PropertyConfigurator to parse a configuration + file and to set up logging according to the instructions found + therein. The sample configuration file listed below, also + available as examples/chapter3/sample0.properties, configures + log4j (after parsing by PropertyConfigurator) in the same way as + BasicCon-figurator.configure. + </p> + + <p>Let us configure logback in the exact same way, + but this time with an XML configuration file. The next + configuration file, once executed, will have the same affect as + calling <code>BasicConfigrator</code>.</p> + + <em>Example 1.4: Basic configuration (logback-examples/src/main/java/chapter1/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> tye. Its layout is managed + by a PatternLayout, that uses the value of the "pattern" 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 examle, use this command:</p> + +<div class="source"><pre>java chapter1.MyApp <b>HOW ABOUT PATH?</b>sample-config-1.xml</pre></div> + + <p>The console output will be exactly the same as before. However, + this time, we didn't need to import and call the BasicConfigurator + class, as you can see in the following code section: </p> - <p>Logging to the console is a rather simple example. Let's now configure logback - so that it logs to the console, but also to a custom file.</p> + + <p>We used the JoranConfigurator class to parse the configuration + file we just created. 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 JoranConfigurator + 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>Logging to the console is a rather simple example. Let's now + configure logback so that it logs to the console, but also to a + custom file.</p> + <em>Example 1.5: Logback configuration from file (logback-examples/src/main/java/chapter1/sample-config-2.xml)</em> <div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?> @@ -1157,15 +1205,19 @@ </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 param element, in either - Appender configuration, reads the <em>name</em> attribute and assigns its value to the corresponding attribute - in the specified java class. + <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 param + element, in either Appender configuration, reads the <em>name</em> + attribute and assigns its value 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 chapter1 package anymore. - This is done by adding the following xml snippet to the configuration file, right before - the <code><root></code> element.</p> + <p>Suppose that we do not want to see the DEBUG level statements in + the chapter1 package anymore. This is done by adding the following + xml snippet to the configuration file, right before the + <code><root></code> element.</p> + <em>Example 1.5: Logback configuration from file (logback-examples/src/main/java/chapter1/sample-config-3.xml)</em> <div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?>