Author: seb
Date: Thu Jan 11 18:56:59 2007
New Revision: 1200
Modified:
logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml
Log:
updated short intro's configuration section
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 Thu Jan
11 18:56:59 2007
@@ -965,38 +965,48 @@
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 a trivial application named <em>MyApp</em>.
+
+ <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 1.3: BasicConfigurator sample usage (<a
href="xref/chapter1/MyApp.html">logback-examples/src/main/java/chapter1/MyApp.java</a>)</em>
+ <em>Example 1.4: Logback configuration from file ((<a
+
href="xref/chapter1/MyAppWithConfigFile.html">logback-examples/src/main/java/chapter1/MyAppWithConfigFile.java</a>)</em>
+
<div class="source"><pre>package chapter1;
-// Import SLF4J classes.
-import org.slf4j.LoggerFactory;
+//Import SLF4J classes.
import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
-import ch.qos.logback.classic.BasicConfigurator;
-
-public class MyApp {
+import ch.qos.logback.classic.LoggerContext;
+import ch.qos.logback.classic.joran.JoranConfigurator;
+import ch.qos.logback.core.util.StatusPrinter;
- public static void main(String[] args) {
+public class MyAppWithConfigFile {
- // Set up a simple configuration that logs on the console.
- BasicConfigurator.configureDefaultContext();
+ 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 logger = LoggerFactory.getLogger(MyApp.class);
-
logger.info("Entering application.");
Bar bar = new Bar();
bar.doIt();
logger.info("Exiting application.");
+
+ StatusPrinter.print(lc.getStatusManager());
}
-}</pre></div>
+}</pre></div>
+
- <p>This class defines a logger instance variable with the name
- <em>MyApp</em>. It then instantiates a <code>Bar</code>
+ <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>
@@ -1015,23 +1025,18 @@
}
}</pre></div>
- <p>The invocation of the <code>configureDefaultContext()</code>
- method in <code>BasicConfigurator</code> creates a minimal
logback setup.
- Note that, by default, the root Logger is assigned to
<code>Level.DEBUG</code>.
- </p>
-
- <p>
- Running <code>MyApp</code>, by issuing the command
<em>java chapter1.MyApp</em>,
- will produce the following output:
+ <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>
-<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>
-
-<!-- ========= CEKI: STOPPED HERE =================== -->
-
- <p><em>MyApp</em> configures logback by invoking
- <code>BasicConfigurator.configureDefaultContext()</code>. All
+ <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
@@ -1042,53 +1047,8 @@
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>
-
- <em>Example 1.4: Logback configuration from file ((<a
-
href="xref/chapter1/MyAppWithConfigFile.html">logback-examples/src/main/java/chapter1/MyAppWithConfigFile.java</a>)</em>
-
-<div class="source"><pre>package chapter1;
-
-//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>MyAppWithConfigFile instructs <code>JoranConfigurator</code>
- to parse a configuration file and to set up logging according to
- the instructions found
- therein.
- </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>
+ <p>Let us configure logback with the
+ next XML configuration file:</p>
<em>Example 1.5: Basic configuration with a xml file
(logback-examples/src/main/java/chapter1/sample-config-1.xml)</em>
<div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?>
@@ -1122,22 +1082,15 @@
<div class="source"><pre>java chapter1.MyAppWithConfigFile
src/main/java/chapter1/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
<code>BasicConfigurator</code>
- class.
- </p>
-
- <p>We used the <code>JoranConfigurator</code> 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
<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>
+ Here is what you should see in the console:
</p>
+<div class="source"><pre>18:15:26.718 [main] INFO
chapter1.MyAppWithConfigFile - Entering application.
+18:15:26.718 [main] DEBUG chapter1.Bar - doing my job
+18:15:26.718 [main] INFO chapter1.MyAppWithConfigFile - Exiting
application.</pre></div>
+
+
<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>
@@ -1225,5 +1178,44 @@
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
+ this short introduction. The output was generated due to this
feature.
+ </p>
</body>
</document>
_______________________________________________
logback-dev mailing list
[email protected]
http://qos.ch/mailman/listinfo/logback-dev
