Author: ceki Date: Sat Aug 23 22:57:50 2008 New Revision: 1772 Added: logback/trunk/logback-site/src/site/resources/manual/images/chapter3/ logback/trunk/logback-site/src/site/resources/manual/images/chapter3/appenderSyntax.png (contents, props changed) logback/trunk/logback-site/src/site/resources/manual/images/chapter3/basicSyntax.png (contents, props changed) logback/trunk/logback-site/src/site/resources/manual/images/chapter3/sample.xml Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/GenericConfigurator.java logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/JoranConfiguratorBase.java logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/AppenderAction.java logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/ContextPropertyAction.java logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/MatcherAction.java logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/EventPlayer.java logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/InterpretationContext.java logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/Interpreter.java logback/trunk/logback-core/src/main/java/ch/qos/logback/core/util/OptionHelper.java logback/trunk/logback-core/src/test/java/ch/qos/logback/core/joran/replay/FruitConfigurator.java logback/trunk/logback-examples/src/main/java/chapter3/additivityFlag.xml logback/trunk/logback-examples/src/main/java/chapter3/multiple.xml logback/trunk/logback-examples/src/main/java/chapter3/restricted.xml logback/trunk/logback-site/src/site/pages/manual/joran.html Log: - ExecutionContext class has been renamed as InterpretationContext a few months ago. Syncing the docs. - ongoing work on the documentation Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/GenericConfigurator.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/GenericConfigurator.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/GenericConfigurator.java Sat Aug 23 22:57:50 2008 @@ -82,7 +82,7 @@ RuleStore rs = new SimpleRuleStore(context); addInstanceRules(rs); this.interpreter = new Interpreter(context, rs); - InterpretationContext ec = interpreter.getExecutionContext(); + InterpretationContext ec = interpreter.getInterpretationContext(); ec.setContext(context); addImplicitRules(interpreter); } Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/JoranConfiguratorBase.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/JoranConfiguratorBase.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/JoranConfiguratorBase.java Sat Aug 23 22:57:50 2008 @@ -84,12 +84,12 @@ @Override protected void buildInterpreter() { super.buildInterpreter(); - Map<String, Object> omap = interpreter.getExecutionContext().getObjectMap(); + Map<String, Object> omap = interpreter.getInterpretationContext().getObjectMap(); omap.put(ActionConst.APPENDER_BAG, new HashMap()); omap.put(ActionConst.FILTER_CHAIN_BAG, new HashMap()); } public InterpretationContext getExecutionContext() { - return interpreter.getExecutionContext(); + return interpreter.getInterpretationContext(); } } Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/AppenderAction.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/AppenderAction.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/AppenderAction.java Sat Aug 23 22:57:50 2008 @@ -9,7 +9,6 @@ */ package ch.qos.logback.core.joran.action; - import java.util.HashMap; import org.xml.sax.Attributes; @@ -20,47 +19,44 @@ import ch.qos.logback.core.spi.LifeCycle; import ch.qos.logback.core.util.OptionHelper; - - public class AppenderAction<E> extends Action { Appender appender; private boolean inError = false; /** * Instantiates an appender of the given class and sets its name. - * - * The appender thus generated is placed in the ExecutionContext appender bag. + * + * The appender thus generated is placed in the {@link InterpretationContext}'s + * appender bag. */ @SuppressWarnings("unchecked") - public void begin( - InterpretationContext ec, String localName, Attributes attributes) throws ActionException { + public void begin(InterpretationContext ec, String localName, + Attributes attributes) throws ActionException { // We are just beginning, reset variables appender = null; inError = false; - + String className = attributes.getValue(CLASS_ATTRIBUTE); - if(OptionHelper.isEmpty(className)) { - addError( - "Missing class name for appender. Near [" - + localName + "] line " + getLineNumber(ec)); + if (OptionHelper.isEmpty(className)) { + addError("Missing class name for appender. Near [" + localName + + "] line " + getLineNumber(ec)); inError = true; return; } - try { - addInfo("About to instantiate appender of type ["+className+"]"); + addInfo("About to instantiate appender of type [" + className + "]"); - appender = (Appender) OptionHelper.instantiateByClassName( - className, ch.qos.logback.core.Appender.class, context); + appender = (Appender) OptionHelper.instantiateByClassName(className, + ch.qos.logback.core.Appender.class, context); appender.setContext(context); String appenderName = attributes.getValue(NAME_ATTRIBUTE); if (OptionHelper.isEmpty(appenderName)) { - addWarn( - "No appender name given for appender of type " + className + "]."); + addWarn("No appender name given for appender of type " + className + + "]."); } else { appender.setName(appenderName); addInfo("Naming appender as [" + appenderName + "]"); @@ -68,8 +64,8 @@ // The execution context contains a bag which contains the appenders // created thus far. - HashMap<String, Appender> appenderBag = - (HashMap) ec.getObjectMap().get(ActionConst.APPENDER_BAG); + HashMap<String, Appender> appenderBag = (HashMap) ec.getObjectMap().get( + ActionConst.APPENDER_BAG); // add the appender just created to the appender bag. appenderBag.put(appenderName, appender); @@ -77,15 +73,15 @@ ec.pushObject(appender); } catch (Exception oops) { inError = true; - addError( - "Could not create an Appender of type ["+className+"].", oops); + addError("Could not create an Appender of type [" + className + "].", + oops); throw new ActionException(oops); } } /** - * Once the children elements are also parsed, now is the time to activate - * the appender options. + * Once the children elements are also parsed, now is the time to activate the + * appender options. */ public void end(InterpretationContext ec, String name) { if (inError) { @@ -99,13 +95,11 @@ Object o = ec.peekObject(); if (o != appender) { - addWarn( - "The object at the of the stack is not the appender named [" - + appender.getName() + "] pushed earlier."); + addWarn("The object at the of the stack is not the appender named [" + + appender.getName() + "] pushed earlier."); } else { - addInfo( - "Popping appender named [" + appender.getName() - + "] from the object stack"); + addInfo("Popping appender named [" + appender.getName() + + "] from the object stack"); ec.popObject(); } } Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/ContextPropertyAction.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/ContextPropertyAction.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/ContextPropertyAction.java Sat Aug 23 22:57:50 2008 @@ -12,7 +12,7 @@ public class ContextPropertyAction extends PropertyAction { /** - * Add all the properties found in the argument named 'props' to an ExecutionContext. + * Add all the properties found in the argument named 'props' to an InterpretationContext. */ public void setProperties(InterpretationContext ec, Properties props) { // TODO : test this method Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/MatcherAction.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/MatcherAction.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/MatcherAction.java Sat Aug 23 22:57:50 2008 @@ -1,7 +1,7 @@ /** - * LOGBack: the generic, reliable, fast and flexible logging framework. + * Logback: the generic, reliable, fast and flexible logging framework. * - * Copyright (C) 1999-2006, QOS.ch + * Copyright (C) 2000-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 @@ -23,11 +23,7 @@ final static String REGEX = "regex"; private boolean inError = false; - /** - * Instantiates an appender of the given class and sets its name. - * - * The appender thus generated is placed in the ExecutionContext appender bag. - */ + public void begin(InterpretationContext ec, String localName, Attributes attributes) throws ActionException { Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/EventPlayer.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/EventPlayer.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/EventPlayer.java Sat Aug 23 22:57:50 2008 @@ -35,16 +35,16 @@ if(se instanceof StartEvent) { interpreter.startElement((StartEvent) se); // invoke fireInPlay after startElement processing - interpreter.getExecutionContext().fireInPlay(se); + interpreter.getInterpretationContext().fireInPlay(se); } if(se instanceof BodyEvent) { // invoke fireInPlay before characters processing - interpreter.getExecutionContext().fireInPlay(se); + interpreter.getInterpretationContext().fireInPlay(se); interpreter.characters((BodyEvent) se); } if(se instanceof EndEvent) { // invoke fireInPlay before endElement processing - interpreter.getExecutionContext().fireInPlay(se); + interpreter.getInterpretationContext().fireInPlay(se); interpreter.endElement((EndEvent) se); } Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/InterpretationContext.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/InterpretationContext.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/InterpretationContext.java Sat Aug 23 22:57:50 2008 @@ -29,7 +29,7 @@ /** * - * The ExecutionContext contains the contextual state of a Joran parsing + * An InterpretationContext contains the contextual state of a Joran parsing * session. {@link Action} objects depend on this context to exchange * and store information. * @@ -135,8 +135,6 @@ } } - - public String getSubstitutionProperty(String key) { return context.getProperty(key); } Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/Interpreter.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/Interpreter.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/Interpreter.java Sat Aug 23 22:57:50 2008 @@ -98,7 +98,15 @@ player = new EventPlayer(this); } + + /** + * @deprecated replaced by {@link #getInterpretationContext()} + */ public InterpretationContext getExecutionContext() { + return getInterpretationContext(); + } + + public InterpretationContext getInterpretationContext() { return ec; } Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/util/OptionHelper.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/util/OptionHelper.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/util/OptionHelper.java Sat Aug 23 22:57:50 2008 @@ -172,7 +172,7 @@ } // if replacement is still null, use the defaultReplacement which - // still be null + // can be null as well if (replacement == null) { replacement = defaultReplacement; } Modified: logback/trunk/logback-core/src/test/java/ch/qos/logback/core/joran/replay/FruitConfigurator.java ============================================================================== --- logback/trunk/logback-core/src/test/java/ch/qos/logback/core/joran/replay/FruitConfigurator.java (original) +++ logback/trunk/logback-core/src/test/java/ch/qos/logback/core/joran/replay/FruitConfigurator.java Sat Aug 23 22:57:50 2008 @@ -33,7 +33,7 @@ final public void doConfigure(final List<SaxEvent> eventList) throws JoranException { buildInterpreter(); - interpreter.getExecutionContext().pushObject(ff); + interpreter.getInterpretationContext().pushObject(ff); EventPlayer player = new EventPlayer(interpreter); player.play(eventList); } Modified: logback/trunk/logback-examples/src/main/java/chapter3/additivityFlag.xml ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter3/additivityFlag.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter3/additivityFlag.xml Sat Aug 23 22:57:50 2008 @@ -1,14 +1,7 @@ <configuration> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> + <appender name="FILE"class="ch.qos.logback.core.FileAppender"> <file>foo.log</file> - <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> - foo-%d{yyyy-MM-dd-HH-mm-ss}.log - </FileNamePattern> - </rollingPolicy> <layout class="ch.qos.logback.classic.PatternLayout"> <Pattern> %date %level [%thread] %logger{10} [%file : %line] %msg%n @@ -16,8 +9,7 @@ </layout> </appender> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <layout class="ch.qos.logback.classic.PatternLayout"> <Pattern>%msg%n</Pattern> </layout> Modified: logback/trunk/logback-examples/src/main/java/chapter3/multiple.xml ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter3/multiple.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter3/multiple.xml Sat Aug 23 22:57:50 2008 @@ -1,13 +1,8 @@ <configuration> - <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> + <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>myApp.log</file> - - <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern>myApp-%d{yyyy-MM-dd-HH-mm-ss}.log</FileNamePattern> - </rollingPolicy> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%date %level [%thread] %logger{10} [%file : %line] %msg%n</Pattern> + <Pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</Pattern> </layout> </appender> Modified: logback/trunk/logback-examples/src/main/java/chapter3/restricted.xml ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter3/restricted.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter3/restricted.xml Sat Aug 23 22:57:50 2008 @@ -1,23 +1,13 @@ <configuration> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> + <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>myApp.log</file> - <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> - myApp-%d{yyyy-MM-dd-HH-mm-ss}.log - </FileNamePattern> - </rollingPolicy> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> - %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> + <Pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</Pattern> </layout> </appender> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <layout class="ch.qos.logback.classic.PatternLayout"> <Pattern>%msg%n</Pattern> </layout> 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 Sat Aug 23 22:57:50 2008 @@ -284,7 +284,7 @@ data. It does <em>not</em> affect logback's configuration otherwise, in particuler with respect to logger levels. (Put differently, no, the root logger will <em>not</em> be set to - DEBUG.) + <code>DEBUG</code>.) </p> @@ -353,8 +353,8 @@ 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 class MyApp3 { + final static Logger logger = LoggerFactory.getLogger(MyApp3.class); public static void main(String[] args) { // assume logback is in use @@ -386,10 +386,7 @@ then finally asks the configurator to configure the context using configuration file passed as parameter to the application. Internal status data is printed in case errors occur. - </p> - - - + </p> <h2> <a name="syntax" href="#syntax">Configuration file Syntax</a> @@ -420,15 +417,9 @@ <p align="left"> <img src="images/chapter3/basicSyntax.png" - alt="basic Syntax" title="Basic configuration file structure"/> + alt="basic Syntax" title="Basic configuration file structure"/> </p> - <!-- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX --> - <!-- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX --> - <!-- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX --> - <!-- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX --> - - <h4>Configuring Loggers, or the <code><logger></code> element</h4> <p>A logger is configured using the <code>logger</code> element. A @@ -488,7 +479,7 @@ declaring it and setting its level, as the next example illustrates. Suppose we are no longer interested in seeing any DEBUG messages from any component belonging to the "chapter3" package. The - following configuration file shows how. + following configuration file shows how to achieve that. </p> <em>Example 3.<span class="autoEx"/>: Setting the level of a logger (logback-examples/src/main/java/chapter3/sample2.xml)</em> @@ -510,18 +501,18 @@ </configuration></pre></div> -<p>This new configuration will yield the following output, when used -with the same <code>chapter3.MyApp2</code> class. -</p> + <p>This new configuration will yield the following output, when + invoked with the <em>MyApp3</em> application. + </p> -<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> +<div class="source"><pre>17:34:07.578 [main] INFO chapter3.MyApp3 - Entering application. +17:34:07.578 [main] INFO chapter3.MyApp3 - Exiting application.</pre></div> -<p>Obviously, you can configure the levels of as many loggers as you -wish. In the next configuration file we set the level of the -<em>chapter3</em> logger to <code>INFO</code> but at the same time set -the level of the <em>chapter3.Foo</em> logger to <code>DEBUG</code>. -</p> + <p>You can configure the levels of as many loggers as you wish. In + the next configuration file, we set the level of the + <em>chapter3</em> logger to INFO but at the same time set the level + of the <em>chapter3.Foo</em> logger to <code>DEBUG</code>. + </p> <em>Example 3.<span class="autoEx"/>: Setting the level of multiple loggers (logback-examples/src/main/java/chapter3/sample3.xml)</em> <div class="source"><pre><configuration> @@ -544,57 +535,62 @@ </configuration></pre></div> - <p>Running <code>MyApp2</code> with this configuration file will + <p>Running <code>MyApp3</code> with this configuration file will result in the following output on the console: </p> -<div class="source"><pre>17:39:27.593 [main] INFO chapter3.MyApp2 - Entering application. +<div class="source"><pre>17:39:27.593 [main] INFO chapter3.MyApp3 - Entering application. 17:39:27.593 [main] DEBUG chapter3.Foo - Did it again! -17:39:27.593 [main] INFO chapter3.MyApp2 - Exiting application.</pre></div> +17:39:27.593 [main] INFO chapter3.MyApp3 - Exiting application.</pre></div> - <p>After <code>JoranConfigurator</code> configures logback using - the <em>sample3.xml</em> file, the logger settings, more - specifically their levels, are summarized in the following table. + <p>The table below list the loggers and their levels, after + <code>JoranConfigurator</code> has configured logback with the + <em>sample3.xml</em> configuration file. </p> -<table class="bodyTable"> - <tr> - <th>Logger name</th> - <th>Assigned Level</th> - <th>Effective Level</th> - </tr> - <tr> - <td>root</td> - <td><code>DEBUG</code></td> - <td><code>DEBUG</code></td> - </tr> - <tr class="alt"> - <td>chapter3</td> - <td><code>INFO</code></td> - <td><code>INFO</code></td> - </tr> - <tr> - <td>chapter3.MyApp2</td> - <td><code>null</code></td> - <td><code>INFO</code></td> - </tr> - <tr class="alt"> - <td>chapter3.Foo</td> - <td><code>DEBUG</code></td> - <td><code>DEBUG</code></td> - </tr> -</table> + <table class="bodyTable"> + <tr> + <th>Logger name</th> + <th>Assigned Level</th> + <th>Effective Level</th> + </tr> + <tr> + <td>root</td> + <td><code>DEBUG</code></td> + <td><code>DEBUG</code></td> + </tr> + <tr class="alt"> + <td>chapter3</td> + <td><code>INFO</code></td> + <td><code>INFO</code></td> + </tr> + <tr> + <td>chapter3.MyApp3</td> + <td><code>null</code></td> + <td><code>INFO</code></td> + </tr> + <tr class="alt"> + <td>chapter3.Foo</td> + <td><code>DEBUG</code></td> + <td><code>DEBUG</code></td> + </tr> + </table> <p>It follows that the two logging statements of level - <code>INFO</code> in the <code>MyApp2</code> class as well as the + <code>INFO</code> in the <code>MyApp3</code> class as well as the DEBUG messages in <code>Foo.doIt()</code> are all enabled. Note that the level of the root logger is always set to a non-null value, - which is DEBUG by default. One rather important point to remember - is that the <a + which is DEBUG by default. + </p> + + <p>Let us note that the <a href="architecture.html#basic_selection">basic-selection rule</a> depends on the effective level of the logger being invoked, not the - level of the logger where appenders are attached. The configuration - file <em>sample4.xml</em> is a case in point: + level of the logger where appenders are attached. Loback will first + determine wheteher a logging statement is enabled or not, and if + enabled, it will invoke the appenders found in the logger hierarchy, + regardless of their level. The configuration file + <em>sample4.xml</em> is a case in point: </p> <em>Example 3.<span class="autoEx"/>: Logger level sample @@ -612,14 +608,15 @@ <b><logger name="chapter3" level="INFO" /></b> + <!-- turn OFF all logging (children can override) --> <root <b>level="OFF"</b>> <appender-ref ref="STDOUT" /> </root> </configuration></pre></div> - <p>The following table lists the loggers and their level setting - after applying the <em>sample4.xml</em> configuration file. + <p>The following table lists the loggers and their levels after + applying the <em>sample4.xml</em> configuration file. </p> <table class="bodyTable"> @@ -639,7 +636,7 @@ <td><code>INFO</code></td> </tr> <tr> - <td>chapter3.MyApp2</td> + <td>chapter3.MyApp3</td> <td><code>null</code></td> <td><code>INFO</code></td> </tr> @@ -652,77 +649,73 @@ <p>The ConsoleAppender named <em>STDOUT</em>, the only configured appender in <em>sample4.xml</em>, is attached to the root logger - whose level is set to <code>OFF</code>. However, running MyApp2 with - configuration script <em>sample4.xml</em> will output: + whose level is set to <code>OFF</code>. However, running + <em>MyApp3</em> with configuration script <em>sample4.xml</em> will + yield: </p> - <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> + <div class="source"><pre>17:52:23.609 [main] INFO chapter3.MyApp3 - Entering application. +17:52:23.609 [main] INFO chapter3.MyApp3 - Exiting application.</pre></div> <p>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 <em>chapter3.MyApp2</em> - and <em>chapter3.Foo</em>, inherit their level from the - <em>chapter3</em> logger which has its level set to - <code>INFO</code>. As noted previously, the <em>chapter3</em> + the loggers in <code>chapter3.MyApp3</code> and + <code>chapter3.Foo</code> classes are all enabled for the + <code>INFO</code> level. As a side note, the <em>chapter3</em> logger exists by virtue of its declaration in the configuration file - even if the Java source code does not directly refer to it. </p> <h4>Configuring Appenders</h4> - <p>Appenders are configured using <em>appender</em> elements. These - elements admit two attributes <em>name</em> and <em>class</em> both - of which are mandatory. The <em>name</em> attribute specifies the - name of the appender whereas the <em>class</em> attribute specifies - the fully qualified name of the class of which the named appender - will be an instance. The <em>appender</em> may contain zero or one - <em>layout</em> elements and zero or more <em>filter</em> - elements. Appart from these two basic elements, <em>appender</em> - elements may contain any element that corresponds to a setter method - of the appender class, to configure the appender's options. -</p> + <p>Appenders are configured using <code><appender></code> + elements, taking two attributes <span class="attr">name</span> and + <span class="attr">class</span>, both of which are mandatory. The + <span class="attr">name</span> attribute specifies the name of the + appender whereas the <span class="attr">class</span> attribute + specifies the fully qualified name of the class of which the named + appender will be an instance. The <code><appender></code> + element may contain zero or one <code><layout></code> elements + and zero or more <code><filter></code> elements. Appart from + these two common elements, <code><appender></code> elements may + contain any number of element corresponding to javabean properties + of the appender class. Seamlessly supporting any property of a given + logback component is one of the major strengths of Joran. The + following diagram illustrates the common structure. Note that + support for properties is not visible. + </p> -<p> -The <em>layout</em> element takes a mandatory class attribute specifying -the fully qualified name of the class of which the associated layout -should be an instance. Like the <em>appender</em> element, it may contain -other elements, referring to setter methods, to configure its options. -</p> + <p align="left"> + <img src="images/chapter3/appenderSyntax.png" + alt="Appender Syntax" title="Appender element syntax"/> + </p> -<p> -Logging to multiple appenders is as easy as defining the various appenders -and referencing them in a logger, as the next configuration file illustrates: -</p> + <p>The <code><layout></code> element takes a mandatory class + attribute specifying the fully qualified name of the class of which + the associated layout should be an instance. Like the + <code><appender></code> element, it may contain other elements + corresponding to properties of the layout class. + </p> + + <p>Logging to multiple appenders is as easy as defining the various + appenders and referencing them in a logger, as the next + configuration file illustrates: + </p> <em>Example 3.<span class="autoEx"/>: Multiple loggers (logback-examples/src/main/java/chapter3/multiple.xml)</em> <div class="source"><pre><configuration> - <appender name="<b>FILE</b>" - class="ch.qos.logback.core.rolling.RollingFileAppender"> + <appender name="<b>FILE</b>" class="ch.qos.logback.core.FileAppender"> <file>myApp.log</file> - <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> - myApp-%d{yyyy-MM-dd-HH-mm-ss}.log - </FileNamePattern> - </rollingPolicy> - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> - %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> + <Pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</Pattern> </layout> </appender> <appender name="<b>STDOUT</b>" class="ch.qos.logback.core.ConsoleAppender"> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> - %msg%n - </Pattern> + <Pattern>%msg%n</Pattern> </layout> </appender> @@ -747,8 +740,8 @@ <p>The appenders are attached to the root logger by referencing them by name within an <em>appender-ref</em> 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. + shared by multiple appenders. As such, logback configuration files + do not provide any syntactical means for sharing layouts. </p> <p>By default, <b>appenders are cumulative</b>: a logger will log to @@ -762,12 +755,9 @@ (logback-examples/src/main/java/chapter3/duplicate.xml)</em> <div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> + <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> + <Pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</Pattern> </layout> </appender> @@ -781,21 +771,21 @@ </root> </configuration></pre></div> - <p>Running <code>MyApp2</code> with <em>duplicate.xml</em> will + <p>Running <code>MyApp3</code> with <em>duplicate.xml</em> will yield the following output: </p> -<div class="source"><pre>14:25:36.343 [main] INFO chapter3.MyApp2 - Entering application. -14:25:36.343 [main] INFO chapter3.MyApp2 - Entering application. +<div class="source"><pre>14:25:36.343 [main] INFO chapter3.MyApp3 - Entering application. +14:25:36.343 [main] INFO chapter3.MyApp3 - Entering application. 14:25:36.359 [main] DEBUG chapter3.Foo - Did it again! 14:25:36.359 [main] DEBUG chapter3.Foo - Did it again! -14:25:36.359 [main] INFO chapter3.MyApp2 - Exiting application. -14:25:36.359 [main] INFO chapter3.MyApp2 - Exiting application.</pre></div> +14:25:36.359 [main] INFO chapter3.MyApp3 - Exiting application. +14:25:36.359 [main] INFO chapter3.MyApp3 - Exiting application.</pre></div> <p>Notice the duplicated output. The appender named <em>STDOUT</em> is attached to two loggers, to root and to <em>chapter3</em>. Since the root logger is the ancestor of all loggers and <em>chapter3</em> - is the parent of <em>chapter3.MyApp2</em> and <em>chapter3.Foo</em>, + is the parent of <em>chapter3.MyApp3</em> and <em>chapter3.Foo</em>, logging request made with these two loggers will be output twice, once because <em>STDOUT</em> is attached to <em>chapter3</em> and once because it is attached to <em>root</em>. @@ -812,24 +802,14 @@ (logback-examples/src/main/java/chapter3/restricted.xml)</em> <div class="source"><pre><configuration> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> + <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>myApp.log</file> - <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> - myApp-%d{yyyy-MM-dd-HH-mm-ss}.log - </FileNamePattern> - </rollingPolicy> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> - %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> + <Pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</Pattern> </layout> </appender> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <layout class="ch.qos.logback.classic.PatternLayout"> <Pattern>%msg%n</Pattern> </layout> @@ -846,14 +826,15 @@ </configuration></pre></div> <p>In this example, the console appender will log all the messages - (for all loggers in the system) whereas only logs under the - <em>chapter3</em> tree go into the <em>myApp.log</em> file. + (for all loggers in the system) whereas only logging request + originating from loggers <em>chapter3</em> and below go into the + <em>myApp.log</em> file. </p> <h4>Overriding the default cumulative behaviour</h4> <p>In case the default cumulative behavior turns out to be - unsuitable for one's needs, one can override it by setting the + unsuitable for your needs, you 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. @@ -862,24 +843,14 @@ <em>Example 3.<span class="autoEx"/>: Additivity flag (logback-examples/src/main/java/chapter3/additivityFlag.xml)</em> <div class="source"><pre><configuration> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> + <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>foo.log</file> - <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> - foo-%d{yyyy-MM-dd-HH-mm-ss}.log - </FileNamePattern> - </rollingPolicy> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> - %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> + <Pattern>%date %level [%thread] %logger{10} [%file : %line] %msg%n</Pattern> </layout> </appender> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <layout class="ch.qos.logback.classic.PatternLayout"> <Pattern>%msg%n</Pattern> </layout> @@ -901,9 +872,9 @@ output will be sent to the appender named <em>FILE</em> but not to any appender attached higher in the hierarchy. Other loggers remain oblivious to the additivity setting of the <em>chapter3.Foo</em> - logger. Running the <code>MyApp2</code> application with the + logger. Running the <code>MyApp3</code> application with the <em>additivityFlag.xml</em> configuration file will output results - on the console from the <em>chapter3.MyApp2</em> logger. However, + on the console from the <em>chapter3.MyApp3</em> logger. However, output from the <em>chapter3.Foo</em> logger will appear in the <em>foo.log</em> file and only in that file. </p> @@ -925,9 +896,9 @@ <em>/home/xyz</em>. </p> - <p>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. + <p>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. </p> <em>Example 3.<span class="autoEx"/>: Simple Variable substitution Added: logback/trunk/logback-site/src/site/resources/manual/images/chapter3/appenderSyntax.png ============================================================================== Binary file. No diff available. Added: logback/trunk/logback-site/src/site/resources/manual/images/chapter3/basicSyntax.png ============================================================================== Binary file. No diff available. Added: logback/trunk/logback-site/src/site/resources/manual/images/chapter3/sample.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-site/src/site/resources/manual/images/chapter3/sample.xml Sat Aug 23 22:57:50 2008 @@ -0,0 +1,32 @@ +<?xml version="1.0" encoding="UTF-8"?> +<configuration> + <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> + <file>myApp.log</file> + <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> + <FileNamePattern> myApp-%d{yyyy-MM-dd-HH-mm-ss}.log</FileNamePattern> + </rollingPolicy> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%date %level [%thread] %logger{10} [%file : %line] %msg%n</Pattern> + </layout> + </appender> + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <filter class="ch.qos.logback.classic.filter.LevelFilter"> + <level>INFO</level> + <onMatch>ACCEPT</onMatch> + <onMismatch>DENY</onMismatch> + </filter> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%msg%n</Pattern> + </layout> + </appender> + <logger name="chapter3"> + <appender-ref ref="FILE"/> + </logger> + <logger name="chapter4"> + <appender-ref ref="FILE"/> + </logger> + <root> + <level value="debug"/> + <appender-ref ref="STDOUT"/> + </root> +</configuration>