Author: ceki Date: Sun Aug 6 19:20:25 2006 New Revision: 396 Modified: logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml Log: work in progress Modified: logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml ============================================================================== --- logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml (original) +++ logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml Sun Aug 6 19:20:25 2006 @@ -83,11 +83,13 @@ <h2>First Baby Step</h2> <p>After you have added the jar fiiles <em>logback-core.jar</em> - and <em>logback-classic.jar</em> to your classpath, we can start + and <em>logback-classic.jar</em> to your classpath, you can begin experimenting with logback. </p> -<div class="source">1 package chapter1; +<div class="source"><em>Example 1.1: Basic template for logging (examples/HelloWorld1.java)</em> + +1 package chapter1; 2 3 import org.slf4j.Logger; 4 import org.slf4j.LoggerFactory; @@ -96,85 +98,95 @@ 7 8 public static void main(String[] args) { 9 -10 Logger logger = LoggerFactory.getLogger(BabyStep1.class); +10 Logger logger = LoggerFactory.getLogger("example/BabyStep1"); 11 logger.debug("Hello world."); 12 13 } 14 } </div> - <!-- STOPPED HERE: COGNIZANT? --> - <p>The <code>HelloWorld</code> class is defined in the <code>chapter1</code> package. It starts by importing the <code>Logger</code> and <code>LoggerFactory</code> classes as defined in the SLF4J API, more specifically in the - <code>org.slf4j</code> package. You will note that the above - example does not reference any logback classes. In most cases, as - far as logging is concerned, your classes will need to import only - SLF4J classes. In principle, you will have to import logback - classes only for configuring logback. Thus, the vast majority of - your classes will only be cognizant of SLF4J API and oblivious to - the existence of logback. + <code>org.slf4j</code> package. </p> - <p>Then a static variable gets a Logger that is initialised with - the <code>HelloWorld</code> class. The main method then invokes the - debug method of the received Logger. It gives the method a simple - String with the message to log. Put differently, the main method - contains a logging statement of level debug containing the message - “Hello world”. + <p>On line 10, the variable named <code>logger</code> 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 "example/BabyStep1". The main method + proceeds to call its <code>debug</code> method with the argument + "Hello world." We say that the main method contains a logging + statement of level debug containing the message “Hello world”. </p> - <p> - You can compile and run this class as follows: + <p>You will note that the above example does not reference any + logback classes. In most cases, as far as logging is concerned, + your classes will need to import only SLF4J classes. In principle, + you will have to import logback classes only for configuring + logback. Thus, the vast majority of your classes will only be + cognizant of SLF4J API and oblivious to the existence of logback. + </p> + + + <p><b>ceki: compile?</b> + You can compile and run this class with the command: </p> - <div class="source">java ch.qos.logback.classic.examples.HelloWorld1</div> + <div class="source">java chapter1.HelloWorld1</div> - <p>This will not produce any logging output. What happened? - Well, a powerful tool in logback is the Status and associated - classes. It keeps track of any events of importance that happen - during the use of logback. A simple statement can help us see why - nothing was logged: - </p> + <p>Suprisingly enough, launching the <code>HelloWorld1</code> + application will not produce <em>any</em> output. Logback does not + posses a default configuration. Without a valid configuration, + logback will be as silent as a mummy. + </p> + + <p>Logback can report information about its internal state using a + built-in status system. Important events occuring during logback's + lifetime can be accessed through a <code>StatusManager</code>. For + the time being, let us tell logback to print its internal + state. This is accomplished by a static method in the + <code>LoggerStatusPrinter</code> class. + </p> -<div class="source">package ch.qos.logback.classic.examples; +<div class="source">package chapter1; import org.slf4j.Logger; import org.slf4j.LoggerFactory; - -import ch.qos.logback.classic.util.LoggerStatusPrinter; +<b>import ch.qos.logback.classic.util.LoggerStatusPrinter;</b> public class HelloWorld2 { - final static Logger logger = LoggerFactory.getLogger(HelloWorld1.class); - public static void main(String[] args) { - + Logger logger = LoggerFactory.getLogger(HelloWorld2.class); logger.debug("Hello world."); - LoggerStatusPrinter.printStatusInDefaultContext(); - + <b>LoggerStatusPrinter.printStatusInDefaultContext();</b> } } </div> - <p> - The LoggerStatusPrinter will print whatever Statuses were sent to the - StatusManager. Running again the class with the new statement will - output to the console the next lines: - </p> -<div class="source"> -ERROR in Logger[ch.qos.logback.classic.examples.HelloWorld2] - No appenders present \\ -in the hierarchy [default] for logger [ch.qos.logback.classic.examples.HelloWorld2]. -</div> - <p> - We now know why nothing was logged: no Appenders are configured. - An Appender is a class that can be seen as an output destination. - Appenders exist for many different destinations including the console, - files, and many more. Users can also easily create their own Appenders - for any specific situation. + + + <p>Running the <code>HelloWorld2</code> application will produce + the following output:</p> + +<div class="source">ERROR in Logger[chapter1.HelloWorld2] - No appenders present in context [default] for logger [chapter1.HelloWorld2].</div> + + + <!-- ========= CEKI: STOPPED HERE =================== --> + + <p>Logback is complaining that no appenders were configured for + the default context. + + + An Appender is a class that can + be seen as an output destination. Appenders exist for many + different destinations including the console, files, and many + more. Users can also easily create their own Appenders for any + specific situation. </p> + <p> Configuring logback classic can be done a different ways. The simplest but less flexible way is by calling the <code>BasicConfigurator</code>