August 2008 - logback-dev - mailman3.qos.ch

svn commit: r1757 - in logback/trunk/logback-classic/src: main/java/ch/qos/logback/classic main/java/ch/qos/logback/classic/jmx main/java/ch/qos/logback/classic/net main/java/ch/qos/logback/classic/selector main/java/ch/qos/logback/classic/util main/java/org/slf4j/impl test/java/ch/qos/logback/classic/util
by noreply.ceki＠qos.ch 16 Aug '08

16 Aug '08

Author: ceki Date: Sat Aug 16 16:57:18 2008 New Revision: 1757 Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/BasicConfigurator.java logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/jmx/Configurator.java logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/JMSQueueSink.java logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/JMSTopicSink.java logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/selector/ContextJNDISelector.java logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/util/ContextInitializer.java logback/trunk/logback-classic/src/main/java/org/slf4j/impl/StaticLoggerBinder.java logback/trunk/logback-classic/src/test/java/ch/qos/logback/classic/util/InitializationTest.java Log: - ContextInitializer now has a constructor taking a LoggerContext It's static methods have become instance methods with their first argument (a LoggerContext) removed. This leads to very slightly simpler code. Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/BasicConfigurator.java ============================================================================== --- logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/BasicConfigurator.java (original) +++ logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/BasicConfigurator.java Sat Aug 16 16:57:18 2008 @@ -1,7 +1,7 @@ /** * Logback: the generic, reliable, fast and flexible logging framework. * - * Copyright (C) 1999-2006, QOS.ch + * Copyright (C) 1999-2008, QOS.ch * * This library is free software, you can redistribute it and/or modify it under * the terms of the GNU Lesser General Public License as published by the Free Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/jmx/Configurator.java ============================================================================== --- logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/jmx/Configurator.java (original) +++ logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/jmx/Configurator.java Sat Aug 16 16:57:18 2008 @@ -49,7 +49,7 @@ addInfo("Shutting down context: " + lc.getName()); lc.shutdownAndReset(); try { - ContextInitializer.autoConfig(lc, lc.getClass().getClassLoader()); + new ContextInitializer(lc).autoConfig(lc.getClass().getClassLoader()); addInfo("Context: " + lc.getName() + " reloaded."); } catch(JoranException je) { addError("Reloading of context: " + lc.getName() + " failed.", je); @@ -70,7 +70,7 @@ LoggerContext lc = (LoggerContext) context; addInfo("Shutting down context: " + lc.getName()); lc.shutdownAndReset(); - ContextInitializer.configureByResource(lc, url); + new ContextInitializer(lc).configureByResource(url); addInfo("Context: " + lc.getName() + " reloaded."); } Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/JMSQueueSink.java ============================================================================== --- logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/JMSQueueSink.java (original) +++ logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/JMSQueueSink.java Sat Aug 16 16:57:18 2008 @@ -60,7 +60,7 @@ LoggerContext loggerContext = (LoggerContext) LoggerFactory .getILoggerFactory(); - ContextInitializer.autoConfig(loggerContext); + new ContextInitializer(loggerContext).autoConfig(); new JMSQueueSink(qcfBindingName, queueBindingName, username, password); Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/JMSTopicSink.java ============================================================================== --- logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/JMSTopicSink.java (original) +++ logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/JMSTopicSink.java Sat Aug 16 16:57:18 2008 @@ -60,7 +60,7 @@ LoggerContext loggerContext = (LoggerContext) LoggerFactory .getILoggerFactory(); - ContextInitializer.autoConfig(loggerContext); + new ContextInitializer(loggerContext).autoConfig(); new JMSTopicSink(tcfBindingName, topicBindingName, username, password); Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/selector/ContextJNDISelector.java ============================================================================== --- logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/selector/ContextJNDISelector.java (original) +++ logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/selector/ContextJNDISelector.java Sat Aug 16 16:57:18 2008 @@ -95,7 +95,7 @@ configureLoggerContextByResource(loggerContext, configFilePath); } else { try { - ContextInitializer.autoConfig(loggerContext); + new ContextInitializer(loggerContext).autoConfig(); } catch(JoranException je) { StatusPrinter.print(loggerContext); } Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/util/ContextInitializer.java ============================================================================== --- logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/util/ContextInitializer.java (original) +++ logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/util/ContextInitializer.java Sat Aug 16 16:57:18 2008 @@ -8,6 +8,8 @@ import ch.qos.logback.classic.LoggerContext; import ch.qos.logback.classic.joran.JoranConfigurator; import ch.qos.logback.core.joran.spi.JoranException; +import ch.qos.logback.core.status.InfoStatus; +import ch.qos.logback.core.status.StatusManager; import ch.qos.logback.core.util.Loader; // contributors @@ -24,8 +26,14 @@ final public static String CONFIG_FILE_PROPERTY = "logback.configurationFile"; final public static String STATUS_LISTENER_CLASS = "logback.statusListenerClass"; final public static String SYSOUT = "SYSOUT"; - - public static void configureByResource(LoggerContext loggerContext, URL url) + + final LoggerContext loggerContext; + + public ContextInitializer(LoggerContext loggerContext) { + this.loggerContext = loggerContext; + } + + public void configureByResource(URL url) throws JoranException { if (url == null) { throw new IllegalArgumentException("URL argument cannot be null"); @@ -35,52 +43,68 @@ configurator.doConfigure(url); } - static URL findConfigFileURLFromSystemProperties(ClassLoader classLoader) { + private URL findConfigFileURLFromSystemProperties(ClassLoader classLoader) { String logbackConfigFile = System.getProperty(CONFIG_FILE_PROPERTY, null); if (logbackConfigFile != null) { + URL result = null; try { - return new URL(logbackConfigFile); + result = new URL(logbackConfigFile); + return result; } catch (MalformedURLException e) { // so, resource is not a URL: // attempt to get the resource from the class path - URL urlAsResource = Loader.getResource(logbackConfigFile, classLoader); - if (urlAsResource != null) { - return urlAsResource; + result = Loader.getResource(logbackConfigFile, classLoader); + if (result != null) { + return result; } File f = new File(logbackConfigFile); if (f.exists() && f.isFile()) { try { - return f.toURL(); + result = f.toURL(); + return result; } catch (MalformedURLException e1) { } } + } finally { + statusOnResourceSearch(logbackConfigFile, result); } } return null; } - public static void autoConfig(LoggerContext loggerContext, - ClassLoader classLoader) throws JoranException { + public void autoConfig(ClassLoader classLoader) throws JoranException { StatusListenerConfigHelper.installIfAsked(loggerContext); - + URL url = findConfigFileURLFromSystemProperties(classLoader); if (url == null) { url = Loader.getResource(TEST_AUTOCONFIG_FILE, classLoader); + statusOnResourceSearch(TEST_AUTOCONFIG_FILE, url); } if (url == null) { url = Loader.getResource(AUTOCONFIG_FILE, classLoader); + statusOnResourceSearch(AUTOCONFIG_FILE, url); } if (url != null) { - configureByResource(loggerContext, url); + configureByResource(url); } else { BasicConfigurator.configure(loggerContext); } } - public static void autoConfig(LoggerContext loggerContext) - throws JoranException { + public void autoConfig() throws JoranException { ClassLoader tccl = Loader.getTCL(); - autoConfig(loggerContext, tccl); + autoConfig(tccl); + } + + private void statusOnResourceSearch(String resourceName, URL url) { + StatusManager sm = loggerContext.getStatusManager(); + if (url == null) { + sm.add(new InfoStatus("Could not find resource [" + resourceName + "]", + loggerContext)); + } else { + sm.add(new InfoStatus("Found resource [" + resourceName + "]", + loggerContext)); + } } } Modified: logback/trunk/logback-classic/src/main/java/org/slf4j/impl/StaticLoggerBinder.java ============================================================================== --- logback/trunk/logback-classic/src/main/java/org/slf4j/impl/StaticLoggerBinder.java (original) +++ logback/trunk/logback-classic/src/main/java/org/slf4j/impl/StaticLoggerBinder.java Sat Aug 16 16:57:18 2008 @@ -59,7 +59,7 @@ LoggerContext defaultLoggerContext = new LoggerContext(); defaultLoggerContext.setName("default"); try { - ContextInitializer.autoConfig(defaultLoggerContext); + new ContextInitializer(defaultLoggerContext).autoConfig(); } catch (JoranException je) { // TODO test me Util.reportFailure("Failed to auto configure default logger context", Modified: logback/trunk/logback-classic/src/test/java/ch/qos/logback/classic/util/InitializationTest.java ============================================================================== --- logback/trunk/logback-classic/src/test/java/ch/qos/logback/classic/util/InitializationTest.java (original) +++ logback/trunk/logback-classic/src/test/java/ch/qos/logback/classic/util/InitializationTest.java Sat Aug 16 16:57:18 2008 @@ -58,7 +58,7 @@ // of users trying to follows the manual and logback-examples from an IDE public void testReset() throws JoranException { { - ContextInitializer.autoConfig(lc); + new ContextInitializer(lc).autoConfig(); Appender appender = root.getAppender("STDOUT"); assertNotNull(appender); assertTrue(appender instanceof ConsoleAppender); @@ -81,7 +81,7 @@ public void doAutoConfigFromSystemProperties(String val) throws JoranException { //lc.shutdownAndReset(); System.setProperty(ContextInitializer.CONFIG_FILE_PROPERTY, val); - ContextInitializer.autoConfig(lc); + new ContextInitializer(lc).autoConfig(); Appender appender = root.getAppender("AUTO_BY_SYSTEM_PROPERTY"); assertNotNull(appender); }

1 0

[JIRA] Created: (LBCLASSIC-60) chapter on Markers
by Ceki Gulcu (JIRA) 15 Aug '08

15 Aug '08

chapter on Markers ------------------ Key: LBCLASSIC-60 URL: http://jira.qos.ch/browse/LBCLASSIC-60 Project: logback-classic Issue Type: Task Reporter: Ceki Gulcu Assignee: Logback dev list Priority: Critical - SECURITY marker, see http://www.owasp.org/index.php/How_to_add_a_security_log_level_in_log4j - ENTER/EXIT markers, both containing a FLOW marker as a child so as to disable both in one statement - PROFILER marker -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://jira.qos.ch/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

1 1

[JIRA] Created: (LBCORE-53) joran stops processing in case of an unchecked exception
by Ceki Gulcu (JIRA) 15 Aug '08

15 Aug '08

joran stops processing in case of an unchecked exception -------------------------------------------------------- Key: LBCORE-53 URL: http://jira.qos.ch/browse/LBCORE-53 Project: logback-core Issue Type: Bug Components: Joran Reporter: Ceki Gulcu Assignee: Logback dev list See http://jira.qos.ch/browse/LBCLASSIC-58 and in particular http://jira.qos.ch/browse/LBCLASSIC-58?focusedCommentId=10636#action_10636 -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://jira.qos.ch/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

2 2

svn commit: r1756 - in logback/trunk: logback-classic/src/main/java/ch/qos/logback/classic logback-site/src/site/pages/css logback-site/src/site/pages/manual
by noreply.ceki＠qos.ch 14 Aug '08

14 Aug '08

Author: ceki Date: Thu Aug 14 18:02:21 2008 New Revision: 1756 Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/BasicConfigurator.java logback/trunk/logback-site/src/site/pages/css/site.css logback/trunk/logback-site/src/site/pages/manual/joran.html Log: - improving the docs - added chapter numbering by CSS (firefox only) Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/BasicConfigurator.java ============================================================================== --- logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/BasicConfigurator.java (original) +++ logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/BasicConfigurator.java Thu Aug 14 18:02:21 2008 @@ -17,6 +17,14 @@ import ch.qos.logback.core.status.InfoStatus; import ch.qos.logback.core.status.StatusManager; +/** + * BasicConfigurator configures logback-classic by attaching a + * {@link ConsoleAppender} to the root logger. The console appender's layout + * is set to a {@link PatternLayout} with the pattern + * "%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n". + * + * @author Ceki Gulcu + */ public class BasicConfigurator { final static BasicConfigurator hiddenSingleton = new BasicConfigurator(); Modified: logback/trunk/logback-site/src/site/pages/css/site.css ============================================================================== --- logback/trunk/logback-site/src/site/pages/css/site.css (original) +++ logback/trunk/logback-site/src/site/pages/css/site.css Thu Aug 14 18:02:21 2008 @@ -9,6 +9,7 @@ color: #000; padding: 0px; margin: 0px; + counter-reset: example; /* Create an example counter scope */ } a { @@ -166,6 +167,7 @@ #content { + min-width:50em; margin: 0px 15em 0px 15em; padding: 0px; background-color: #ffffff; @@ -304,4 +306,10 @@ .quote { align: right; padding-left: 12em; +} + +/* --------- numbering --------- */ +.autoEx:before { + counter-increment: example; /* Add 1 to example */ + content: counter(example) } \ No newline at end of file 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 Aug 14 18:02:21 2008 @@ -18,7 +18,7 @@ <div id="right"> <script src="index_menu.js"></script> </div> -<div id="content"> +<div id="content" class="chapter"> <h1>Chapter 3: Logback configuration & Joran</h1> @@ -43,7 +43,7 @@ In the first part, we start by presenting ways for configuring logback, with many example configuration scripts. In the <a href="#Joran">second part</a>, we present Joran, a generic - configuration framework, that you can put into use in order to + configuration framework, which you can put into use in order to configure your own applications. @@ -56,8 +56,8 @@ 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, we need powerful tools to manage these - log statements. + code. Given their number, we need tools to manage these log + statements. Logback can be configured either programmatically or with @@ -85,8 +85,7 @@ <li>In case neither file is found, logback configures itself automatically using the <a href="../xref/ch/qos/logback/classic/BasicConfigurator.html"><code>BasicConfigurator</code></a> - which will cause logging output to be directed on the - console. + which will cause logging output to be directed on the console. </li> @@ -103,7 +102,7 @@ won't be included in the artifact produced. Thus, you can use a different configuration file, namely logback-test.xml during testing, and another file, namely, logback.xml, in - production. The same principle could apply by analogy for Ant. + production. The same principle applies by analogy for Ant. @@ -115,9 +114,11 @@ <code>MyApp1</code>. -Example 3.1: Simple example of <code>BasicConfigurator</code> usage -<a href="../xref/chapter3/MyApp1.html">(logback-examples/src/main/java/chapter3/MyApp1.java)</a> -<div class="source"><pre>package chapter3; + Example 3.: Simple example of + <code>BasicConfigurator</code> usage <a + href="../xref/chapter3/MyApp1.html">(logback-examples/src/main/java/chapter3/MyApp1.java)</a> + + <div class="source"><pre>package chapter3; import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -138,7 +139,7 @@ instantiates a Foo object. The Foo class is listed below: - Example 3.2: Small class doing logging + Example 3.: Small class doing logging <a href="../xref/chapter3/Foo.html">(logback-examples/src/main/java/chapter3/Foo.java)</a> @@ -156,34 +157,33 @@ }</pre></div> - - In order to run the examples in this chapter, 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. - + In order to run the examples in this chapter, 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. + Assuming the configuration files logback-test.xml or logback.xml could not be found, logback will default to a - minimal configuration hardwired to attaching a - <code>ConsoleAppender</code> to the root logger. The output is - formatted using a <code>PatternLayout</code> set to the pattern - %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - - %msg%n. Moreover, by default the root logger is assigned to - the <code>DEBUG</code> level. - + minimal configuration mentioned earlier. This configuration is + hardwired to attaching a <code>ConsoleAppender</code> to the root + logger. The output is formatted using a + <code>PatternLayout</code> set to the pattern %d{HH:mm:ss.SSS} + [%thread] %-5level %logger{36} - %msg%n. Moreover, by default + the root logger is assigned to the <code>DEBUG</code> level. + - Thus, the output of the command java chapter3.MyApp1 - should be similar to: - + Thus, the output of the command java chapter3.MyApp1 + should be similar to: + <div class="source"><pre>16:06:09.031 [main] INFO chapter3.MyApp1 - Entering application. 16:06:09.046 [main] DEBUG chapter3.Foo - Did it again! 16:06:09.046 [main] INFO chapter3.MyApp1 - Exiting application.</pre></div> - The <code>MyApp1</code> application links to logback through + The <code>MyApp1</code> application links to logback via calls <code>org.slf4j.LoggerFactory</code> and <code>org.slf4j.Logger</code> classes, retrieve the loggers it wishes to use, and chugs on. Note that the only dependence of the @@ -196,18 +196,85 @@ bodies of code from one logging system to another. - - <h3>The same with <code>JoranConfigurator</code></h3> + <h3>Automatic configuration with logback-test.xml or + logback.xml</h3> + + As mentioned earlier, logback will try to configure itself using + the files logback-test.xml or logback.xml if + found on the classpath. Here is a configuration file equivalent to + the one established by <code>BasicConfigrator</code> we've just + seen. + + + Example 3.: Basic configuration file + (logback-examples/src/main/java/chapter3/sample0.xml) + + <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> + + After you have renamed sample0.xml as + logback.xml (or logback-test.xml) place it into a + directory accesible from the classpath. Running the MyApp1 + application should give identical results to its previous run. + + If you are having problems with this example, you might want to + inspect logback's internal status. This is done invoking the + <code>print()</code> of the <code>StatusPrinter</code> class. The + MyApp2 application shown below is identical to + MyApp1 except the addition of two lines of code for + printing internal status data. + + Example 3.: Print logback's internal status information + <a + href="../xref/chapter3/MyApp2.html">(logback-examples/src/main/java/chapter3/MyApp2.java)</a> + + <div class="source"><pre> + public static void main(String[] args) { + logger.info("Entering application."); + // print logback's internal status + LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); + StatusPrinter.print(lc); + ... + }</pre></div> + + If everything goes well, you should see the following output on the console + + <div class="source"><pre>17:58:31.328 [main] INFO chapter3.MyApp2 - Entering application. +17:58:31,171 |-INFO in ch.qos.logback.classic.joran.action.ConfigurationAction - Ignoring debug attribute. +17:58:31,171 |-INFO in ch.qos.logback.core.joran.action.AppenderAction - About to instantiate appender of type [ch.qos.logback.core.ConsoleAppender] +17:58:31,171 |-INFO in ch.qos.logback.core.joran.action.AppenderAction - Naming appender as [STDOUT] +17:58:31,328 |-INFO in ch.qos.logback.core.joran.action.AppenderAction - Popping appender named [STDOUT] from the object stack +17:58:31,328 |-INFO in ch.qos.logback.classic.joran.action.LevelAction - root level set to DEBUG +17:58:31,328 |-INFO in ch.qos.logback.core.joran.action.AppenderRefAction - Attaching appender named [STDOUT] to Logger[root] + +17:58:31.343 [main] DEBUG chapter3.Foo - Did it again! +17:58:31.343 [main] INFO chapter3.MyApp2 - Exiting application. +</pre></div> + + + <h3>Invoking <code>JoranConfigurator</code> programmatically</h3> The previous example outputs logging information always in the - same fixed manner. How boring! It takes few easy steps to modify + same fixed manner. How boring! It takes few simple steps to modify <code>MyApp1</code> so that the log output can be controlled at runtime. Here is a slightly modified application called <code>MyApp2</code>. - Example 3.2: Simple example of + Example 3.: Simple example of <code>BasicConfigurator</code> usage <a href="../xref/chapter3/MyApp2.html">(logback-examples/src/main/java/chapter3/MyApp2.java)</a> @@ -253,7 +320,7 @@ below: - Example 3.3: Basic configuration file + Example 3.: Basic configuration file (logback-examples/src/main/java/chapter3/sample0.xml) <div class="source"><pre><configuration> @@ -312,7 +379,7 @@ above: wec -Example 3.4: Basic configuration file using debug mode (logback-examples/src/main/java/chapter3/sample1.xml) +Example 3.: Basic configuration file using debug mode (logback-examples/src/main/java/chapter3/sample1.xml) <div class="source"><pre><configuration debug="true"> <appender name="STDOUT" @@ -370,54 +437,57 @@ <h4>Configuring Loggers</h4> - -Loggers are configured using logger elements. A logger element takes exactly -one mandatory name atttribute and an optional additivity attribute, which takes values -true or false. The logger element admits at most one level -element which is discussed next. It may also contain zero or more appender-ref elements; -each appender thus referenced is added to the named logger. It is important to keep mind that -each named logger that is declared with a logger element first has all its -appenders removed and only then are the referenced appenders attached to it. -In particular, if there are no appender references, then the named logger will -lose all its appenders. - - - -The level element is used to set logger levels. It admits two attributes -value and class. The value attribute can be one of the strings DEBUG, -INFO, WARN ERROR, ALL or OFF. -The special case-insensitive value INHERITED, or its synonym NULL, -will force the level of the logger to be inherited from higher up in the hierarchy. -Note that the level of the root logger cannot be inherited. -If you set the level of a logger and later decide that it should inherit -its level, then you need to specify INHERITED or its synonym NULL -as the level value. The class attribute allows you to specify a custom -level where the value of the attribute is the fully qualified name of a -custom level class. You may alternatively use the level#classname syntax within -the value attribute. The level element has no children. - - - -The root element configures the root logger. It does not admit -any attributes because the additivity flag does not apply to the root logger. -Moreover, since the root logger cannot be named, it does not admit a name -attribute either. The root element admits at most one level -element and zero or more appender-ref elements. -Similar to the logger element, declaring a root element -will have the effect of first closing and then detaching all its current -appenders and only subsequently will referenced appenders, if any, will be added. -In particular, if it has no appender references, then the root logger -will lose all its appenders. - - - -Setting the level of a logger is as simple as declaring it and setting -its level, as the next example illustrates. Suppose we are no longer interested -in seeing any <code>DEBUG</code> level logs from any component -belonging to the chapter3 package. The following configuration file shows how to achieve that. - +Loggers are configured using logger elements. A +logger element takes exactly one mandatory name atttribute +and an optional additivity attribute, which takes values true +or false. The logger element admits at most one +level element which is discussed next. It may also contain +zero or more appender-ref elements; each appender thus +referenced is added to the named logger. It is important to keep mind +that each named logger that is declared with a logger element +first has all its appenders removed and only then are the referenced +appenders attached to it. In particular, if there are no appender +references, then the named logger will lose all its appenders. + + +The level element is used to set logger levels. It admits +two attributes value and class. The value attribute +can be one of the strings DEBUG, INFO, WARN +ERROR, ALL or OFF. The special +case-insensitive value INHERITED, or its synonym +NULL, will force the level of the logger to be inherited from +higher up in the hierarchy. Note that the level of the root logger +cannot be inherited. If you set the level of a logger and later +decide that it should inherit its level, then you need to specify +INHERITED or its synonym NULL as the level +value. The class attribute allows you to specify a custom level where +the value of the attribute is the fully qualified name of a custom +level class. You may alternatively use the level#classname +syntax within the value attribute. The level element has no +children. + + +The root element configures the root logger. It does not +admit any attributes because the additivity flag does not apply to the +root logger. Moreover, since the root logger cannot be named, it does +not admit a name attribute either. The root element admits at +most one level element and zero or more appender-ref +elements. Similar to the logger element, declaring a +root element will have the effect of first closing and then +detaching all its current appenders and only subsequently will +referenced appenders, if any, will be added. In particular, if it has +no appender references, then the root logger will lose all its +appenders. + + + Setting the level of a logger is as simple as declaring it and + setting its level, as the next example illustrates. Suppose we are + no longer interested in seeing any <code>DEBUG</code> level logs + from any component belonging to the chapter3 package. The following + configuration file shows how to achieve that. + -Example 3.5: Setting the level of a logger (logback-examples/src/main/java/chapter3/sample2.xml) +Example 3.: Setting the level of a logger (logback-examples/src/main/java/chapter3/sample2.xml) <div class="source"><pre><configuration> <appender name="STDOUT" @@ -440,22 +510,20 @@ </configuration></pre></div> - -This new configuration will yield the following output, when used with the -same <code>chapter3.MyApp2</code> class. +This new configuration will yield the following output, when used +with the same <code>chapter3.MyApp2</code> class. <div class="source"><pre>17:34:07.578 [main] INFO chapter3.MyApp2 - Entering application. 17:34:07.578 [main] INFO chapter3.MyApp2 - Exiting application.</pre></div> - -Obviously, you can configure the levels of as many loggers as you wish. -In the next configuration file we set the level of the chapter3 logger to -<code>INFO</code> but at the same time set the level of the chapter3.Foo logger -to <code>DEBUG</code>. +Obviously, you can configure the levels of as many loggers as you +wish. In the next configuration file we set the level of the +chapter3 logger to <code>INFO</code> but at the same time set +the level of the chapter3.Foo logger to <code>DEBUG</code>. -Example 3.6: Setting the level of multiple loggers (logback-examples/src/main/java/chapter3/sample3.xml) +Example 3.: Setting the level of multiple loggers (logback-examples/src/main/java/chapter3/sample3.xml) <div class="source"><pre><configuration> <appender name="STDOUT" @@ -484,9 +552,8 @@ </configuration></pre></div> - -Running <code>MyApp2</code> with this configuration file will result in the -following output on the console: +Running <code>MyApp2</code> with this configuration file will +result in the following output on the console: <div class="source"><pre>17:39:27.593 [main] INFO chapter3.MyApp2 - Entering application. @@ -526,16 +593,18 @@ </tr> </table> - -It follows that the two logging statements of level <code>INFO</code> in the <code>MyApp2</code> -class are enabled while the <code>debug</code> statement in <code>Foo.doIt()</code> method -will also print without hindrance. Note that the level of the root logger is always -set to a non-null value, which is <code>DEBUG</code> by default. -One rather important point to remember is that the logger-level filter depends -on the effective level of the logger being invoked, not the level of the logger -where the appenders are attached. The configuration file sample4.xml is a case in point: +It follows that the two logging statements of level +<code>INFO</code> in the <code>MyApp2</code> class are enabled while +the <code>debug</code> statement in <code>Foo.doIt()</code> method +will also print without hindrance. Note that the level of the root +logger is always set to a non-null value, which is <code>DEBUG</code> +by default. One rather important point to remember is that the +logger-level filter depends on the effective level of the logger being +invoked, not the level of the logger where the appenders are +attached. The configuration file sample4.xml is a case in +point: -Example 3.7: Logger level sample (logback-examples/src/main/java/chapter3/sample4.xml) +Example 3.: Logger level sample (logback-examples/src/main/java/chapter3/sample4.xml) <div class="source"><pre><configuration> <appender name="STDOUT" @@ -591,24 +660,23 @@ </tr> </table> - -The ConsoleAppender named STDOUT, the only configured appender in -sample4.xml, is attached to the root logger whose level is set to -<code>OFF</code>. However, running MyApp2 with configuration script -sample4.xml will output: +The ConsoleAppender named STDOUT, the only configured +appender in sample4.xml, is attached to the root logger whose +level is set to <code>OFF</code>. However, running MyApp2 with +configuration script sample4.xml will output: <div class="source"><pre>17:52:23.609 [main] INFO chapter3.MyApp2 - Entering application. 17:52:23.609 [main] INFO chapter3.MyApp2 - Exiting application.</pre></div> - -Thus, the level of the root logger has no apparent effect because the loggers in -<code>chapter3.MyApp2</code> and <code>chapter3.Foo</code> classes, namely -chapter3.MyApp2 and chapter3.Foo, inherit their level from the -chapter3 logger which has its level set to <code>INFO</code>. -As noted previously, the chapter3 logger exists by virtue of its -declaration in the configuration file - even if the Java source code does not -directly refer to it. +Thus, the level of the root logger has no apparent effect because +the loggers in <code>chapter3.MyApp2</code> and +<code>chapter3.Foo</code> classes, namely chapter3.MyApp2 and +chapter3.Foo, inherit their level from the chapter3 +logger which has its level set to <code>INFO</code>. As noted +previously, the chapter3 logger exists by virtue of its +declaration in the configuration file - even if the Java source code +does not directly refer to it. <h4>Configuring Appenders</h4> @@ -637,7 +705,7 @@ and referencing them in a logger, as the next configuration file illustrates: -Example 3.8: Multiple loggers (logback-examples/src/main/java/chapter3/multiple.xml) +Example 3.: Multiple loggers (logback-examples/src/main/java/chapter3/multiple.xml) <div class="source"><pre><configuration> <appender name="FILE" @@ -674,32 +742,33 @@ </root> </configuration></pre></div> - -This configuration scripts defines two appenders called FILE and STDOUT. -The FILE appender logs to a file called myApp.log. The layout for this appender -is a <code>PatternLayout</code> that outputs the date, level, thread name, logger name, -file name and line number where the log request is located, -the message and line separator character(s). -The second appender called <code>STDOUT</code> outputs to the console. -The layout for this appender outputs only the message string followed by a line separator. - + This configuration scripts defines two appenders called + FILE and STDOUT. The FILE appender logs + to a file called myApp.log. The layout for this appender is + a <code>PatternLayout</code> that outputs the date, level, thread + name, logger name, file name and line number where the log request + is located, the message and line separator character(s). The second + appender called <code>STDOUT</code> outputs to the console. The + layout for this appender outputs only the message string followed by + a line separator. + - -The appenders are attached to the root logger by referencing -them by name within an appender-ref element. Note that each appender -has its own layout. Layouts are usually not designed to be shared by multiple -appenders. XML configuration files do not provide any syntactical -means for sharing layouts. - + The appenders are attached to the root logger by referencing them + by name within an appender-ref element. Note that each + appender has its own layout. Layouts are usually not designed to be + shared by multiple appenders. XML configuration files do not provide + any syntactical means for sharing layouts. + - -By default, appenders are cumulative: a logger will log to the appenders -attached to itself (if any) as well as all the appenders attached to its ancestors. -Thus, attaching the same appender to multiple loggers will cause -logging output to be duplicated. - + By default, appenders are cumulative: a logger will log to + the appenders attached to itself (if any) as well as all the + appenders attached to its ancestors. Thus, attaching the same + appender to multiple loggers will cause logging output to be + duplicated. + -Example 3.9: Duplicate appender (logback-examples/src/main/java/chapter3/duplicate.xml) + Example 3.: Duplicate appender + (logback-examples/src/main/java/chapter3/duplicate.xml) <div class="source"><pre><configuration> <appender name="STDOUT" @@ -721,9 +790,9 @@ </root> </configuration></pre></div> - -Running <code>MyApp2</code> with duplicate.xml will yield the following output: - + Running <code>MyApp2</code> with duplicate.xml will + yield the following output: + <div class="source"><pre>14:25:36.343 [main] INFO chapter3.MyApp2 - Entering application. 14:25:36.343 [main] INFO chapter3.MyApp2 - Entering application. @@ -732,24 +801,25 @@ 14:25:36.359 [main] INFO chapter3.MyApp2 - Exiting application. 14:25:36.359 [main] INFO chapter3.MyApp2 - Exiting application.</pre></div> - -Notice the duplicated output. The appender named STDOUT is attached to -two loggers, to root and to chapter3. Since the root logger is the -ancestor of all loggers and chapter3 is the parent of chapter3.MyApp2 -and chapter3.Foo, logging request made with these two loggers -will be output twice, once because STDOUT is attached to chapter3 -and once because it is attached to root. - + Notice the duplicated output. The appender named STDOUT + is attached to two loggers, to root and to chapter3. Since + the root logger is the ancestor of all loggers and chapter3 + is the parent of chapter3.MyApp2 and chapter3.Foo, + logging request made with these two loggers will be output twice, + once because STDOUT is attached to chapter3 and + once because it is attached to root. + - -Appender additivity is not intended as a trap for new users. -It is a quite convenient logback feature. For instance, you can configure -logging such that log messages appear on the console (for all loggers in the system) -while messages only from some specific set of loggers flow into a specific appender. - + Appender additivity is not intended as a trap for new users. It + is a quite convenient logback feature. For instance, you can + configure logging such that log messages appear on the console (for + all loggers in the system) while messages only from some specific + set of loggers flow into a specific appender. + -Example 3.10: Multiple appender (logback-examples/src/main/java/chapter3/restricted.xml) -<div class="source"><pre><configuration> + Example 3.: Multiple appender + (logback-examples/src/main/java/chapter3/restricted.xml) + <div class="source"><pre><configuration> <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> @@ -784,21 +854,21 @@ </root> </configuration></pre></div> - -In this example, the console appender will log all the messages (for all loggers in the system) -whereas only logs under the chapter3 tree go into the myApp.log file. - + In this example, the console appender will log all the messages + (for all loggers in the system) whereas only logs under the + chapter3 tree go into the myApp.log file. + -<h4>Overriding the default cumulative behaviour</h4> + <h4>Overriding the default cumulative behaviour</h4> - -In case the default cumulative behavior turns out to be unsuitable for -one's needs, one can override it by setting the additivity flag to false. -Thus, a branch in your logger tree may direct output to a set of appenders -different than those of the rest of the tree. - + In case the default cumulative behavior turns out to be + unsuitable for one's needs, one can override it by setting the + additivity flag to false. Thus, a branch in your logger tree may + direct output to a set of appenders different than those of the rest + of the tree. + -Example 3.11: Additivity flag (logback-examples/src/main/java/chapter3/additivityFlag.xml) +Example 3.: Additivity flag (logback-examples/src/main/java/chapter3/additivityFlag.xml) <div class="source"><pre><configuration> <appender name="FILE" @@ -834,44 +904,46 @@ </root> </configuration></pre></div> - -This example, the appender named FILE is attached to the chapter3.Foo -logger. Moreover, the chapter3.Foo logger has its additivity flag set to false -such that its logging output will be sent to the appender named FILE but -not to any appender attached higher in the hierarchy. Other loggers remain -oblivious to the additivity setting of the chapter3.Foo logger. -Running the <code>MyApp2</code> application with the additivityFlag.xml -configuration file will output results on the console from the chapter3.MyApp2 -logger. -However, output from the chapter3.Foo logger will appear in the foo.log file -and only in that file. - + This example, the appender named FILE is attached to the + chapter3.Foo logger. Moreover, the chapter3.Foo + logger has its additivity flag set to false such that its logging + output will be sent to the appender named FILE but not to + any appender attached higher in the hierarchy. Other loggers remain + oblivious to the additivity setting of the chapter3.Foo + logger. Running the <code>MyApp2</code> application with the + additivityFlag.xml configuration file will output results + on the console from the chapter3.MyApp2 logger. However, + output from the chapter3.Foo logger will appear in the + foo.log file and only in that file. + -<h4>Variable substitution</h4> + <h4>Variable substitution</h4> - -All option values admit variable substitution. The syntax of variable -substitution is similar to that of Unix shells. The string between an -opening ${ and closing } is interpreted as a key. -The value of the substituted variable can be defined as a system property -in the configuration file itself or in a separate file linked to the -configuration file. The value of the key -is first searched in configuration file or linked properties file, -and if not found there, it is then searched in system properties. -The corresponding value replaces ${aKey} sequence. For example, -if java.home.dir system property is set to /home/xyz, -then every occurrence of the sequence ${java.home.dir} will be -interpreted as /home/xyz. - + All option values admit variable substitution. The + syntax of variable substitution is similar to that of Unix + shells. The string between an opening ${ and closing + } is interpreted as a key. The value of the substituted + variable can be defined as a system property in the configuration + file itself or in a separate file linked to the configuration + file. The value of the key is first searched in configuration file + or linked properties file, and if not found there, it is then + searched in system properties. The corresponding value replaces + ${aKey} sequence. For example, if java.home.dir + system property is set to /home/xyz, then every occurrence + of the sequence ${java.home.dir} will be interpreted as + /home/xyz. + - -The first example shows a declared property at the beginning of the -configuration file. It is then used further down the file to specify -the place to create the output file. - + The first example shows a declared property at the beginning of the + configuration file. It is then used further down the file to specify + the place to create the output file. + -Example 3.12: Simple Variable substitution (logback-examples/src/main/java/chapter3/variableSubstitution1.xml) -<div class="source"><pre><configuration> + Example 3.: Simple Variable substitution + (logback-examples/src/main/java/chapter3/variableSubstitution1.xml) + + + <div class="source"><pre><configuration> <substitutionProperty name="user.home.dir" value="/Users/seb" /> @@ -898,13 +970,15 @@ </configuration></pre></div> - -The next example shows the use of a System property to achieve the same result. The -property is not declared anywhere, thus logback will look for it in the System properties. - + The next example shows the use of a System property to achieve the same result. The + property is not declared anywhere, thus logback will look for it in the System properties. + -Example 3.13: System Variable substitution (logback-examples/src/main/java/chapter3/variableSubstitution2.xml) -<div class="source"><pre><configuration> + Example 3.: System Variable substitution + (logback-examples/src/main/java/chapter3/variableSubstitution2.xml) + + + <div class="source"><pre><configuration> <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> @@ -928,14 +1002,17 @@ </root> </configuration></pre></div> - -When many variables are used, it is often more convenient to create -a separate file that will contain all the variables. Here is how one can -do such a setup. - + When many variables are used, it is often more convenient to + create a separate file that will contain all the variables. Here is + how one can do such a setup. + -Example 3.14: Variable substitution using a separate file (logback-examples/src/main/java/chapter3/variableSubstitution3.xml) -<div class="source"><pre><configuration> + Example 3.: Variable substitution using a + separate file + (logback-examples/src/main/java/chapter3/variableSubstitution3.xml) + + + <div class="source"><pre><configuration> <substitutionProperty file="variables1.properties" /> @@ -967,7 +1044,7 @@ logback configuration file. Here is what the variable.properties file looks like. -Example 3.15: Variable file (logback-examples/src/main/java/chapter3/variables1.properties) +Example 3.: Variable file (logback-examples/src/main/java/chapter3/variables1.properties) <div class="source"><pre>user.home.dir=/Users/seb</pre></div> @@ -981,18 +1058,20 @@ -Example 3.16: Recursive use of variables (logback-examples/src/main/java/chapter3/variables2.properties) +Example 3.: Recursive use of variables +(logback-examples/src/main/java/chapter3/variables2.properties) <div class="source"><pre>user.home.dir=/Users/seb fileName=myApp.log destination=${user.home.dir}/${fileName}</pre></div> - -In the configuration file, only the last variable, ${destination} will -be used, as shown below: - + In the configuration file, only the last variable, + ${destination} will be used, as shown below: + -Example 3.17: Variable substitution using a separate file (logback-examples/src/main/java/chapter3/variableSubstitution4.xml) -<div class="source"><pre><configuration> + Example 3.: Variable substitution using a separate file + (logback-examples/src/main/java/chapter3/variableSubstitution4.xml) + + <div class="source"><pre><configuration> <substitutionProperty file="variables1.properties" /> @@ -1018,27 +1097,30 @@ </root> </configuration></pre></div> -<a name="Include"></a> -<h3>File inclusion</h3> + <a name="Include"></a> + <h3>File inclusion</h3> - -It is possible to include configuration elements into a logback.xml -configuration file. This is done by using a include element, as shown -in the example below: - + It is possible to include configuration elements into a + logback.xml configuration file. This is done by using a + include element, as shown in the example below: + -Example 3.18: File include (logback-examples/src/main/java/chapter3/redirectConfig.xml) -<div class="source"><pre><configuration> + Example 3.: File include + (logback-examples/src/main/java/chapter3/redirectConfig.xml) + + <div class="source"><pre><configuration> <include file="path/to/configuration/file"/> -</configuration></pre></div> + </configuration></pre></div> - -The target file must have its elements nested inside an included -element. For example, a <code>ConsoleAppender</code> would be declared this way: - + The target file must have its elements nested inside an + included element. For example, a + <code>ConsoleAppender</code> would be declared this way: + -Example 3.18: File include (logback-examples/src/main/java/chapter3/includedConfig.xml) -<div class="source"><pre><included> + Example 3.: File include + (logback-examples/src/main/java/chapter3/includedConfig.xml) + + <div class="source"><pre><included> <appender name="redirectConsole" class="ch.qos.logback.core.ConsoleAppender"> @@ -1054,118 +1136,121 @@ </included></pre></div> -The file to be included can be referenced as a URL or as a -resource. To reference a URL use the <code>url</code> attribute -instead of the file attribute in the previous example. To reference a -resource, use the <code>resource</code> attribute instead of the file -attribute in the previous example. - + The file to be included can be referenced as a URL or as a + resource. To reference a URL use the <code>url</code> attribute + instead of the file attribute in the previous example. To reference + a resource, use the <code>resource</code> attribute instead of the + file attribute in the previous example. + -<a name="Joran"></a> -<h2>Using Joran in your own application</h2> -As we've seen, logback relies on Joran, a -mature, flexible and powerful configuration framework. Many of the -capabilities offered by logback modules are possible with the help of Joran. - + <a name="Joran"></a> + <h2>Using Joran in your own application</h2> -Joran is actually a generic configuration system which can be used -independently of logging. To emphaises this point, we should mention -that the logback-core module does not have a notion of loggers. In -that spirit, many of the examples related to this tutorial, have -nothing to do with loggers, appenders or layouts. - + As we've seen, logback relies on Joran, a mature, flexible and + powerful configuration framework. Many of the capabilities offered + by logback modules are possible with the help of Joran. + -The examples for this chapter can be found under -LOGBACK_HOME/logback-examples/src/main/java/chapter3. - + Joran is actually a generic configuration system which can be + used independently of logging. To emphaises this point, we should + mention that the logback-core module does not have a notion of + loggers. In that spirit, many of the examples related to this + tutorial, have nothing to do with loggers, appenders or layouts. + -To install joran, simply <a href="../download.html">download</a> -logback and add logback-core-VERSION.jar to your classpath. + The examples for this chapter can be found under + LOGBACK_HOME/logback-examples/src/main/java/chapter3. + -<h2>Historical perspective</h2> + To install joran, simply <a href="../download.html">download</a> + logback and add logback-core-VERSION.jar to your classpath. + + <h2>Historical perspective</h2> -One of the most powerful features of the Java language is -reflection. Reflection makes it possible to configure software systems -declaratively. For example, many important properties of an EJB are -configured with the ejb.xml file. While EJBs are written in Java, many -of their properties are specified within the ejb.xml file. Similarly, -logback settings can be specified in a configuration file, expressed -in XML format. - + One of the most powerful features of the Java language is + reflection. Reflection makes it possible to configure software systems + declaratively. For example, many important properties of an EJB are + configured with the ejb.xml file. While EJBs are written in Java, many + of their properties are specified within the ejb.xml file. Similarly, + logback settings can be specified in a configuration file, expressed + in XML format. + -In log4j, logback's predecessor, <code>DOMConfigurator</code> that -shipped with log4j version 1.2.x can parse configuration files written -in XML. The <code>DOMConfigurator</code> was written in a way that -forced to tweak it each time the structure of the configuration file -changed. The modified code had to be recompiled and redeployed. Just -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 -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 -small and specialized. Consequently, they are relatively easy to -understand and to maintain. - + In log4j, logback's predecessor, <code>DOMConfigurator</code> + that shipped with log4j version 1.2.x can parse configuration files + written in XML. The <code>DOMConfigurator</code> was written in a + way that forced to tweak it each time the structure of the + configuration file changed. The modified code had to be recompiled + and redeployed. Just 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 + 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 small and specialized. Consequently, they are relatively easy + to understand and to maintain. + -Joran is heavily inspired by the commons-digester project but uses -a slightly different terminology. In commons-digester, a rule can be -seen as consisting of a pattern and a rule, as shown by the -<code>Digester.addRule(String pattern, Rule rule)</code> method. We -find it unnecessarily confusing to have a rule to consist of itself, -not recursively but with a different meaning. In Joran, a rule -consists of a pattern and an action. An action is invoked when a match -occurs for the corresponding pattern. This relation between patterns -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 a/b will match a <code></code> element nested within -an <code><a></code> element but not a <code><c></code> element, -even if nested within a <code></code> element. It is also -possible to match a particular XML element, regardless of its nesting -level, by using the * wildcard character. For example, the pattern -*/a will match an <code><a></code> element at any nesting -position within the document. Other types of patterns, for example -a/*, are not currently supported by Joran. - + Joran is heavily inspired by the commons-digester project but + uses a slightly different terminology. In commons-digester, a rule + can be seen as consisting of a pattern and a rule, as shown by the + <code>Digester.addRule(String pattern, Rule rule)</code> method. We + find it unnecessarily confusing to have a rule to consist of itself, + not recursively but with a different meaning. In Joran, a rule + consists of a pattern and an action. An action is invoked when a + match occurs for the corresponding pattern. This relation between + patterns 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 a/b will match a + <code></code> element nested within an <code><a></code> + element but not a <code><c></code> element, even if nested within + a <code></code> element. It is also possible to match a + particular XML element, regardless of its nesting level, by using + the * wildcard character. For example, the pattern + */a will match an <code><a></code> element at any + nesting position within the document. Other types of patterns, for + example a/*, are not currently supported by Joran. + -<h2>SAX or DOM?</h2> + <h2>SAX or DOM?</h2> -Due to the event-based architecture of the SAX API, a tool based on -SAX cannot easily deal with forward references, that is, references to -elements which are defined later than the current element being -processed. Elements with cyclical references are equally -problematic. More generally, the DOM API allows the user to perform -searches on all the elements and make forward jumps. - + Due to the event-based architecture of the SAX API, a tool based + on SAX cannot easily deal with forward references, that is, + references to elements which are defined later than the current + element being processed. Elements with cyclical references are + equally problematic. More generally, the DOM API allows the user to + perform searches on all the elements and make forward jumps. + -This extra flexibility initially led us to choose the DOM API as -the underlying parsing API for Joran. After some experimentation, it -quickly became clear that dealing with jumps to distant elements while -parsing the DOM tree did not make sense when the interpretation rules -were expressed in the form of patterns and actions. Joran only -needs to be given the elements in the XML document in a sequential, -depth-first order. - + This extra flexibility initially led us to choose the DOM API as + the underlying parsing API for Joran. After some experimentation, it + quickly became clear that dealing with jumps to distant elements + while parsing the DOM tree did not make sense when the + interpretation rules were expressed in the form of patterns and + actions. Joran only needs to be given the elements in the XML + document in a sequential, depth-first order. + -Joran was first implemented in DOM. However, the author migrated to -SAX in order to benefit form the location information provided to the -user, that is, to an <code>org.w3.sax.ContentHandler</code>. With the -help of location information, it becomes possible to display essential -error reports to the user which include exact line and column. This -extra information turns out to be handy in hunting down problems. - + Joran was first implemented in DOM. However, the author migrated + to SAX in order to benefit form the location information provided to + the user, that is, to an + <code>org.w3.sax.ContentHandler</code>. With the help of location + information, it becomes possible to display essential error reports + to the user which include exact line and column. This extra + information turns out to be handy in hunting down problems. + -<h2>Actions</h2> + <h2>Actions</h2> -Actions extend the -<code>ch.qos.logback.core.joran.action.Action</code> class which -consists of the following abstract methods. - + Actions extend the + <code>ch.qos.logback.core.joran.action.Action</code> class which + consists of the following abstract methods. + <div class="source"><pre>package ch.qos.logback.core.joran.action; @@ -1191,139 +1276,155 @@ public abstract void end(ExecutionContext ec, String name); }</pre></div> -Thus, every action must implement the begin and end methods. + Thus, every action must implement the begin and end methods. -<h2>Execution context</h2> + <h2>Execution context</h2> -To allow various actions to collaborate, the invocation of begin -and end methods include an execution context as the first -parameter. The execution context includes an object stack, an object -map, an error list and a reference to the Joran interpreter invoking -the action. Please see the -<code>ch.qos.logback.core.joran.spi.ExecutionContext</code> class for -the exact list of fields contained in the execution context. - + To allow various actions to collaborate, the invocation of begin + and end methods include an execution context as the first + parameter. The execution context includes an object stack, an object + map, an error list and a reference to the Joran interpreter invoking + the action. Please see the + <code>ch.qos.logback.core.joran.spi.ExecutionContext</code> class + for the exact list of fields contained in the execution context. + -Actions can collaborate together by fetching, pushing or popping -objects from the common object stack, or by putting and fetching keyed -objects on the common object map. Actions can report any error -conditions by adding error items on the execution context's -<code>StatusManager</code>. - + Actions can collaborate together by fetching, pushing or popping + objects from the common object stack, or by putting and fetching + keyed objects on the common object map. Actions can report any error + conditions by adding error items on the execution context's + <code>StatusManager</code>. + -<a name="helloWorld"></a> -<h3>A hello world example</h3> + <a name="helloWorld"></a> + <h3>A hello world example</h3> -The logback-examples/src/main/java/chapter3/helloWorld/ directory includes a -trivial action and Joran interpreter setup which just displays Hello -World when a <hello-world> element is encountered in an XML file. -It also includes the basic steps which are -necessary to set up and invoke a Joran interpreter. - - -The hello.xml 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 -it's <code>begin()</code> method is called. - - -<a href="../xref/chapter3/helloWorld/HelloWorld.html"><code>HelloWorld</code></a> -is a class that sets up the Joran interpreter, -with the minimal steps necessary: - + The logback-examples/src/main/java/chapter3/helloWorld/ + directory includes a trivial action and Joran interpreter setup + which just displays Hello World when a <hello-world> + element is encountered in an XML file. It also includes the basic + steps which are necessary to set up and invoke a Joran interpreter. + -<ul> - It creates a <code>RuleStore</code> and a <code>Context</code> - It adds the hello-world pattern, with it's corresponding action - It creates a Joran interpreter, and passes the <code>RuleStore</code> - It creates a SAX parser and parses the given file, specifying the newly created - Joran interpreter as the <code>ContentHandler</code> -</ul> + The hello.xml 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 it's + <code>begin()</code> method is called. + - -It's last step is to print the content of the <code>Context</code>. -Since Joran uses logback's powerfull <code>Status</code> objects for -error reporting, one can have a good feedback on what happened during -the parsing. - + <a + href="../xref/chapter3/helloWorld/HelloWorld.html"><code>HelloWorld</code></a> + is a class that sets up the Joran interpreter, with the minimal + steps necessary: + - -In this example, the parsing is rather simple. The hello-world element -will activate <code>HelloWorldAction</code>'s <code>begin()</code> and -<code>end()</code> methods. -In the first method, a simple call to <code>System.out.println()</code> -will be issued, displaying Hello World in the console. - + <ul> + <li>It creates a <code>RuleStore</code> and a <code>Context</code></li> + <li>It adds the hello-world pattern, with it's corresponding action</li> + <li>It creates a Joran interpreter, and passes the <code>RuleStore</code></li> + <li>It creates a SAX parser and parses the given file, specifying the newly created + Joran interpreter as the <code>ContentHandler</code></li> + </ul> + + It's last step is to print the content of the + <code>Context</code>. Since Joran uses logback's powerfull + <code>Status</code> objects for error reporting, one can have a good + feedback on what happened during the parsing. + -<a name="calculator"></a> -<h3>Collaborating actions</h3> - -The logback-examples/src/main/java/joran/calculator/ directory includes several actions -which collaborate together through the common object stack in order -to accomplish simple computations. - - -The calculator1.xml file contains a <code>computation</code> element, -with a nested <code>literal</code> element. - - -In the <a href="../xref/chapter3/calculator/Calculator1.html"> -<code>Calculator1</code></a> class, we declare various patterns and actions, -that will collaborate and calculate a result based on the xml file. The simple -calculator1.xml file only creates a computation and declares a literal -value. The resulting parsing is pretty simple: - -<ul> - The <a href="../xref/chapter3/calculator/ComputationAction1.html"> - <code>ComputationAction1</code></a> class' <code>begin()</code> method - is called - The <a href="../xref/chapter3/calculator/LiteralAction.html"> - <code>LiteralAction</code></a> class' <code>begin()</code> and <code>end()</code> - methods are called - The <a href="../xref/chapter3/calculator/ComputationAction1.html"> - <code>ComputationAction1</code></a> class' <code>end()</code> method - is called -</ul> - -What is interesting here is the way that the Actions collaborate. -The <code>LiteralAction</code> reads a literal value and pushes it in the -object stack maintained by the <code>ExecutionContext</code>. Once done, -any other action can pop the value to read or modify it. Here, the -<code>end()</code> method of the <code>ComputationAction1</code> class pops -the value from the stack and prints it. - -The calculator2.xml file is a bit more complex, but much more interesting. -It contains the following elements: + In this example, the parsing is rather simple. The + hello-world element will activate + <code>HelloWorldAction</code>'s <code>begin()</code> and + <code>end()</code> methods. In the first method, a simple call to + <code>System.out.println()</code> will be issued, displaying + Hello World in the console. + -Example 3.19: Calculator configuration file (logback-examples/src/main/java/chapter3/calculator/calculator2.xml) -<div class="source"><pre><computation name="toto"> + <a name="calculator"></a> + <h3>Collaborating actions</h3> + + The logback-examples/src/main/java/joran/calculator/ + directory includes several actions which collaborate together + through the common object stack in order to accomplish simple + computations. + + + The calculator1.xml file contains a <code>computation</code> + element, with a nested <code>literal</code> element. + + + In the <a href="../xref/chapter3/calculator/Calculator1.html"> + <code>Calculator1</code></a> class, we declare various patterns and + actions, that will collaborate and calculate a result based on the + xml file. The simple calculator1.xml file only creates a + computation and declares a literal value. The resulting parsing is + pretty simple: + + + <ul> + <li>The <a href="../xref/chapter3/calculator/ComputationAction1.html"> + <code>ComputationAction1</code></a> class' <code>begin()</code> method + is called</li> + <li>The <a href="../xref/chapter3/calculator/LiteralAction.html"> + <code>LiteralAction</code></a> class' <code>begin()</code> and <code>end()</code> + methods are called</li> + <li>The <a href="../xref/chapter3/calculator/ComputationAction1.html"> + <code>ComputationAction1</code></a> class' <code>end()</code> method + is called</li> + </ul> + What is interesting here is the way that the Actions collaborate. + The <code>LiteralAction</code> reads a literal value and pushes it + in the object stack maintained by the + <code>ExecutionContext</code>. Once done, any other action can pop + the value to read or modify it. Here, the <code>end()</code> method + of the <code>ComputationAction1</code> class pops the value from the + stack and prints it. + + + The calculator2.xml file is a bit more complex, but much + more interesting. + + It contains the following elements: + + Example 3.: Calculator configuration file (logback-examples/src/main/java/chapter3/calculator/calculator2.xml) + <div class="source"><pre><computation name="toto"> <literal value="7"/> <literal value="3"/> <add/> <literal value="3"/> <multiply/> </computation></pre></div> - -Here, there are obviously more actions that will be part of the computation. - -When called, the <a href="../xref/chapter3/calculator/AddAction.html"> -<code>AddAction</code></a> class will remove the two integers at -the bottom of the stack, add them and push the resulting integer at the -top of the stack, for further use. -Later in the computation, the <a href="../xref/chapter3/calculator/MultiplyAction.html"> -<code>MultiplyAction</code></a> class will be called. -It will take the last two integers from the stack, multiply them and -push the result in the stack. -We have here two examples of action whose <code>begin()</code> method behaves in -a certain, predictable way, but whose <code>end()</code> methods are empty. - -Finally, a calculator3.xml is also provided, to demonstrate the possibility -elements that contain instances of the same element. Here's the content of -calculator3.xml: -Example 3.20: Calculator configuration file (logback-examples/src/main/java/chapter3/calculator/calculator3.xml) + Here, there are obviously more actions that will be part of the + computation. + + + When called, the <a + href="../xref/chapter3/calculator/AddAction.html"> + <code>AddAction</code></a> class will remove the two integers at the + bottom of the stack, add them and push the resulting integer at the + top of the stack, for further use. + + Later in the computation, the <a + href="../xref/chapter3/calculator/MultiplyAction.html"> + <code>MultiplyAction</code></a> class will be called. It will take + the last two integers from the stack, multiply them and push the + result in the stack. + + We have here two examples of action whose <code>begin()</code> + method behaves in a certain, predictable way, but whose + <code>end()</code> methods are empty. + + Finally, a calculator3.xml is also provided, to + demonstrate the possibility elements that contain instances of the + same element. Here's the content of calculator3.xml: + + Example 3.: Calculator configuration file + (logback-examples/src/main/java/chapter3/calculator/calculator3.xml) + <div class="source"><pre><computation name="toto"> <computation> <literal value="7"/> @@ -1335,43 +1436,56 @@ <multiply/> </computation></pre></div> -Much like the use of parentheses in an algebrical equation, the presence of -a <code>computation</code> element nested in another is managed by the -<a href="../xref/chapter3/calculator/ComputationAction2.html"> -<code>ComputationAction2</code></a> class using an internal stack. The well-formedness -of XML will guarantee that a value saved by one <code>begin()</code> will be consumed -only by the matching <code>end()</code> method. - -<a name="newRule"></a> -<h3>New-rule action</h3> -Joran includes an action which allows the Joran interpreter to lean -new rules on the fly while interpreting the XML file containing the -new rules. See the logback-examples/src/main/java/joran/newRule/ -directory for sample code. - -In this package, the <a href="../xref/chapter3/newRule/NewRuleCalculator.html"> -<code>NewRuleCalculator</code></a> class contains -the same setup as we have seen so far, but for one line: - -<source>ruleStore.addRule(new Pattern("/computation/new-rule"), new NewRuleAction());</source> - -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 -<code>begin()</code> and <code>end()</code> method, and is called each time -the parser finds a new-rule element. - -When called, the <code>begin()</code> method looks for a pattern -and a actionClass attribute. The action class is then instanciated -and added to the <code>RuleStore</code>, along with its corresponding pattern. - -Here is how new rules can be declared in an xml file: - -<div class="source"><pre><new-rule pattern="*/computation/literal" actionClass="chapter3.calculator.LiteralAction"/></pre></div> + Much like the use of parentheses in an algebrical equation, the + presence of a <code>computation</code> element nested in another is + managed by the <a + href="../xref/chapter3/calculator/ComputationAction2.html"> + <code>ComputationAction2</code></a> class using an internal + stack. The well-formedness of XML will guarantee that a value saved + by one <code>begin()</code> will be consumed only by the matching + <code>end()</code> method. + + <a name="newRule"></a> + + <h3>New-rule action</h3> + + Joran includes an action which allows the Joran interpreter to + lean new rules on the fly while interpreting the XML file containing + the new rules. See the + logback-examples/src/main/java/joran/newRule/ directory for + sample code. + -Using new rule declarations, the preceding example, involving the calculation, could be -expressed this way: + In this package, the <a + href="../xref/chapter3/newRule/NewRuleCalculator.html"> + <code>NewRuleCalculator</code></a> class contains the same setup as + we have seen so far, but for one line: + + ruleStore.addRule(new + Pattern("/computation/new-rule"), new NewRuleAction()); + + 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 + <code>begin()</code> and <code>end()</code> method, and is called each time + the parser finds a new-rule element. + + When called, the <code>begin()</code> method looks for a + pattern and a actionClass attribute. The action + class is then instanciated and added to the <code>RuleStore</code>, + along with its corresponding pattern. + + Here is how new rules can be declared in an xml file: + +<div class="source"><pre><new-rule pattern="*/computation/literal" +actionClass="chapter3.calculator.LiteralAction"/></pre></div> + + Using new rule declarations, the preceding example, involving the + calculation, could be expressed this way: + + Example 3.: Configuration file using new + rules on the fly + (logback-examples/src/main/java/chapter3/newrule/new-rule.xml) -Example 3.21: Configuration file using new rules on the fly (logback-examples/src/main/java/chapter3/newrule/new-rule.xml) <div class="source"><pre><computation name="toto"> <new-rule pattern="*/computation/literal" actionClass="chapter3.calculator.LiteralAction"/> @@ -1390,88 +1504,96 @@ <multiply/> </computation></pre></div> -<a name="implicit"></a> -<h3>Implicit actions </h3> -The rules defined thus far are called explicit rules because they -require an explicit pattern, hence fixing the tag name of the elements -for which they apply. - + <a name="implicit"></a> + <h3>Implicit actions </h3> -In highly extensible systems, the number and type of components to -handle are innumerable so that it would become very tedious or even -impossible to list all the applicable patterns by name. - - -At the same time, even in highly extensible systems one can observe -well-defined patterns linking the various parts together. Implicit -rules come in very handy when processing components composed of -sub-components unknown ahead of time. For example, Apache Ant is -capable of handling tasks which contain tags unknown at compile time -by looking at methods whose names start with add, as in -<code>addFile</code>, or <code>addClassPath</code>. -When Ant encounters an embedded tag within a task, it -simply instantiates an object that matches the signature of the task -class' add method and attaches the resulting object to the parent. - - -Joran includes similar capability in the form of implicit -actions. Joran keeps a list of implicit actions which can be applied -if no explicit pattern matches the current XML element. However, -applying an implicit action may not be always appropriate. Before -executing the implicit action, Joran asks an implicit action whether -it is appropriate in the current context. Only if the action replies -affirmatively does Joran interpreter invoke the (implicit) -action. This extra step makes it possible to support multiple implicit -actions or obviously none, if no implicit action is appropriate for a -given situation. - - -For example, the <a href="../xref/ch/qos/logback/core/joran/action/NestedComponentIA.html"> -<code>NestedComponentIA</code></a> extending -<a href="../xref/ch/qos/logback/core/joran/action/ImplicitAction.html"> -<code>ImplicitAction</code></a> , will -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 nested within <a>. The current -implementation of <code>NestedComponentIA</code> is capable of -handling multiply nested elements requiring intervention by the same -implicit action. - + The rules defined thus far are called explicit rules because they + require an explicit pattern, hence fixing the tag name of the + elements for which they apply. + -Both <code>ImplicitAction</code> and <code>NestedComponentIA</code> are located in the -<code>ch.qos.logback.core.joran.action</code> package. - + In highly extensible systems, the number and type of components + to handle are innumerable so that it would become very tedious or + even impossible to list all the applicable patterns by name. + -Refer to the logback-examples/src/main/java/joran/implicit -directory for an example of an implicit action. - + At the same time, even in highly extensible systems one can + observe well-defined patterns linking the various parts + together. Implicit rules come in very handy when processing + components composed of sub-components unknown ahead of time. For + example, Apache Ant is capable of handling tasks which contain tags + unknown at compile time by looking at methods whose names start with + add, as in <code>addFile</code>, or + <code>addClassPath</code>. When Ant encounters an embedded tag + within a task, it simply instantiates an object that matches the + signature of the task class' add method and attaches the resulting + object to the parent. + -In that directory, you will find two actions classes, one xml file and one -class containing the setup of Joran. + Joran includes similar capability in the form of implicit + actions. Joran keeps a list of implicit actions which can be applied + if no explicit pattern matches the current XML element. However, + applying an implicit action may not be always appropriate. Before + executing the implicit action, Joran asks an implicit action whether + it is appropriate in the current context. Only if the action replies + affirmatively does Joran interpreter invoke the (implicit) + action. This extra step makes it possible to support multiple + implicit actions or obviously none, if no implicit action is + appropriate for a given situation. + -The <a href="../xref/chapter3/implicit/NOPAction.html"> -<code>NOPAction</code></a> class does nothing. It is used to set -the context of the foo element, using this line: + For example, the <a + href="../xref/ch/qos/logback/core/joran/action/NestedComponentIA.html"> + <code>NestedComponentIA</code></a> extending <a + href="../xref/ch/qos/logback/core/joran/action/ImplicitAction.html"> + <code>ImplicitAction</code></a> , will 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 nested within <a>. The current implementation of + <code>NestedComponentIA</code> is capable of handling multiply + nested elements requiring intervention by the same implicit action. + -<source>ruleStore.addRule(new Pattern("*/foo"), new NOPAction());</source> + Both <code>ImplicitAction</code> and + <code>NestedComponentIA</code> are located in the + <code>ch.qos.logback.core.joran.action</code> package. + -After that, the implicit action, namely -<a href="../xref/chapter3/implicit/PrintMeImplicitAction.html"> -<code>PrintMeImplicitAction</code></a>, -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> + Refer to the + logback-examples/src/main/java/joran/implicit directory for + an example of an implicit action. + -<source>ji.addImplicitAction(new PrintMeImplicitAction());</source> + In that directory, you will find two actions classes, one xml + file and one class containing the setup of Joran. -When called, the <code>isApplicable()</code> method of <code>PrintMeImplicitAction</code> -checks the value of the printme attribute. If the value is <code>true</code>, -the implicit action is applicable: its <code>begin()</code> method will be called. + The <a href="../xref/chapter3/implicit/NOPAction.html"> + <code>NOPAction</code></a> class does nothing. It is used to set the + context of the foo element, using this line: + + ruleStore.addRule(new Pattern("*/foo"), new NOPAction()); + + After that, the implicit action, namely <a + href="../xref/chapter3/implicit/PrintMeImplicitAction.html"> + <code>PrintMeImplicitAction</code></a>, 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> + + ji.addImplicitAction(new + PrintMeImplicitAction()); + + When called, the <code>isApplicable()</code> method of + <code>PrintMeImplicitAction</code> checks the value of the + printme attribute. If the value is <code>true</code>, the + implicit action is applicable: its <code>begin()</code> method will + be called. -The implicit1.xml file contains the following lines: + The implicit1.xml file contains the following lines: -Example 3.22: Usage of implicit rules (logback-examples/src/main/java/chapter3/implicit/implicit1.xml) + Example 3.: Usage of implicit rules + (logback-examples/src/main/java/chapter3/implicit/implicit1.xml) <div class="source"><pre><foo> <xyz printme="true"> @@ -1484,31 +1606,33 @@ </foo></pre></div> -As one can see, the first element will be printed, since it has a printme -attribute, which bears the value <code>true</code>. - -The second element will not be printed, because no printme attibute is present. + As you can see, the first element will be printed, since it has a + printme attribute, which bears the value + <code>true</code>. + + The second element will not be printed, because no printme attibute is present. + + The last element will not be printed, although the required + attribute is present. This is because implicit rules are called + only if no explicit rules are defined. Since we added a + <code>NOPAction</code> with the */foo pattern, it will be + used instead of the <code>PrintMeImplicitAction</code>. -The last element will not be printed, although the required attribute is present. -This is because implicit rules are called only if no explicit rules are defined. Since -we added a <code>NOPAction</code> with the */foo pattern, it will be used instead -of the <code>PrintMeImplicitAction</code>. - -Running the example yields the following output: + Running the example yields the following output: <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> -The last line was printed because of a call to <code>StatusPrinter</code> at the end -of the main class. + The last line was printed because of a call to + <code>StatusPrinter</code> at the end of the main class. -<h3>Non goals</h3> + <h3>Non goals</h3> -The Joran API is not intended to be used to parse documents with -thousands of elements. - + The Joran API is not intended to be used to parse documents with + thousands of elements. +

1 0

svn commit: r1755 - logback/trunk/logback-examples/src/main/java/chapter3
by noreply.ceki＠qos.ch 14 Aug '08

14 Aug '08

Author: ceki Date: Thu Aug 14 18:01:22 2008 New Revision: 1755 Added: logback/trunk/logback-examples/src/main/java/chapter3/MyApp3.java Modified: logback/trunk/logback-examples/src/main/java/chapter3/MyApp2.java Log: working on the 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 Aug 14 18:01:22 2008 @@ -14,29 +14,18 @@ import org.slf4j.LoggerFactory; import ch.qos.logback.classic.LoggerContext; -import ch.qos.logback.classic.joran.JoranConfigurator; -import ch.qos.logback.core.joran.spi.JoranException; import ch.qos.logback.core.util.StatusPrinter; public class MyApp2 { final static Logger logger = LoggerFactory.getLogger(MyApp2.class); public static void main(String[] args) { - // assume logback is in use + logger.info("Entering application."); + + // print logback's internal status LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); + StatusPrinter.print(lc); - - try { - JoranConfigurator configurator = new JoranConfigurator(); - configurator.setContext(lc); - lc.shutdownAndReset(); - configurator.doConfigure(args[0]); - } catch (JoranException je) { - StatusPrinter.print(lc); - } - - logger.info("Entering application."); - Foo foo = new Foo(); foo.doIt(); logger.info("Exiting application."); Added: logback/trunk/logback-examples/src/main/java/chapter3/MyApp3.java ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter3/MyApp3.java Thu Aug 14 18:01:22 2008 @@ -0,0 +1,47 @@ +/** + * Logback: the reliable, generic, fast and flexible logging framework. + * + * Copyright (C) 1999-2008, QOS.ch + * + * This library is free software, you can redistribute it and/or modify it under + * the terms of the GNU Lesser General Public License as published by the Free + * Software Foundation. + */ + +package chapter3; + +/** + * Demonstrates programmatic invocation of Joran. + * + */ +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.joran.spi.JoranException; +import ch.qos.logback.core.util.StatusPrinter; + +public class MyApp3 { + final static Logger logger = LoggerFactory.getLogger(MyApp3.class); + + public static void main(String[] args) { + // assume logback is in use + LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); + + try { + JoranConfigurator configurator = new JoranConfigurator(); + configurator.setContext(lc); + lc.shutdownAndReset(); + configurator.doConfigure(args[0]); + } catch (JoranException je) { + StatusPrinter.print(lc); + } + + logger.info("Entering application."); + + Foo foo = new Foo(); + foo.doIt(); + logger.info("Exiting application."); + } +}

1 0

svn commit: r1754 - in logback/trunk/logback-site/src/site/pages: . templates
by noreply.ceki＠qos.ch 10 Aug '08

10 Aug '08

Author: ceki Date: Sun Aug 10 23:29:21 2008 New Revision: 1754 Modified: logback/trunk/logback-site/src/site/pages/dependencies.html logback/trunk/logback-site/src/site/pages/documentation.html logback/trunk/logback-site/src/site/pages/templates/left.js logback/trunk/logback-site/src/site/pages/templates/right.js Log: - minor improvements to the docs Modified: logback/trunk/logback-site/src/site/pages/dependencies.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/dependencies.html (original) +++ logback/trunk/logback-site/src/site/pages/dependencies.html Sun Aug 10 23:29:21 2008 @@ -37,9 +37,7 @@ <td>Overall</td> <td> <ul> - <li>JDK 1.5, unless you are using the retro-translated - logback-core-${project.version}-jdk14.jar which - requires JDK 1.4 + <li>JDK 1.5 </li> </ul> </td> @@ -94,9 +92,7 @@ <td>Overall</td> <td> <ul> - <li>JDK 1.5, unless you are using the retro-translated - logback-classic-${project.version}-jdk14.jar which - requires JDK 1.4 + <li>JDK 1.5 </li> </ul> </td> @@ -178,9 +174,7 @@ <td>Overall</td> <td> <ul> - <li>JDK 1.5, unless you are using the retro-translated - logback-classic-${project.version}-jdk14.jar which - requires JDK 1.4 + <li>JDK 1.5 </li> </ul> </td> Modified: logback/trunk/logback-site/src/site/pages/documentation.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/documentation.html (original) +++ logback/trunk/logback-site/src/site/pages/documentation.html Sun Aug 10 23:29:21 2008 @@ -71,7 +71,11 @@ logback</a>, by Ceki Gülcü and Sébastien Pennec. </li> - </ul> + + <li><a href="http://www.infoq.com/news/2007/08/logback">Logback: + Evolving Java Logging</a> by Geoffrey Wiseman + + </ul> <script src="templates/footer.js"></script> </div> Modified: logback/trunk/logback-site/src/site/pages/templates/left.js ============================================================================== --- logback/trunk/logback-site/src/site/pages/templates/left.js (original) +++ logback/trunk/logback-site/src/site/pages/templates/left.js Sun Aug 10 23:29:21 2008 @@ -8,7 +8,7 @@ document.write('<a href="' + prefix + 'repos.html">Source Repository</a>'); document.write('<a href="' + prefix + 'bugreport.html">Bug Report</a>'); document.write('<a href="' + prefix + 'license.html">License</a>'); -document.write('<a href="http://logback.qos.ch/translator/">Log4j Properties Translator</a>'); +document.write('<a href="http://logback.qos.ch/translator/">log4j.properties Translator</a>'); document.write('<a href="' + prefix + 'team.html">Logback Team</a>'); document.write('<a class="x" href="http://www.qos.ch/"><img src="' + prefix + 'images/logos/qosLogo.png" /></a>'); Modified: logback/trunk/logback-site/src/site/pages/templates/right.js ============================================================================== --- logback/trunk/logback-site/src/site/pages/templates/right.js (original) +++ logback/trunk/logback-site/src/site/pages/templates/right.js Sun Aug 10 23:29:21 2008 @@ -4,6 +4,8 @@ document.write('<a href="http://stubbisms.wordpress.com/2008/07/15/some-serious-logging-niceness-log…">Logging niceness</a>') +document.write('<a href="http://wimpi.coalevo.net/2008/04/logger-name-based-filtering-in-logback.html">Filtering by logger name</a>') + document.write('<a href="http://wizardforge.org/pc?action=showVersion&id=72">Configuration Wizard</a>') document.write('<a href="http://xhab.blogspot.com/2007/03/new-logging-experience.html">A new logging experience!</a>')

1 0

svn commit: r1753 - logback/trunk/logback-site/src/site/pages
by noreply.ceki＠qos.ch 10 Aug '08

10 Aug '08

Author: ceki Date: Sun Aug 10 23:28:26 2008 New Revision: 1753 Modified: logback/trunk/logback-site/src/site/pages/faq.html Log: added an entry about the choice of LGPL Modified: logback/trunk/logback-site/src/site/pages/faq.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/faq.html (original) +++ logback/trunk/logback-site/src/site/pages/faq.html Sun Aug 10 23:28:26 2008 @@ -20,12 +20,20 @@ <div id="content"> <h2> - <a name="top">Logback Frequently Asked Questions</a> + <a name="top">Frequently Asked Questions</a> </h2> + + <h3>Logback project</h3> + + <ol type="1"> + <li><a href="#why_lgpl">Why is logback distributed under LGPL and + not the Apache Software License?</a> + </li> + </ol> + - - Logback Classic - + <h3>Logback Classic</h3> + <ol type="1"> <li> @@ -51,7 +59,31 @@ </ol> <div class="section"> - <h2>Logback Classic</h2> + <h2>Logback project</h2> + + <dl> + <dt> <a name="why_lgpl">Why is logback distributed under LGPL and + not the Apache Software License?</a> + </dt> + + <dd> + The logback project is distributed under the LGPL license + in order to emphasize the fact that it is a related but + different project than log4j. + + + Given that Java v7 will be distributed under GPL, we expect + GPL and LGPL to become even more prevalent in the Java world. + + + In short, LGPL is a reasonable and widely-accepted + license. Let well alone. + + </dd> + </dl> + </div> + <div class="section"> + <h2>Logback-classic</h2> <dl> <dt> <a name="setup_jetty">

1 0

svn commit: r1752 - in logback/trunk/logback-site/src/site/pages: . css manual templates
by noreply.ceki＠qos.ch 09 Aug '08

09 Aug '08

Author: ceki Date: Sat Aug 9 23:42:09 2008 New Revision: 1752 Modified: logback/trunk/logback-site/src/site/pages/css/site.css logback/trunk/logback-site/src/site/pages/documentation.html logback/trunk/logback-site/src/site/pages/download.html logback/trunk/logback-site/src/site/pages/manual/architecture.html logback/trunk/logback-site/src/site/pages/templates/right.js Log: - improving the docs Modified: logback/trunk/logback-site/src/site/pages/css/site.css ============================================================================== --- logback/trunk/logback-site/src/site/pages/css/site.css (original) +++ logback/trunk/logback-site/src/site/pages/css/site.css Sat Aug 9 23:42:09 2008 @@ -226,6 +226,10 @@ background-color: #eee; } +table.bodyTable tr.alt { + background-color: #eee; +} + .author { text-align: left; font-weight: bold; Modified: logback/trunk/logback-site/src/site/pages/documentation.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/documentation.html (original) +++ logback/trunk/logback-site/src/site/pages/documentation.html Sat Aug 9 23:42:09 2008 @@ -38,11 +38,7 @@ <li> <a href="dependencies.html">Dependencies per module</a> </li> - - - <li> - <a href="bridge.html">How to use the log4j bridge</a> - </li> + <li> <a href="jmxConfig.html">How to use the logback JMX Configurator</a> </li> Modified: logback/trunk/logback-site/src/site/pages/download.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/download.html (original) +++ logback/trunk/logback-site/src/site/pages/download.html Sat Aug 9 23:42:09 2008 @@ -84,7 +84,7 @@ </dt> <dd> - Lilith is a Logging- and AccessEvent viewer for LOGBack. + Lilith is a Logging- and AccessEvent viewer for logback. </dd> Modified: logback/trunk/logback-site/src/site/pages/manual/architecture.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/architecture.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/architecture.html Sat Aug 9 23:42:09 2008 @@ -46,35 +46,35 @@ The core module lays the groundwork for the other two - modules. The classic module extends core. 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 - access 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>. + modules. The classic module extends core. 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 java.util.logging (JUL) introduced in JDK + 1.4. The third module called access 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>. - - In the reminder of this document, we will write "logback" to refer to the - logback classic module. + + In the reminder of this document, we will write "logback" to + refer to the logback-classic module. <h2>Logger, Appenders and Layouts</h2> - - 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. + Logback is built upon three main classes: <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. - - 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. + + The <code>Logger</code> class is part of the logback-classic + module. On the other hand, the <code>Appender</code> and + <code>Layout</code> interfaces are part of logback-core. As a + general-purpose module, logback-core has no notion of loggers. <a name="LoggerContext"></a> @@ -85,8 +85,8 @@ 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. + according to some developer-chosen criteria. In logback-classic, + this categorization is an inherent part of loggers. @@ -140,27 +140,24 @@ public void fatal(String message); }</pre></div> - - 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. + 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 <code>Marker</code> + objects. - - If a given logger is not assigned a level, then it inherits - one from its closest ancestor with an assigned level. More - formally: + If a given logger is not assigned a level, then it inherits one + from its closest ancestor with an assigned level. More formally: <div class="definition"> <div class="deftitle">Level Inheritance</div> - - The effective level for a given logger L, is equal to - the first non-null level in its hierarchy, starting at - L itself and proceeding upwards in the hierarchy - towards the root logger. + The effective level for a given logger L, is equal + to the first non-null level in its hierarchy, starting at + L itself and proceeding upwards in the hierarchy + towards the root logger. </div> @@ -178,34 +175,27 @@ Example 1 <table class="bodyTable"> <tr> - <th> - Logger name - </th> - <th> - Assigned level - </th> - - <th> - Effective level - </th> + <th>Logger name</th> + <th>Assigned level</th> + <th>Effective level</th> </tr> - <tr class="a"> + <tr class="alt"> <td>root</td> <td>DEBUG</td> <td>DEBUG</td> </tr> - <tr class="b"> + <tr> <td>X</td> <td>none</td> <td>DEBUG</td> </tr> - <tr class="a"> + <tr class="alt"> <td>X.Y</td> <td>none</td> <td>DEBUG</td> </tr> - <tr class="b"> + <tr> <td>X.Y.Z</td> <td>none</td> <td>DEBUG</td> @@ -218,20 +208,13 @@ Example 2 - <table> + <table class="bodyTable"> <tr> - <th> - Logger name - </th> - <th> - Assigned level - </th> - - <th> - Effective level - </th> + <th>Logger name</th> + <th>Assigned level</th> + <th>Effective level</th> </tr> - <tr align="left"> + <tr class="alt" align="left"> <td>root</td> <td>ERROR</td> <td>ERROR</td> @@ -242,7 +225,7 @@ <td>INFO</td> </tr> - <tr align="left"> + <tr class="alt" align="left"> <td>X.Y</td> <td>DEBUG</td> <td>DEBUG</td> @@ -259,19 +242,13 @@ Example 3 - <table> + <table class="bodyTable"> <tr> - <th> - Logger name - </th> - <th> - Assigned level - </th> - <th> - Effective level - </th> + <th>Logger name</th> + <th>Assigned level</th> + <th>Effective level</th> </tr> - <tr align="left"> + <tr class="alt" align="left"> <td>root</td> <td>DEBUG</td> <td>DEBUG</td> @@ -282,7 +259,7 @@ <td>INFO</td> <td>INFO</td> </tr> - <tr align="left"> + <tr class="alt" align="left"> <td>X.Y</td> <td>none</td> <td>INFO</td> @@ -293,28 +270,23 @@ <td>ERROR</td> </tr> </table> - - 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>. + + 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>. + Example 4 - <table> + <table class="bodyTable"> <tr> - <th> - Logger name - </th> - <th> - Assigned level - </th> - <th> - Effective level - </th> + <th>Logger name</th> + <th>Assigned level</th> + <th>Effective level</th> </tr> - <tr align="left"> + <tr class="alt" align="left"> <td>root</td> <td>DEBUG</td> <td>DEBUG</td> @@ -325,7 +297,7 @@ <td>INFO</td> <td>INFO</td> </tr> - <tr align="left"> + <tr class="alt" align="left"> <td>X.Y</td> <td>none</td> <td>INFO</td> @@ -346,6 +318,7 @@ <a name="PrintintMethods"></a> + <a name="basic_selection"></a> <h3>Printing methods</h3> By definition, the printing method determines the level of a @@ -354,25 +327,27 @@ logging statement of level INFO. + A logging request is said to be enabled if its level - is higher than or equal to the level of its logger. Otherwise, the - request is said to be disabled. A logger without an - assigned level will inherit one from the context. This rule is - summarized below. + is higher than or equal to the effective level of its + logger. Otherwise, the request is said to be disabled. As + described previously, a logger without an assigned level will + inherit one from its nearest ancestor. This rule is summarized + below. + <div class="definition"> <div class="deftitle">Basic Selection Rule</div> - A log request of level p in a logger with an - effective level q, is enabled if p >= q. + A log request of level p issued with a logger having + an effective level q, is enabled if p >= q. </div> - - This rule is at the heart of logback. It assumes - that levels are ordered as follows: - <code>DEBUG < INFO < WARN < ERROR< OFF</code>. + This rule is at the heart of logback. It assumes that levels + are ordered as follows: <code>DEBUG < INFO < WARN < + ERROR</code>. In a more graphic way, here is how the selection rule works. In @@ -427,7 +402,7 @@ Here is an example of the basic selection rule. - <div class="source"><pre>// get a logger instance named "com.foo", with an INFO level. + <div class="source"><pre>// get a logger instance named "com.foo" Logger logger = LoggerFactory.getLogger("com.foo"); //set its Level to INFO logger.setLevel(Level. INFO); @@ -465,34 +440,28 @@ exactly the same logger object. - - 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. - - - 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. - - - Logback makes it easy to name loggers by software - component. 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. + 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. + + 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. + + Logback makes it easy to name loggers by software + component. 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. Nevertheless, naming loggers after the class where they are @@ -502,62 +471,54 @@ <a name="AppendersAndLayouts"></a> <h3>Appenders and Layouts</h3> - - 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. + 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.  More than one appender can be attached to a logger. - 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 L, - then enabled logging requests for L and L's - children will print on a file and 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. + 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 L, then enabled logging requests + for L and L's children will print on a file + and 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. - - The rules governing appender additivity are summarized - below. + The rules governing appender additivity are summarized below. <div class="definition"> <div class="deftitle">Appender Additivity</div> - - The output of a log statement of logger L - will go to all the appenders in L - and its ancestors. This is the meaning of the term - "appender additivity". + The output of a log statement of logger L will go to + all the appenders in L and its ancestors. This is the + meaning of the term "appender additivity". - - However, if an ancestor of logger L, say - P, has the additivity flag set to false, then - L's output will be directed to all the appenders in - L and it's ancestors upto and including - P but not the appenders in any of the ancestors of - P. + However, if an ancestor of logger L, say P, + has the additivity flag set to false, then L's output + will be directed to all the appenders in L and it's + ancestors upto and including P but not the appenders in + any of the ancestors of P. - - Loggers have their additivity flag set to true by - default. + Loggers have their additivity flag set to true by default. </div> @@ -581,7 +542,7 @@ hiearchy, the additivity flag does not apply to it. </td> </tr> - <tr> + <tr class="alt"> <td>x</td> <td>A-x1, A-x2</td> <td>true</td> @@ -595,7 +556,7 @@ <td>A1, A-x1, A-x2</td> <td>Appenders of "x" and of root.</td> </tr> - <tr> + <tr class="alt"> <td>x.y.z</td> <td>A-xyz1</td> <td>true</td> @@ -613,7 +574,7 @@ <code>false</code>. Only appender A-sec will be used. </td> </tr> - <tr> + <tr class="alt"> <td>security.access</td> <td>none</td> <td>true</td> @@ -627,65 +588,55 @@ </table> - - More often than not, users wish to customize not only the - output destination but also the output format. This is - accomplished by associating a layout - 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. + More often than not, users wish to customize not only the + output destination but also the output format. This is + accomplished by associating a layout 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. - - For example, the PatternLayout with the conversion pattern - "%-4relative [%thread] %-5level %logger{32} - %msg%n" will output something akin to: + For example, the PatternLayout with the conversion pattern + "%-4relative [%thread] %-5level %logger{32} - %msg%n" will output + something akin to: <div class="source"><pre>176 [main] DEBUG chapter2.HelloWorld2 - Hello world.</pre></div> - - 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. + 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. <a name="ParametrizedLogging"></a> <h3>Parameterized logging</h3> - - 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. + 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. - - For some Logger <code>logger</code>, writing, - + For some Logger <code>logger</code>, writing, <div class="source"><pre>logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));</pre></div> - - 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. + 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. - - One possible way to avoid the cost of parameter construction - is by surrounding the log statement with a test. Here is an - example. + One possible way to avoid the cost of parameter construction is + by surrounding the log statement with a test. Here is an example. <div class="source"><pre>if(logger.isDebugEnabled()) { @@ -693,55 +644,46 @@ }</pre></div> - - 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. + 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. - - <h4>Better alternative</h4> - - There exists a convenient alternative based on message - formats. Assuming <code>entry</code> is an object, you can write: + There exists a convenient alternative based on message + formats. Assuming <code>entry</code> is an object, you can write: <div class="source"><pre>Object entry = new SomeObject(); logger.debug("The entry is {}.", entry);</pre></div> - - 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. + 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. - - The following two lines will yield the exact same output. - However, in case of a disabled - logging statement, the second variant will outperform the first variant by a - factor of at least 30. + The following two lines will yield the exact same output. + However, in case of a disabled logging statement, the + second variant will outperform the first variant by a factor of at + least 30. <div class="source"><pre>logger.debug("The new entry is "+entry+"."); logger.debug("The new entry is {}.", entry);</pre></div> - - A two argument variant is also availalble. For example, you - can write: + A two argument variant is also availalble. For example, you can + write: <div class="source"><pre>logger.debug("The new entry is {}. It replaces {}.", entry, oldEntry);</pre></div> @@ -781,7 +723,8 @@ to step 3. - <h4>2. Apply the Logger level filter</h4> + <h4>2. Apply the <a href="#basic_selection">basic selection + rule</a></h4> At this step, logback compares the effective level of the logger with the level of the request. If the logging request is disabled Modified: logback/trunk/logback-site/src/site/pages/templates/right.js ============================================================================== --- logback/trunk/logback-site/src/site/pages/templates/right.js (original) +++ logback/trunk/logback-site/src/site/pages/templates/right.js Sat Aug 9 23:42:09 2008 @@ -1,13 +1,10 @@ - //document.write('<a href="'+prefix+'10reasons.ppt">10 reasons for migrating</a>') document.write('New and noteworthy') -document.write('<a href="http://wizardforge.org/pc?action=showVersion&id=72">Configuration Wizard</a>') - -http://wizardforge.org/pc?action=showVersion&id=72 +document.write('<a href="http://stubbisms.wordpress.com/2008/07/15/some-serious-logging-niceness-log…">Logging niceness</a>') -document.write('<a href="http://www.javadonkey.com/blog/log4j-isdebugenabled-logback/">isDebugEnabled()</a>') +document.write('<a href="http://wizardforge.org/pc?action=showVersion&id=72">Configuration Wizard</a>') document.write('<a href="http://xhab.blogspot.com/2007/03/new-logging-experience.html">A new logging experience!</a>')

1 0

svn commit: r1751 - logback/trunk/logback-site/src/site/pages
by noreply.ceki＠qos.ch 09 Aug '08

09 Aug '08

Author: ceki Date: Sat Aug 9 23:41:35 2008 New Revision: 1751 Modified: logback/trunk/logback-site/src/site/pages/bridge.html Log: - link update Modified: logback/trunk/logback-site/src/site/pages/bridge.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/bridge.html (original) +++ logback/trunk/logback-site/src/site/pages/bridge.html Sat Aug 9 23:41:35 2008 @@ -25,7 +25,7 @@ This module has migrated into the SLF4J project, its original home. It has also been renamed as <a - href="http://www.slf4j.org/log4j-over-slf4j.html">log4j-over-slf4j</a>. + href="http://www.slf4j.org/legacy.html#log4j-over-slf4j">log4j-over-slf4j</a>.

1 0

svn commit: r1750 - logback/trunk/logback-site/src/site/pages/manual
by noreply.ceki＠qos.ch 09 Aug '08

09 Aug '08

Author: ceki Date: Sat Aug 9 22:45:21 2008 New Revision: 1750 Modified: logback/trunk/logback-site/src/site/pages/manual/introduction.html Log: minor editing of the introduction chapter Modified: logback/trunk/logback-site/src/site/pages/manual/introduction.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/introduction.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/introduction.html Sat Aug 9 22:45:21 2008 @@ -168,48 +168,47 @@ |-INFO in ch.qos.logback.classic.BasicConfigurator@1c1ea29 - Setting up default configuration.</pre></div> - - Logback explains that it configured itself using its default - policy, which is a basic <code>ConsoleAppender</code>. - An <code>Appender</code> is a class that can be - seen as an output destination. Appenders exist for many different - destinations including the console, files, Syslog, TCP Socket, JMS and - many more. Users can also easily create their own Appenders as - appropriate for their specific situation. - - - - The previous examples are rather simple. However, actual logging - in a larger application would not be any different. The general - pattern logging statements will not change. Only the configuration - process will be different since you will certainly need a more - specific configuration than what logback provides by default. - As you will see later on in this document, - configuring logback can be done in different flexible and - powerfull ways. Note that, normally, you won't need to invoke - <code>LoggerStatusPrinter</code> - after your log statements. - - - - Here is a list of the three required steps in order to enable - logging in your application. + Logback explains that it configured itself using its default + policy, which is a basic <code>ConsoleAppender</code>. An + <code>Appender</code> is a class that can be seen as an output + destination. Appenders exist for many different destinations + including the console, files, Syslog, TCP Socket, JMS and many + more. Users can also easily create their own Appenders as + appropriate for their specific situation. - <ol> + The previous examples are rather simple. Actual logging in a + larger application would not be that different. The general pattern + for logging statements would not change. nly the configuration + process would be different since However, you would probably want to + customize or configure logback for according to your needs. Logback + configuration will be covered in subsequent chapters. + + + Note that in the above example we have instructed logback to + print its internal state by invoking + <code>StatusPrinter.print()</code> method. Logback's internal status + information can be very useful in diagnosing logback-related + problems. + + + Here is a list of the three required steps in order to enable + logging in your application. + - Configure the logback environment. You can do so in several - more or less sophisticated ways. More on this later. + <ol> + <li>Configure the logback environment. You can do so in several + more or less sophisticated ways. More on this later.</li> - In every class where you wish to perform logging, retrieve a + <li>In every class where you wish to perform logging, retrieve a <code>Logger</code> instance by invoking the <code>org.slf4j.LoggerFactory</code> class' <code>getLogger()</code> method, passing the current class name - or the class itself as parameter. + or the class itself as parameter.</li> - Use this logger instance by invoking its printing methods, + <li>Use this logger instance by invoking its printing methods, namely the debug(), info(), warn() and error(). This will - produce logging output on the configured appenders. + produce logging output on the configured appenders.</li> </ol> <a name="BuildingLogback"></a> @@ -233,13 +232,12 @@ Once you have installed Maven2, building the logback project, including all its modules, should be as easy as issuing a <code>mvn - package</code> command in a terminal or command window from within - the directory where you unarchived the logback distribution - file. Maven will automatically download the required external - libraries and use them. However, certain artefacts cannot be - downloaded from the Maven2 repository. At present, time only the JMS - API from from SUN Inc. needs to be downloaded and installed - separately into your local repository. + package</code> command from within the directory where you + unarchived the logback distribution. Maven will automatically + download the required external libraries. However, certain artefacts + cannot be downloaded from the Maven2 repository. At present, time + only the JMS API from from SUN Inc. needs to be downloaded and + installed separately into your local repository. You can manually download the <a

1 0