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

[JIRA] Resolved: (LBCORE-48) compression should happen in a separate thread
by Ceki Gulcu (JIRA) 25 Aug '08

25 Aug '08

[ http://jira.qos.ch/browse/LBCORE-48?page=com.atlassian.jira.plugin.system.i… ] Ceki Gulcu resolved LBCORE-48. ------------------------------ Fix Version/s: 0.9.10 Resolution: Fixed Compression is done in a separate thread. Fixed in revision 1677. See http://svn.qos.ch/viewvc?view=rev&revision=1677 for full details. > compression should happen in a separate thread > ---------------------------------------------- > > Key: LBCORE-48 > URL: http://jira.qos.ch/browse/LBCORE-48 > Project: logback-core > Issue Type: Improvement > Components: Rolling > Affects Versions: unspecified > Environment: Operating System: All > Platform: Other > Reporter: Ceki Gulcu > Assignee: Logback dev list > Priority: Minor > Fix For: 0.9.10 > > > During rollover, compression can bring all logging to a halt. > This bug is related to LBCLASSIC-20. > http://bugzilla.qos.ch/show_bug.cgi?id=55 -- 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 0

[JIRA] Resolved: (LBCLASSIC-20) Implement AsyncAppender
by Ceki Gulcu (JIRA) 25 Aug '08

25 Aug '08

[ http://jira.qos.ch/browse/LBCLASSIC-20?page=com.atlassian.jira.plugin.syste… ] Ceki Gulcu resolved LBCLASSIC-20. --------------------------------- Fix Version/s: 0.9.10 Resolution: Duplicate I am closing this issue as the requirement is not actually AsyncAppender but a way to do compression asynchronously, which very different. I invite those really interested in AsyncAppender to create a separate issue. > Implement AsyncAppender > ----------------------- > > Key: LBCLASSIC-20 > URL: http://jira.qos.ch/browse/LBCLASSIC-20 > Project: logback-classic > Issue Type: Improvement > Components: Other > Affects Versions: unspecified > Environment: Operating System: Windows > Platform: PC > Reporter: Anders Wallgren > Assignee: Logback dev list > Priority: Minor > Fix For: 0.9.10 > > > Being able to write log files in the background is a requirement for production deployments of anything we would write on top of logback. > Bonus points for including a feature to periodically flush the output. -- 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 0

[JIRA] Commented: (LBCORE-48) compression should happen in a separate thread
by Jonathan Komorek (JIRA) 25 Aug '08

25 Aug '08

[ http://jira.qos.ch/browse/LBCORE-48?page=com.atlassian.jira.plugin.system.i… ] Jonathan Komorek commented on LBCORE-48: ---------------------------------------- Is there a work around for this issue? This is freezing our production environment for about 10 minutes every night while the log files is being compressed. > compression should happen in a separate thread > ---------------------------------------------- > > Key: LBCORE-48 > URL: http://jira.qos.ch/browse/LBCORE-48 > Project: logback-core > Issue Type: Improvement > Components: Rolling > Affects Versions: unspecified > Environment: Operating System: All > Platform: Other > Reporter: Ceki Gulcu > Assignee: Logback dev list > Priority: Minor > > During rollover, compression can bring all logging to a halt. > This bug is related to LBCLASSIC-20. > http://bugzilla.qos.ch/show_bug.cgi?id=55 -- 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 0

[JIRA] Created: (LBSITE-16) Clarify manual/joran wording
by Ceki Gulcu (JIRA) 25 Aug '08

25 Aug '08

Clarify manual/joran wording ---------------------------- Key: LBSITE-16 URL: http://jira.qos.ch/browse/LBSITE-16 Project: logback-site Issue Type: Bug Reporter: Ceki Gulcu Assignee: Logback dev list Reported by Anton Tagunov in bugzilla.slf4j.org instead of here. See http://bugzilla.slf4j.org/show_bug.cgi?id=87 -- 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

svn commit: r1777 - in logback/trunk: logback-examples/src/main/java/chapter4 logback-site/src/site/pages logback-site/src/site/pages/manual
by noreply.ceki＠qos.ch 25 Aug '08

25 Aug '08

Author: ceki Date: Mon Aug 25 21:54:06 2008 New Revision: 1777 Modified: logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes1.java logback/trunk/logback-site/src/site/pages/jmxConfig.html logback/trunk/logback-site/src/site/pages/manual/appenders.html logback/trunk/logback-site/src/site/pages/manual/contextSelector.html logback/trunk/logback-site/src/site/pages/manual/filters.html logback/trunk/logback-site/src/site/pages/manual/joran.html logback/trunk/logback-site/src/site/pages/manual/layouts.html logback/trunk/logback-site/src/site/pages/manual/mdc.html Log: Related to LBSITE-16 Documentation improvements many of which have been proposed by Anton Tagunov. Modified: logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes1.java ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes1.java (original) +++ logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes1.java Mon Aug 25 21:54:06 2008 @@ -1,7 +1,7 @@ /** - * Logback: the reliable, generic, 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 @@ -25,7 +25,7 @@ public static void main(String[] args) throws Exception { LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); - lc.shutdownAndReset();//this is to cancel default-config. + lc.shutdownAndReset(); // we want to override the default-config. WriterAppender<LoggingEvent> writerAppender = new WriterAppender<LoggingEvent>(); writerAppender.setContext(lc); writerAppender.setLayout(new EchoLayout<LoggingEvent>()); Modified: logback/trunk/logback-site/src/site/pages/jmxConfig.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/jmxConfig.html (original) +++ logback/trunk/logback-site/src/site/pages/jmxConfig.html Mon Aug 25 21:54:06 2008 @@ -23,45 +23,45 @@ <h2>JMX Configurator</h2> - - As of version 0.8, logback ships with a component that allows - configuration via JMX. Basically, it lets you reload the current - configuration, load a new one, list loggers and modify logger levels. + As of version 0.8, logback ships with a component that allows + configuration via JMX. Basically, it lets you reload the current + configuration, load a new one, list loggers and modify logger + levels. <h3>Configuring your server</h3> - - The first step is to make sure that your application server will - allow the JMX Configurator to publish itself. In this document, - we'll cover the necessary steps in Tomcat and Jetty. + + The first step is to make sure that your application server + will allow the JMX Configurator to publish itself. In this + document, we'll cover the necessary steps in Tomcat and Jetty. <h4>Configuring Tomcat</h4> - - Accessing JMX components with Tomcat requires to add the following lines - to the $TOMCAT_HOME/bin/catalina.sh configuration file: + + Accessing JMX components with Tomcat requires to add the + following lines to the $TOMCAT_HOME/bin/catalina.sh + configuration file: <div class="source"><pre>CATALINA_OPTS="-Dcom.sun.management.jmxremote" CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.ssl=false" CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"</pre></div> - - Once started with these options, Tomcat's JMX compoenents can be accessed - with JConsole by issuing the following command in a shell: + Once started with these options, Tomcat's JMX compoenents can + be accessed with JConsole by issuing the following command in a + shell: <div class="source"><pre>jconsole &</pre></div> - - You might prefer to access your components via a web-based solution using MX4J. - In that case, here are the required steps: + You might prefer to access your components via a web-based + solution using MX4J. In that case, here are the required steps: - - First, <a href="http://mx4j.sourceforge.net/">download MX4J</a>. - Place the mx4j-impl.jar file in - the $TOMCAT_HOME/bin/ directory, and the mx4j-tools.jar - in the $TOMCAT_HOME/common/lib/ directory. + First, <a href="http://mx4j.sourceforge.net/">download + MX4J</a>. Place the mx4j-impl.jar file in the + $TOMCAT_HOME/bin/ directory, and the + mx4j-tools.jar in the $TOMCAT_HOME/common/lib/ + directory. Then, add the following lines to the @@ -87,19 +87,17 @@ mx.httpPort="8082" protocol="AJP/1.3" /></pre></div> - - Once Tomcat is started, you should be ableo to reach the JMX components by - pointing a browser to the following URL: + Once Tomcat is started, you should be able to reach the JMX + components by pointing a browser to the following URL: <div class="source"><pre>http://host_name:8082/</pre></div> <h4>Configuring Jetty</h4> - - Configuring Jetty to publish JMX components requires a few modifications to the - $JETTY_HOME/etc/jetty.xml configuration file. Here are the elements that need to be - added: + Configuring Jetty to publish JMX components requires a few + modifications to the $JETTY_HOME/etc/jetty.xml + configuration file. Here are the elements that need to be added: <div class="source"><pre><Call id="MBeanServer" class="java.lang.management.ManagementFactory" name="getPlatformMBeanServer"/> @@ -116,18 +114,17 @@ </Call> </Get></pre></div> - - Once Jetty is started with this configuration, all available components can be reviewed - at this address: + Once Jetty is started with this configuration, all available + components can be reviewed at this address: <div class="source"><pre>http://host_name:8082/</pre></div> <h3>Using the JMX Configurator</h3> - - The next step is to declare the JMX Configurator in the logback configuration - file. This is done by adding a single element, as shown below: + The next step is to declare the JMX Configurator in the logback + configuration file. This is done by adding a single element, as + shown below: <div class="source"><pre><configuration> @@ -146,58 +143,49 @@ </root> </configuration></pre></div> - - Once the JMX Configurator is displayed on your screen, there are - several operations available. + Once the JMX Configurator is displayed on your screen, there + are several operations available. <ul> - Display the logback Statuses - - Reload the configuration using the same file that was previously - used. - - Reload the configuration using a file whose path is passed as - a parameter. - - Reload the configuration using a file whose URL is passed as a - parameter. - - - Get the level of a logger - - - Change the level setting of a specified logger. - - - Change a list of all declared loggers. - - - Change the level setting of a specified logger. - + <li>Display the logback Status </li> + + <li>Reload the configuration using the same file that was previously + used. </li> + + <li>Reload the configuration using a file whose path is passed + as a parameter.</li> + + <li>Reload the configuration using a file whose URL is passed as + a parameter.</li> + + <li>Get the level of a logger</li> + <li>Change the level setting of a specified logger.</li> + <li>Change a list of all declared loggers.</li> + <li>Change the level setting of a specified logger.</li> </ul> - - In the last case, you must specify the name of the logger you wish to - alter, and its new level. + In the last case, you must specify the name of the logger you + wish to alter, and its new level. - - The level of a logger is a value that can be null, if no specific level - has been configured for said logger. Its effective level, on the other - hand, is given with respect to the parent loggers' levels. This value cannot - be null, since all loggers are direct or indirect children of the root - logger, whose level is always set. When trying to get the level or effective - level of a logger, the name of the logger has to be passed as a parameter. - Note that trying to get the level or effective level for a nonexistent logger - will not return any result. + + The level of a logger is a value that can be null, if no + specific level has been configured for said logger. Its effective + level, on the other hand, is given with respect to the parent + loggers' levels. This value cannot be null, since all loggers are + direct or indirect children of the root logger, whose level is + always set. When trying to get the level or effective level of a + logger, the name of the logger has to be passed as a parameter. + Note that trying to get the level or effective level for a + nonexistent logger will not return any result. - - Displaying logback Statuses via JMX can help users check the internal state - of logback. It shows if anything has gone wrong, if rollovers occured - as expected, and many other useful informations. It is also very useful - when reloading a configuration, since the user can immediately see if - the configuration file was successfully processed. + Displaying logback status via JMX can help users check the + internal state of logback. It shows if anything has gone wrong, if + rollovers occured as expected, as well as other useful + information. It is also very useful when reloading a + configuration, since the user can immediately see if the + configuration file has been procsseds successfully. Modified: logback/trunk/logback-site/src/site/pages/manual/appenders.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/appenders.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/appenders.html Mon Aug 25 21:54:06 2008 @@ -298,9 +298,10 @@ import java.io.OutputStream; import java.io.OutputStreamWriter; -import org.slf4j.Logger; + import org.slf4j.LoggerFactory; +import ch.qos.logback.classic.Logger; import ch.qos.logback.classic.LoggerContext; import ch.qos.logback.core.WriterAppender; import ch.qos.logback.core.layout.EchoLayout; @@ -309,16 +310,19 @@ public static void main(String[] args) throws Exception { LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); + lc.shutdownAndReset(); // we want to override the default-config. WriterAppender<LoggingEvent> writerAppender = new WriterAppender<LoggingEvent>(); writerAppender.setContext(lc); - writerAppender.setLayout(new EchoLayout<LoggingEvent>()); + writerAppender.setLayout(new EchoLayout<<LoggingEvent>()); OutputStream os = new FileOutputStream("exitWoes1.log"); writerAppender.setWriter(new OutputStreamWriter(os)); writerAppender.setImmediateFlush(false); writerAppender.start(); + Logger root = lc.getLogger(LoggerContext.ROOT_NAME); + root.addAppender(writerAppender); - Logger logger = LoggerFactory.getLogger(ExitWoes1.class); + Logger logger = lc.getLogger(ExitWoes1.class); logger.debug("Hello world."); } @@ -681,11 +685,10 @@ The FileNamePattern option represents - the file name pattern for the archived (rolled over) log files. The - FileNamePattern option, which is also - required, must include an integer token, that is the string + the file name pattern for the archived (rolled over) log files. + This option is required and must include an integer token %i somewhere within the pattern. - + Here are the available options for <code>FixedWindowRollingPolicy</code> @@ -865,14 +868,13 @@ FileNamePattern option defines the - name of the rolled (archived) log files. Its value FileNamePattern should consist of the name of - the file, plus a suitably placed %d conversion specifier. - The %d conversion specifier may contain a date-and-time - pattern as specified by the <code>java.text.SimpleDateFormat</code> - class. If the date-and-time pattern is omitted, then the default - pattern yyyy-MM-dd is assumed. The following examples - should clarify the point. + name of the rolled (archived) log files. Its value should consist of + the name of the file, plus a suitably placed %d conversion + specifier. The %d conversion specifier may contain a + date-and-time pattern as specified by the + <code>java.text.SimpleDateFormat</code> class. If the date-and-time + pattern is omitted, then the default pattern yyyy-MM-dd is + assumed. The following examples should clarify the point. <table class="bodyTable"> Modified: logback/trunk/logback-site/src/site/pages/manual/contextSelector.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/contextSelector.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/contextSelector.html Mon Aug 25 21:54:06 2008 @@ -207,7 +207,7 @@ <div class="source"><pre><listener> <listener-class>ch.qos.logback.classic.selector.servlet.ContextDetachingSCL</listener-class> -</listener</pre></div> +</listener></pre></div> Using the <code>ContextJNDISelector</code> might slow down your Modified: logback/trunk/logback-site/src/site/pages/manual/filters.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/filters.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/filters.html Mon Aug 25 21:54:06 2008 @@ -54,48 +54,55 @@ <h2>Logback Classic</h2> <a name="Filter"></a> - <code>Filter</code> objects all implement the - <a href="../xref/ch/qos/logback/core/filter/Filter.html"><code>Filter</code></a> - abstract class. The <code>decide(Object event)</code> method is passed a - newly created <code>LoggingEvent</code> object. + + <code>Filter</code> objects all extend the <a + href="../xref/ch/qos/logback/core/filter/Filter.html"><code>Filter</code></a> + abstract class. The <code>decide(Object event)</code> method is + passed a newly created <code>LoggingEvent</code> object. <h3>Filter chains</h3> - - This abstract class assumes that filters be organized in a linear chain. - Its member field next points to the next filter in the chain, or - <code>null</code> if there are no further filters in the chain. - Figure 6.1 depicts a sample filter chain consisting of three filters. + + This abstract class assumes that filters are organized in a + linear chain. Its member field next points to the next filter in + the chain, or <code>null</code> if there are no further filters in + the chain. Figure 6.1 depicts a sample filter chain consisting of + three filters. <img src="images/chapter6/filterChain.gif" alt="A sample filter chain"/> - - Filters are based on ternary logic. The <code>decide(Object event)</code> - method of each filter is called in sequence. This method returns one of the - enumerations <code>FilterReply.DENY</code>, <code>FilterReply.NEUTRAL</code> or - <code>FilterReply.ACCEPT</code>. If the returned value is <code>FilterReply.DENY</code>, - then the log event is dropped immediately without consulting the - remaining filters. If the value returned is <code>FilterReply.NEUTRAL</code>, - then the next filter in the chain is consulted. If there are no further filters - to consult, then the logging event is processed normally. - If the returned value is <code>FilterReply.ACCEPT</code>, then the logging - event is processed immediately skipping the remaining filters. + Filters are based on ternary logic. The <code>decide(Object + event)</code> method of each filter is called in sequence. This + method returns one of the <a + href="../xref/ch/qos/logback/core/spi/FilterReply.html"><code>FilterReply</code></a> + enumeration values, i.e. one of <code>FilterReply.DENY</code>, + <code>FilterReply.NEUTRAL</code> or + <code>FilterReply.ACCEPT</code>. If the returned value is + <code>FilterReply.DENY</code>, then the log event is dropped + immediately without consulting the remaining filters. If the value + returned is <code>FilterReply.NEUTRAL</code>, then the next filter + in the chain is consulted. If there are no further filters to + consult, then the logging event is processed normally. If the + returned value is <code>FilterReply.ACCEPT</code>, then the + logging event is processed immediately skipping the remaining + filters. - - In logback-classic, <code>Filter</code> objects can only be added to <code>Appender</code> - instances. By adding filters to an appender you can filter events by various - criteria, such as the contents of the log message, the contents of the MDC, - the time of day or any other part of the logging event. + In logback-classic <code>Filter</code> objects can only be + added to <code>Appender</code> instances. By adding filters to an + appender you can filter events by various criteria, such as the + contents of the log message, the contents of the MDC, the time of + day or any other part of the logging event. <h3>Implementing your own Filter</h3> - - Creating your own filter is not difficult. All you have to do is extend the <code>Filter</code> - abstract class. The only method that you will have to implement is the <code>decide()</code> - method, allowing you to contentrate only on the behaviour of your filter. + Creating your own filter is not difficult. All you have to do + is extend the <code>Filter</code> abstract class. The only method + that you will have to implement is the <code>decide()</code> + method, allowing you to contentrate only on the behaviour of your + filter. @@ -168,14 +175,14 @@ <h3>Logback Filters</h3> - - As the moment, there are two filters that ship with logback. - <a href="../xref/ch/qos/logback/classic/LevelFilter.html"> - <code>LevelFilter</code></a> provides event filtering based on a <code>Level</code> value. - It the event's level is equal to the configured level, the filter accepts of denies - the event, depending on its configuration. It allows you to choose the - behaviour of logback for a precise given level. Here is a sample configuration that - uses <code>LevelFilter</code>. + At the moment, there are two filters that ship with logback. <a + href="../xref/ch/qos/logback/classic/LevelFilter.html"> + <code>LevelFilter</code></a> provides event filtering based on a + <code>Level</code> value. It the event's level is equal to the + configured level, the filter accepts of denies the event, + depending on its configuration. It allows you to choose the + behaviour of logback for a precise given level. Here is a sample + configuration that uses <code>LevelFilter</code>. Example 6.3: Sample LevelFilter configuration (logback-examples/src/main/java/chapter6/LevelFilterConfig.xml) @@ -227,131 +234,89 @@ </root> </configuration></pre></div> - <h3>Evaluator Filters</h3> - - - A special category of filters ships with logback. The - <a href="../xref/ch/qos/logback/core/filter/EvaluatorFilter.html"> - <code>EvaluatorFilter</code></a> objects use an - <a href="../xref/ch/qos/logback/core/boolex/EventEvaluator.html"> - <code>EventEvaluator</code></a> - to decide wether to accept or deny the request. This allows unprecedented - flexibility in the way that you can affect the logging event's filtering. - - - - Creating a customized filter that makes use of <code>EventEvaluator</code> objects - works the same way as seen previously, except that one must extend the - <code>EvaluatorFilter</code> class, instead of the <code>Filter</code> - or <code>AbstractMatcherFilter</code> classes. - - - <a name="EventEvaluator"></a> - <h3>Event Evaluators</h3> - - - Events evaluators allow the user to enter java expressions, using - components of a logging event, and to check each logging event - against the compiled expression. - - - - Let's see a sample configuration. - - -Example 6.5: Basic event evaluator usage (logback-examples/src/main/java/chapter6/basicEventEvaluator.xml) -<div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> - <evaluator name="myEval"> - <expression>message.contains("billing")</expression> - </evaluator> - <OnMismatch>NEUTRAL</OnMismatch> - <OnMatch>DENY</OnMatch> - </filter> - <layout class="ch.qos.logback.classic.PatternLayout"> - <pattern> - %-4relative [%thread] %-5level %logger - %msg%n - </pattern> - </layout> - </appender> + <h3>Evaluator Filters taking Java Expressions</h3> - <root> - <level value="INFO" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + + A special category of filters is implemented by the <a + href="../xref/ch/qos/logback/core/filter/EvaluatorFilter.html"> + <code>EvaluatorFilter</code></a> class. These filters use an <a + href="../xref/ch/qos/logback/core/boolex/EventEvaluator.html"> + <code>EventEvaluator</code></a> object to decide wether to accept + or deny a request. This allows unprecedented flexibility in the + way that you can affect filtering of logging events. + - - The bold part in the previous configuration adds an <code>EvaluatorFilter</code> - to a <code>ConsoleAppender</code>. An <code>EventEvaluator</code> is then given to - the filter. The expression element contains a recognizable java expression. - Notice that the message variable is defined implicitly. Logback provides - access to the internal components of a logging event and lets the user build her - expression at will. + As a user, you do not need to worry about the actual + plumbing. All you need to do is to give a name to the evaluator + and to specify an evaluation expression, that is a + boolean expression in regular Java syntax. These evaluation + expressions are compiled on-the-fly during the interpretation of + the configration file. It is the users reponsibility to ensure + that the expression is boolean, that it evaluates to true or + false. In evaluation expressions, logback implicitly exposes + various fields of a logging event as variables. The list of these + implicit variables is given below. The scope of evaluation + expressions is limited to the logging event. - - The implicit variables available to the <code>EventEvaluator</code> are described below: - - <table> - <tr> - <th>Name</th> - <th>Type</th> - <th>Description</th> + <table class="bodyTable"> + <tr> + <th>Name</th> + <th>Type</th> + <th>Description</th> </tr> - <tr> - <td>event - </td> + <tr> + <td>event</td> <td><code>LoggingEvent</code></td> - <td>The logging event associated with the logging request. - All of the following variables are also available from the event. For example, - <code>event.getMessage()</code> returns the same String value as the message - variable. - </td> + + <td>The raw logging event associated with the logging + request. All of the following variables are also available + from the event. For example, <code>event.getMessage()</code> + returns the same String value as the message variable + described next. + </td> </tr> - <tr> - <td>message - </td> - <td><code>String</code></td> - <td>The message created with the logging request. - </td> + + <tr class="alt"> + <td>message</td> + <td><code>String</code></td> + <td>The message of the logging request.</td> </tr> <tr> - <td>logger - </td> + <td>logger</td> <td><code>LoggerRemoteView</code></td> - <td>This object can be treated like a usual logger. In case the logging event - is serialized and sent to a remote machine, the usual logger object is - dropped and replaced by a <code>LoggerRemoteView</code> object, which - performs much better when serialized. - </td> + <td>This object is a proxy for the logger object where the + logging request was issued. It can be viewed as a regular + logger object. However, it has some nice performance + properties, especially with respect to serialization. + </td> </tr> - <tr> - <td>level - </td> + + <tr class="alt"> + <td>level</td> <td><code>int</code></td> - <td>The int value corresponding to the level. To help create easily - expressions involving levels, the default value DEBUG, - INFO, WARN and ERROR are also available. Thus, - using level > INFO is a correct expression. + <td>The int value corresponding to the level. To help create + easily expressions involving levels, the default value + DEBUG, INFO, WARN and + ERROR are also available. Thus, using level > + INFO is a correct expression. </td> </tr> <tr> <td>timeStamp </td> <td><code>long</code></td> - <td>The timestamp corresponding to the logging event's creation. + <td>The timestamp corresponding to the logging event's + creation. </td> </tr> - <tr> - <td>marker - </td> + <tr class="alt"> + <td>marker</td> <td><code>Marker</code></td> - <td>The <code>Marker</code> object associated with the logging request. + <td>The <code>Marker</code> object associated with the logging + request. </td> </tr> <tr> @@ -363,43 +328,74 @@ following expression: mdc.get("myKey"). </td> </tr> - <tr> - <td>throwable - </td> + <tr class="alt"> + <td>throwable</td> <td><code>Throwable</code></td> - <td>The exception that was passed to the logger when it - was requested. + <td>The exception associated with the logging event </td> </tr> </table> + - - The behaviour of the filter is also defined by its OnMatch - and OnMismatch options. The configuration specifies thanks - to these elements the replies that the <code>EvaluatorFilter</code> must give once its - expression has been evaluated. The example above returns the value <code>FilterReply.ACCEPT</code> - when the message of the logging event contains the String important. - If important is not contained in the message, then the filter lets the next filter - evaluate this logging event. - - - - Let us see an example of <code>EvaluatorFilter</code>. The <code>FilterEvents</code> - class issues ten logging requests, numbered from 0 to 9. - - - - First, let us run the <code>FilterEvents</code> class with a configuration that does - not contain any filters. This can be done by issuing the following command: + The behaviour of the <code>EvaluatorFilter</code> is also + affected by its OnMatch and OnMismatch options taking values of type + <code>FilterReply</code>, i.e. DENY, ACCEPT, NEUTRAL. + + + Here is a concrete example. + +Example 6.5: Basic event evaluator usage (logback-examples/src/main/java/chapter6/basicEventEvaluator.xml) + +<div class="source"><pre><configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> + <evaluator name="myEval"> + <expression>message.contains("billing")</expression> + </evaluator> + <OnMismatch>NEUTRAL</OnMismatch> + <OnMatch>DENY</OnMatch> + </filter> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern> + %-4relative [%thread] %-5level %logger - %msg%n + </pattern> + </layout> + </appender> + + <root> + <level value="INFO" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> + + The bold part in the previous configuration adds an + <code>EvaluatorFilter</code> to a <code>ConsoleAppender</code>. An + <code>EventEvaluator</code> is then injected into the + <code>EvaluatorFilter</code>. The expression element + corresponds to the evaluation expression described previously. The + expression <code>message.contains("billing")</code> returns a + boolean value. Notice that the message variable is + defined implicitly. + + + This evalutor filter will drop all logging events whose message + contains the string "billing". + + + The <a + href="../xref/chapter6/FilterEvents.html"><code>FilterEvents</code></a> + class issues ten logging requests, numbered from 0 to 9. Let us + rist run <code>FilterEvents</code> class without any filters: <div class="source"><pre> java chapter6.FilterEvents src/main/java/chapter6/basicConfiguration.xml </pre></div> - - All requests will be displayed, as shown below: - + All requests will be displayed, as shown below: <div class="source"><pre>0 [main] INFO chapter6.FilterEvents - logging statement 0 0 [main] INFO chapter6.FilterEvents - logging statement 1 @@ -412,27 +408,15 @@ 0 [main] INFO chapter6.FilterEvents - logging statement 8 0 [main] INFO chapter6.FilterEvents - logging statement 9</pre></div> - - Suppose that we want to get rid of the billing information. We - can use an <code>EvaluatorFilter</code> configured as follows: - -<div class="source"><pre><configuration> - ... - <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> - <evaluator name="myEval"> - <expression>message.contains("billing")</expression> - </evaluator> - <OnMismatch>NEUTRAL</OnMismatch> - <OnMatch>DENY</OnMatch> - </filter> - ... -</configuration></pre></div> - - This filter will deny any logging event whose message - contains the String billing. If we run the <code>FilterEvents</code> - class again, we obtain the following output: + Suppose that we want to get rid of the billing information. + The basicEventEvaluator.xml configuration file just + desribed, does exactly what we want. + + Running with filters: + java chapter6.FilterEvents src/main/java/chapter6/basicEventEvaluator.xml + we obtain: <div class="source"><pre>0 [main] INFO chapter6.FilterEvents - logging statement 0 @@ -468,12 +452,12 @@ request is issued. Their scope is wider than appender-attached filters. - - More importantly, they are called before the <code>LoggingEvent</code> object creation. - Their decision is made based on some of the logging event's components. They require - no logging event instanciation, nor any other treatement to provide their - filtering functionnalities. They are much more performant than the usual - <code>Filter</code> objects. + More importantly, they are called before the + <code>LoggingEvent</code> object creation. Their decision is made + based on some of the logging event's components. They require no + logging event instantiation, nor any other treatement to provide + their filtering functionnalities. They are much more performant + than the usual <code>Filter</code> objects. <h3>Implementing your own TurboFilter</h3> @@ -663,33 +647,34 @@ - <h2>Logback Access</h2> + <h2>Logback-access</h2> - - Logback access benefits from most of the possibilities available - to the classic module. <code>Filter</code> objects are available and work - in the same way as their classic counterpart. They handle access' implementation - of logging events: <code>AccessEvent</code>. - Thus, a customized filter - for logback access is follows strictly the same rules than one for the - classic module, except for the event implemenation recieved as a parameter. - On the other hand, - <code>TurboFilter</code> objects are not available to the access module. + Logback-access offers most of the features available with + logback-classic. <code>Filter</code> objects are available and + work in the same way as their logback-classic counterparts. They + handle access' implementation of logging events: + <code>AccessEvent</code>. Thus, a customized filter for logback + access follows strictly the same rules as those for + logback-classic, except for the event type recieved as parameter. + On the other hand, <code>TurboFilter</code> objects are supported + by logback-access. <h3>Filters</h3> - - <code>EvaluatorFilter</code> objects, with their expressions, are available to - the access module. However, the variables that one can use to build an expression - are different. Only the <code>AccessEvent</code> object can be used, by inserting the - event variable in the expression. Although less wide than its classic - counterpart, the access evaluation filter is just as powerfull. All the - request and response components are reachable from the event variable. + <code>EvaluatorFilter</code> objects with java expressions + supplied in in <code>evaluator</code> configuration elements are + supported by logback-access. However, list implicit variables + available for constructing an expression are different. Only the + <code>AccessEvent</code> object can be used by inserting the + event variable in the expression. Nevertheless the access + <code>evaluator</code> is just as powerfull. All the request and + response components are reachable from the event + variable. - - Here is a sample configuration that will ensure that any 404 error will be displayed: + Here is a sample configuration that will ensure that any 404 + error will be logged: Example 6.9: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator.xml) @@ -714,10 +699,9 @@ <appender-ref ref="STDOUT" /> </configuration></pre></div> - - We might imagine a slightly more complex use of filters to ensure the display of 404 errors, but - to prevent polluting the output with endless accesses to CSS files. Here is what such a configuration - would look like: + We might imagine a slightly more complex use of filters to + ensure logging of 404 errors, except those returned on access to + CSS resources. Here is what such a configuration would look like: Example 6.10: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator2.xml) 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 Mon Aug 25 21:54:06 2008 @@ -460,7 +460,8 @@ the root logger is already named, it does not admit a name attribute either. The value of the level attribute can be set to one of the case-insensitive strings TRACE, DEBUG, INFO, WARN, ERROR, ALL or - OFF. Note that the level of the root logger cannot be inherited. + OFF. Note that the level of the root logger cannot be set to + INHERITED or NULL. @@ -992,16 +993,15 @@ <div class="source"><pre>USER_HOME=/home/sebastien</pre></div> Nested variabled subsitution is also supported. By nested, we - mean that the value definition of a variable contains referenced to - other variables. Here is an example. Suppose you wish to use - variables to specify not only the destination directory but also - the file name, and combine those variable in a third variable - called "destination". The properties file shown below gives an - example. + mean that the value definition of a variable contains references to + other variables. Suppose you wish to use variables to specify not + only the destination directory but also the file name, and combine + those two variables in a third variable called "destination". The + properties file shown below gives an example. - Example 3.: Recursive use of variables + Example 3.: Nested variable references (logback-examples/src/main/java/chapter3/variables2.properties) <div class="source"><pre>USER_HOME=/home/sebastien Modified: logback/trunk/logback-site/src/site/pages/manual/layouts.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/layouts.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/layouts.html Mon Aug 25 21:54:06 2008 @@ -1414,12 +1414,16 @@ <a name="ClassicHTMLLayout"></a> - <h3>HTMLLayout</h3> - - <a href="../xref/ch/qos/logback/classic/html/HTMLLayout.html"> - <code>HTMLLayout</code></a> outputs logging events in an HTML - table where each row of the table corresponds to a logging - event. + <h2>Generating logs in HTML format</h2> + + Logback provides a special <a + href="../xref/ch/qos/logback/core/Layout.html"><code>Layout</code></a>, + namely <a + href="../xref/ch/qos/logback/classic/html/HTMLLayout.html"> + <code>HTMLLayout</code></a>, to generate logs directly in HTML + format. <code>HTMLLayout</code> outputs logging events in an HTML + table where each row of the table corresponds to a logging + event. Here is a sample output produced by <code>HTMLLayout</code> using its default CSS stylesheet: @@ -1438,11 +1442,11 @@ <code>PatternLayout</code> with <code>HTMLLayout</code> is that conversion specifiers should not be separated by space characters or more generally by literal text. Each specifier found in the - pattern willa result in a separate column, in particular for each - literal text in the pattern, wasting valuable real estate on your - screen. - - + pattern will result in a separate column. Likewise a separate + column will be generated for each block of literal text found in + the pattern potentially wasting valuable real estate on your + screen. + Here is simple but functional configuration file illustrating the use of <code>HTMLLayout</code>. @@ -1488,18 +1492,19 @@ <h3>Stack traces</h3> - If you use the %em conversion word, to display stack - traces, a table column will be created to display exception stack - traces. In most cases the column will be empty, wasting screen + If you use the %em conversion word to display stack + traces, a table column will be created to display stack traces. In + most cases the column will be empty, wasting screen real-estate. Moreover, printing a stack trace on a separate column - does yield very readable results. Fortunately, the %ex - conversion word is not the only way to display stack traces. + does not yield very readable results. Fortunately, the + %ex conversion word is not the only way to display stack + traces. A better solution is available through implementations of <code>IThrowableRenderer</code> interface. Such an implementation - can assigned to <code>HTMLLayout</code> to manage the display data - related to exceptions. By default, a + can be assigned to <code>HTMLLayout</code> to manage the display + data related to exceptions. By default, a <a href="../xref/ch/qos/logback/classic/html/DefaultThrowableRenderer.html"> <code>DefaultThrowableRenderer</code></a> is assigned to each <code>HTMLLayout</code> instance. It writes exceptions on a @@ -1508,12 +1513,12 @@ If for some reason, you still wish to use the %ex - pattern, then you can specify - <a href="../xref/ch/qos/logback/core/html/NOPThrowableRenderer.html"> - <code>NOPThrowableRenderer</code></a> in the configuration file - in order to disable displaying a separate row for the stack - trace. We don't have the faintest idea why you would want to do - that, but if you did, you could. + pattern, then you can specify <a + href="../xref/ch/qos/logback/core/html/NOPThrowableRenderer.html"> + <code>NOPThrowableRenderer</code></a> in the configuration file in + order to disable displaying a separate row for the stack trace. We + don't have the faintest idea why you would want to do that, but if + you wished, you could. <h3>CSS</h3> @@ -1522,8 +1527,8 @@ is controlled through a Cascading Style Sheet (CSS). In the absence of specific instructions, <code>HTMLLayout</code> will default to its internal CSS. However, your can instruct - <code>HTMLLayout</code> you use an external CSS file. For this - purpose, a <code>cssBuilder</code> element can be nested within a + <code>HTMLLayout</code> to use an external CSS file. For this + purpose a <code>cssBuilder</code> element can be nested within a <code><layout></code> element, as shown below. @@ -1600,268 +1605,249 @@ <a name="AccessPatternLayout"></a> <h3>PatternLayout</h3> - <a href="../xref/ch/qos/logback/access/PatternLayout.html"> + + <a href="../xref/ch/qos/logback/access/PatternLayout.html"> <code>PatternLayout</code></a> in logback-access can be configured - in the same way as it's classic counterpart, with the notable - exception of the available conversion specifiers, as appropriate - for HTTP servlet request and response. - + much in the same way as its classic counterpart. However it + features additional conversion specifiers suited for logging + particular bits of information availalbe only in HTTP servlet + requests and HTTP servlet responses. + Below is a list of conversion specifiers for <code>PatternLayout</code> in logback-access. <table class="bodyTable" border="0" CELLPADDING="8"> - <th align="center">Conversion Word</th> - <th align="center">Effect</th> - - <tr class="a"> - <td align="center">a / remoteIP</td> - <td> - - Remote IP address. - - </td> - </tr> - <tr class="b"> - <td align="center">A / localIP</td> - <td> - - Local IP address. - - </td> - </tr> - <tr class="a"> - <td align="center">b / B / byteSent</td> - <td> - - Response's content length. - - </td> - </tr> - <tr class="b"> - <td align="center">h / clientHost</td> - <td> - - Remote host. - - </td> - </tr> - <tr class="a"> - <td align="center">H / protocol</td> - <td> - - Request protocol. - - </td> - </tr> - <tr class="b"> - <td align="center">l</td> - <td> - - Remote log name. In logback-access, this converter always - returns the value "-". - - </td> - </tr> - - <tr class="a"> - <td align="center">reqParameter{paramName}</td> - <td> - - Parameter of the response. - - This conversion word takes the first option in braces and looks - for the corresponding parameter in the request. - %reqParameter{input_data} - displays the corresponding parameter. - </td> - </tr> - <tr class="b"> - <td align="center">i{header} / header{header}</td> - <td> - - Request header. - - This conversion word takes the first option in braces and looks - for the corresponding header in the request. - %header{Referer} displays the referer of the request. - - If no option is specified, it displays every available header. - - </td> - </tr> - <tr class="a"> - <td align="center">m / requestMethod</td> - <td> - - Request method. - - </td> - </tr> - <tr class="b"> - <td align="center">r / requestURL</td> - <td> - - URL requested. - - </td> - </tr> - <tr class="a"> - <td align="center">s / statusCode</td> - <td> - - Status code of the request. - - </td> - </tr> - <tr class="b"> - <td align="center">t / date</td> - <td> - - Used to output the date of the logging event. - The date conversion specifier may be followed by - a set of braces containing a date and time - pattern strings used by - <code>java.text.SimpleDateFormat</code> - . - ABSOLUTE - , - DATE - or - ISO8601 - can also be used. + <tr> + <th align="center">Conversion Word</th> + <th align="center">Effect</th> + </tr> + <tr class="a"> + <td align="center">a / remoteIP</td> + <td> + + Remote IP address. + + </td> + </tr> + <tr class="b"> + <td align="center">A / localIP</td> + <td> + + Local IP address. + + </td> + </tr> + <tr class="a"> + <td align="center">b / B / byteSent</td> + <td> + + Response's content length. + + </td> + </tr> + <tr class="b"> + <td align="center">h / clientHost</td> + <td> + + Remote host. + + </td> + </tr> + <tr class="a"> + <td align="center">H / protocol</td> + <td> + + Request protocol. + + </td> + </tr> + <tr class="b"> + <td align="center">l</td> + <td> + + Remote log name. In logback-access, this converter always + returns the value "-". + + </td> + </tr> + + <tr class="a"> + <td align="center">reqParameter{paramName}</td> + <td> + + Parameter of the response. + + This conversion word takes the first option in braces and looks + for the corresponding parameter in the request. + %reqParameter{input_data} + displays the corresponding parameter. + </td> + </tr> + <tr class="b"> + <td align="center">i{header} / header{header}</td> + <td> + + Request header. + + This conversion word takes the first option in braces and looks + for the corresponding header in the request. + %header{Referer} displays the referer of the request. + + If no option is specified, it displays every available header. + + </td> + </tr> + <tr class="a"> + <td align="center">m / requestMethod</td> + <td> + + Request method. + + </td> + </tr> + <tr class="b"> + <td align="center">r / requestURL</td> + <td> + + URL requested. + + </td> + </tr> + <tr class="a"> + <td align="center">s / statusCode</td> + <td> + + Status code of the request. + + </td> + </tr> + <tr class="b"> + <td align="center">t / date</td> + <td> + Used to output the date of the logging event. The date + conversion specifier may be followed by a set of braces + containing a date and time pattern strings used by + <code>java.text.SimpleDateFormat</code>. ABSOLUTE, + DATE or ISO8601 are also valid values. - - For example, - %d{HH:mm:ss,SSS} - , - - %d{dd MMM yyyy ;HH:mm:ss,SSS} - - or - %d{DATE} - . If no date format specifier is given then - ISO8601 format is assumed. + For example, %d{HH:mm:ss,SSS}, + %d{dd MMM yyyy ;HH:mm:ss,SSS} or + %d{DATE}. If no date format specifier is given then + ISO8601 format is assumed. - </td> - </tr> - <tr class="a"> - <td align="center">u / user</td> - <td> - - Remote user. - - </td> - </tr> - <tr class="b"> - <td align="center">U / requestURI</td> - <td> - - Requested URI. - - </td> - </tr> - <tr class="a"> - <td align="center">v / server</td> - <td> - - Server name. - - </td> - </tr> - <tr class="b"> - <td align="center">localPort</td> - <td> - - Local port. - - </td> - </tr> - <tr class="a"> - <td align="center">reqAttribute{attributeName}</td> - <td> - - Attribute of the request. - - This conversion word takes the first option in braces and looks - for the corresponding attribute in the request. - %reqAttribute{SOME_ATTRIBUTE} - displays the corresponding attribute. - </td> - </tr> - <tr class="b"> - <td align="center">reqCookie{cookie}</td> - <td> - - Request cookie. - - This conversion word takes the first option in braces and looks - for the corresponding cookie in the request. - %cookie{COOKIE_NAME} displays corresponding cookie. - </td> - </tr> - <tr class="a"> - <td align="center">responseHeader{header}</td> - <td> - - Header of the response. - - This conversion word takes the first option in braces and looks - for the corresponding header in the response. - %header{Referer} displays the referer of the response. - </td> - </tr> - <tr class="b"> - <td align="center">requestContent</td> - <td> - - This conversion word displays the content of the request, that is the - request's <code>InputStream</code>. It is used in conjunction with a - <a href="../xref/ch/qos/logback/access/servlet/TeeFilter.html"> - <code>TeeFilter</code></a>, a <code>javax.servlet.Filter</code> that - replaces the original <code>HttpServletRequest</code> - by a <a href="../xref/ch/qos/logback/access/servlet/TeeHttpServletRequest.html"> - <code>TeeHttpServletRequest</code></a>. The latter object allows - access to the requet's <code>InputStream</code> multiple times without - any loss of data. - - </td> - </tr> - <tr class="a"> - <td align="center">fullRequest</td> - <td> - This converter outputs the data associated with the + </td> + </tr> + <tr class="a"> + <td align="center">u / user</td> + <td> + + Remote user. + + </td> + </tr> + <tr class="b"> + <td align="center">U / requestURI</td> + <td> + + Requested URI. + + </td> + </tr> + <tr class="a"> + <td align="center">v / server</td> + <td> + Server name. + </td> + </tr> + <tr class="b"> + <td align="center">localPort</td> + <td> + Local port. + </td> + </tr> + <tr class="a"> + <td align="center">reqAttribute{attributeName}</td> + <td> + Attribute of the request. + This conversion word takes the first option in braces and looks + for the corresponding attribute in the request. + %reqAttribute{SOME_ATTRIBUTE} + displays the corresponding attribute. + </td> + </tr> + <tr class="b"> + <td align="center">reqCookie{cookie}</td> + <td> + Request cookie. + This conversion word takes the first option in braces and looks + for the corresponding cookie in the request. + %cookie{COOKIE_NAME} displays corresponding cookie. + </td> + </tr> + <tr class="a"> + <td align="center">responseHeader{header}</td> + <td> + + Header of the response. + + This conversion word takes the first option in braces and looks + for the corresponding header in the response. + %header{Referer} displays the referer of the response. + </td> + </tr> + <tr class="b"> + <td align="center">requestContent</td> + <td> + This conversion word displays the content of the request, + that is the request's <code>InputStream</code>. It is used + in conjunction with a <a + href="../xref/ch/qos/logback/access/servlet/TeeFilter.html"> + <code>TeeFilter</code></a>, a + <code>javax.servlet.Filter</code> that replaces the original + <code>HttpServletRequest</code> by a <a + href="../xref/ch/qos/logback/access/servlet/TeeHttpServletRequest.html"> + <code>TeeHttpServletRequest</code></a>. The latter object + allows access to the requet's <code>InputStream</code> + multiple times without any loss of data. + + </td> + </tr> + <tr class="a"> + <td align="center">fullRequest</td> + <td> + This converter outputs the data associated with the request, including all headers and request contents. - - </td> - </tr> - <tr class="b"> - <td align="center">responseContent</td> - <td> - - This conversion word displays the content of the response, that is the - response's <code>InputStream</code>. It is used in conjunction with a + + </td> + </tr> + <tr class="b"> + <td align="center">responseContent</td> + <td> + This conversion word displays the content of the + response, that is the response's + <code>InputStream</code>. It is used in conjunction with a <a href="../xref/ch/qos/logback/access/servlet/TeeFilter.html"> - <code>TeeFilter</code></a>, a <code>javax.servlet.Filter</code> that - replaces the original <code>HttpServletResponse</code> - by a <a href="../xref/ch/qos/logback/access/servlet/TeeHttpServletResponse.html"> - <code>TeeHttpServletResponse</code></a>. The latter object allows - access to the requet's <code>InputStream</code> multiple times without - any loss of data. - - </td> - </tr> - <tr class="a"> - <td align="center">fullResponse</td> - <td> - - This conversion word takes all the available data + <code>TeeFilter</code></a>, a + <code>javax.servlet.Filter</code> that replaces the original + <code>HttpServletResponse</code> by a <a + href="../xref/ch/qos/logback/access/servlet/TeeHttpServletResponse.html"> + <code>TeeHttpServletResponse</code></a>. The latter object + allows access to the requet's <code>InputStream</code> + multiple times without any loss of data. + + </td> + </tr> + <tr class="a"> + <td align="center">fullResponse</td> + <td> + This conversion word takes all the available data associatede with the response, inclusing all headers of the response and response contents. - - </td> - </tr> - </table> + + </td> + </tr> + </table> Logback access' <code>PatternLayout</code> also recognize three keywords, which act like shortcuts to a certain pattern. @@ -1887,10 +1873,10 @@ which displays client host, remote log name, user, date, requested URL, status code and response's content length - The combined keyword is a shortcut to - %h %l %u %t \"%r\" %s %b \"%i{Referer}\" \"%i{User-Agent}\". This pattern begins - much like the common pattern but also displays two request headers, namely - referer, and user-agent. + The combined keyword is a shortcut for %h %l %u %t + \"%r\" %s %b \"%i{Referer}\" \"%i{User-Agent}\". This pattern + begins much like the common pattern but also displays two + request headers, namely referer, and user-agent. <a name="AccessHTMLLayout"></a> <h3>HTMLLayout</h3> @@ -1898,37 +1884,49 @@ The <a href="../xref/ch/qos/logback/access/html/HTMLLayout.html"><code>HTMLLayout</code></a> class found in logback-access is similar to the <a - href="#ClassicHTMLLayout"><code>HTMLLayout</code></a> class found - in logback-classic. + href="#ClassicHTMLLayout"><code>HTMLLayout</code></a> class from + logback-classic. By default, it will create a table containing the following data: <ul> - Remote IP - Date - Request URL - Status code - Content Length + <li>Remote IP</li> + <li>Date</li> + <li>Request URL</li> + <li>Status code</li> + <li>Content Length</li> </ul> - Here is a sample output produced by <code>HTMLLayout</code> in logback-access: + Here is a sample output produced by <code>HTMLLayout</code> in + logback-access: <img src="images/htmlLayoutAccess.gif" alt="Access HTML Layout Sample Image"/> - What is better than a real world example? Our own log4j + What can be better than a real world example? Our own log4j properties to logback <a href="http://logback.qos.ch/translator/">translator</a> makes use of logback-access to showcase a live ouput, using a <code>RollingFileAppender</code> and <code>HTMLLayout</code>. - You can see the file by <a - href="http://logback.qos.ch/translator/logs/access.html">following - this link</a>. - - Just like any access log, each visit the <a - href="http://logback.qos.ch/translator/">translator</a> - web-application will add a new entry to the access logs. - + What can be better than a real world example? Our own log4j + properties for logback <a + href="http://logback.qos.ch/translator/">translator</a> makes use + of logback-access to demonstrate live ouput from + <code>RollingFileAppender</code> with <code>HTMLLayout</code>. + + + On every new user request to our <a + href="http://logback.qos.ch/translator/">translator</a> + web-application, a new entry will be added to the access logs, + which you can view by <a + href="http://logback.qos.ch/translator/logs/access.html">following + this link</a>. + + + + + + <script src="../templates/footer.js"></script> </div> Modified: logback/trunk/logback-site/src/site/pages/manual/mdc.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/mdc.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/mdc.html Mon Aug 25 21:54:06 2008 @@ -50,12 +50,11 @@ the SLF4J API: Mapped Diagnostic Contexts (MDC). - - To uniquely stamp each request, the user puts contextual - information into the <code><a - href="http://www.slf4j.org/api/org/slf4j/MDC.html">MDC</a></code>, - the abbreviation of Mapped Diagnostic Context. The public - interface of the MDC class is shown below. + To uniquely stamp each request, the user puts contextual + information into the <code><a + href="http://www.slf4j.org/api/org/slf4j/MDC.html">MDC</a></code>, + the abbreviation of Mapped Diagnostic Context. The salient parts + of the MDC class is shown below. <div class="source"><pre>package org.slf4j; @@ -73,9 +72,6 @@ //Clear all entries in the MDC. public static void clear(); - - //Returns the keys in the MDC as a Set. The returned value can be null. - public static Set<String> getKeys(); }</pre></div> The <code>MDC</code> class contains only static methods. It @@ -615,6 +611,28 @@ are unaffected. Furthermore, any given thread will contain correct MDC data any point in time. + + + <h3>MDC And Managed Threads</h3> + + A copy of mapped diagnostic context can not always be inherited + by worker thread from the initiating thread. This is the case when + <code>java.util.concurrent.Executors</code> is used for thread + management. For instance, <code>newCachedThreadPool</code> method + creates a <code>ThreadPoolExecutor</code> and like other thread + pooling code it has intricate thread creation logic. + + + In such cases, it is recommended that + <code>MDC.getCopyOfContextMap()</code> is invoked on the original + (master) thread before submitting a task to the executor. When the + task runs, as its first action, it should invoke + <code>MDC.setContextMapValues()</code> to associate the stored copy + of the orinal MDC values with the new <code>Executor</code> managed + thread. + + + <script src="../templates/footer.js"></script> </div> </body>

1 0

[JIRA] Resolved: (LBSITE-15) logback mail lists cannot be reached again
by Ceki Gulcu (JIRA) 25 Aug '08

25 Aug '08

[ http://jira.qos.ch/browse/LBSITE-15?page=com.atlassian.jira.plugin.system.i… ] Ceki Gulcu resolved LBSITE-15. ------------------------------ Fix Version/s: unspecified Resolution: Fixed The hardware failure behind this issue has been solved with a new machine. Moreover, both the DNS and email servers are now duplicated. > logback mail lists cannot be reached again > ------------------------------------------ > > Key: LBSITE-15 > URL: http://jira.qos.ch/browse/LBSITE-15 > Project: logback-site > Issue Type: Bug > Components: other > Affects Versions: unspecified > Environment: Operating System: All > Platform: All > URL: http://www.dnsstuff.com/tools/dnsreport.ch?domain=qos.ch > Reporter: Ralph Goers > Assignee: Logback dev list > Fix For: unspecified > > > Hi, > my emails to the logback mail lists are consitently bouncing. A quick check on qos.ch DNS configuration shows there are serious problems with it. Likely this is why your mail server appears to never be available. > See for example this report: http://www.dnsstuff.com/tools/dnsreport.ch?domain=qos.ch -- 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 0

[JIRA] Created: (LBSITE-17) wrong docs for variable substitution
by Ceki Gulcu (JIRA) 25 Aug '08

25 Aug '08

wrong docs for variable substitution ------------------------------------ Key: LBSITE-17 URL: http://jira.qos.ch/browse/LBSITE-17 Project: logback-site Issue Type: Bug Components: Documentation Reporter: Ceki Gulcu Assignee: Logback dev list Rob Ross reports: Also, on Chapter 3 of the current Logback documentation manual, when it discusses variable substitution it mentions "Recursive Substitution." Well, if you re-read that section carefully I think you'll agree that this example is in fact NOT doing any kind of *recursion*, it is just using multiple variables. They are not even being nested. So I would suggest calling it something other than "recursion." The people that will read this manual are programmers, and we all know (or should know ) what recursion is, and I think this will just confuse people. reference http://www.qos.ch/pipermail/logback-user/2008-July/000492.html -- 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] Resolved: (LBSITE-8) Provide links to externals
by Ceki Gulcu (JIRA) 24 Aug '08

24 Aug '08

[ http://jira.qos.ch/browse/LBSITE-8?page=com.atlassian.jira.plugin.system.is… ] Ceki Gulcu resolved LBSITE-8. ----------------------------- Resolution: Fixed Initial references to SLF4J now reference the SLF4J site. This should help newbies find the SLF4J project more easily. > Provide links to externals > -------------------------- > > Key: LBSITE-8 > URL: http://jira.qos.ch/browse/LBSITE-8 > Project: logback-site > Issue Type: Bug > Components: Documentation > Affects Versions: unspecified > Environment: Operating System: All > Platform: All > Reporter: Sebastian Davids > Assignee: Logback dev list > > Provide at least links to SLF4J on the documentation pages and possibly on the main menu. -- 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 0

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

24 Aug '08

Author: ceki Date: Sun Aug 24 23:58:15 2008 New Revision: 1776 Modified: logback/trunk/logback-site/src/site/pages/manual/introduction.html logback/trunk/logback-site/src/site/pages/setup.html Log: LBSITE-8 Add references to SLF4J in the manual, so that new users have an easier time to find it. 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 Sun Aug 24 23:58:15 2008 @@ -69,6 +69,10 @@ logback-classic.jar on the classpath. + The logback-*.jar files are part of the logback + distribution whereas slf4j-api-${slf4j.version}.jar ships + with <a href="http://www.slf4j.org">SLF4J</a>, a separate project. + Let us now begin experimenting with logback. @@ -88,24 +92,24 @@ } }</pre></div> - - The <code>HelloWorld</code> class is defined in the - <code>chapter1</code> package. It starts by importing the <code>Logger</code> - and <code>LoggerFactory</code> - classes defined in the SLF4J API, more specifically within the <code>org.slf4j</code> - package. + <code>HelloWorld</code> class is defined in the + <code>chapter1</code> package. It starts by importing the <a + href="http://slf4j.org/api/org/slf4j/Logger.html"><code>Logger</code></a> + and <a + href="http://slf4j.org/api/org/slf4j/LoggerFactory.html"><code>LoggerFactory</code></a> + classes defined in the SLF4J API, more specifically within the + <code>org.slf4j</code> package. - - On the first line of the main() method, the variable named - <code>logger</code> is assigned a <code>Logger</code> instance - retrieved by invoking the static <code>getLogger</code> method - from the <code>LoggerFactory</code> class. This logger is named - "chapter1.HelloWorld1". The main method proceeds to call the - <code>debug</code> method of this logger passing "Hello World" - as an argument. We say that the main method contains a logging - statement of level DEBUG with the message "Hello world". + On the first line of the main() method, the variable named + <code>logger</code> is assigned a <code>Logger</code> instance + retrieved by invoking the static <code>getLogger</code> method + from the <code>LoggerFactory</code> class. This logger is named + "chapter1.HelloWorld1". The main method proceeds to call the + <code>debug</code> method of this logger passing "Hello World" as + an argument. We say that the main method contains a logging + statement of level DEBUG with the message "Hello world". Note that the above example does not reference any logback @@ -130,14 +134,12 @@ <div class="source"><pre>20:49:07.962 [main] DEBUG chapter1.HelloWorld1 - Hello world.</pre></div> - - Logback can report information about its internal state - using a built-in status system. Important events occuring - during logback's lifetime can be accessed through a - <code>StatusManager</code>. For the time being, let us instruct logback to print its - internal state. This is accomplished by a static method in - the <code>LoggerStatusPrinter</code> - class. + Logback can report information about its internal state using a + built-in status system. Important events occuring during logback's + lifetime can be accessed through a <code>StatusManager</code>. For + the time being, let us instruct logback to print its internal + state. This is accomplished by a static method in the + <code>LoggerStatusPrinter</code> class. Example 1.2: Printing Logger Status (<a href="../xref/chapter1/HelloWorld2.html">logback-examples/src/main/java/chapter1/HelloWorld2.java</a>) @@ -164,11 +166,16 @@ Running the <code>HelloWorld2</code> application will produce the following output: -<div class="source"><pre>20:49:07.962 [main] DEBUG chapter1.HelloWorld2 - Hello world. -|-INFO in ch.qos.logback.classic.BasicConfigurator@1c1ea29 - Setting up default configuration.</pre></div> +<div class="source"><pre>12:49:22.203 [main] DEBUG chapter1.HelloWorld2 - Hello world. +12:49:22,078 |-INFO in ch.qos.logback.classic.LoggerContext[default] - Could NOT find resource [logback-test.xml] +12:49:22,093 |-INFO in ch.qos.logback.classic.LoggerContext[default] - Could NOT find resource [logback.xml] +12:49:22,093 |-INFO in ch.qos.logback.classic.LoggerContext[default] - Setting up default configuration. +</pre></div> - Logback explains that it configured itself using its default + Logback explains that having failed to find the + logback-test.xml and logback.xml configuration + files (discussed later), 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 @@ -177,6 +184,9 @@ appropriate for their specific situation. + Note that in case of errors, logback will automatically print its + internal state on the console. + 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 Modified: logback/trunk/logback-site/src/site/pages/setup.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/setup.html (original) +++ logback/trunk/logback-site/src/site/pages/setup.html Sun Aug 24 23:58:15 2008 @@ -33,6 +33,11 @@ <li>slf4j-api-${slf4j.version}.jar</li> </ul> + The logback-*.jar files are part of the logback + distribution whereas slf4j-api-${slf4j.version}.jar ships + with <a href="http://www.slf4j.org">SLF4J</a>, a separate project. + + <h3>Running from the command line</h3> Assuming your current directory is

1 0

svn commit: r1775 - in logback/trunk: logback-examples/src/main/java/chapter3 logback-site/src/site/pages logback-site/src/site/pages/manual
by noreply.ceki＠qos.ch 23 Aug '08

23 Aug '08

Author: ceki Date: Sun Aug 24 00:25:55 2008 New Revision: 1775 Added: logback/trunk/logback-examples/src/main/java/chapter3/containingConfig.xml - copied, changed from r1772, /logback/trunk/logback-examples/src/main/java/chapter3/redirectConfig.xml logback/trunk/logback-site/src/site/pages/joran.html Removed: logback/trunk/logback-examples/src/main/java/chapter3/redirectConfig.xml Modified: logback/trunk/logback-examples/src/main/java/chapter3/includedConfig.xml logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution1.xml logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution2.xml logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution3.xml logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution4.xml logback/trunk/logback-examples/src/main/java/chapter3/variables1.properties logback/trunk/logback-examples/src/main/java/chapter3/variables2.properties logback/trunk/logback-site/src/site/pages/documentation.html logback/trunk/logback-site/src/site/pages/manual/joran.html Log: - ongoing work on the documentation Chapter3 has been split into two parts, the fist part on logback configuration and a second part on Joran as a standalone framework Copied: logback/trunk/logback-examples/src/main/java/chapter3/containingConfig.xml (from r1772, /logback/trunk/logback-examples/src/main/java/chapter3/redirectConfig.xml) ============================================================================== --- /logback/trunk/logback-examples/src/main/java/chapter3/redirectConfig.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter3/containingConfig.xml Sun Aug 24 00:25:55 2008 @@ -2,6 +2,11 @@ <configuration> - <include file="path/to/configuration/file" /> + <include file="src/main/java/chapter3/includedConfig.xml" /> + + <root level="DEBUG"> + <appender-ref ref="includedConsole" /> + </root> + </configuration> Modified: logback/trunk/logback-examples/src/main/java/chapter3/includedConfig.xml ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter3/includedConfig.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter3/includedConfig.xml Sun Aug 24 00:25:55 2008 @@ -2,16 +2,10 @@ <included> - <appender name="redirectConsole" - class="ch.qos.logback.core.ConsoleAppender"> + <appender name="includedConsole" class="ch.qos.logback.core.ConsoleAppender"> <layout class="ch.qos.logback.classic.PatternLayout"> <param name="Pattern" value="%d - %m%n" /> </layout> </appender> - <root> - <level value="DEBUG" /> - <appender-ref ref="redirectConsole" /> - </root> - </included> \ No newline at end of file Modified: logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution1.xml ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution1.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution1.xml Sun Aug 24 00:25:55 2008 @@ -1,9 +1,9 @@ <configuration> - <substitutionProperty name="user.home.dir" value="/home/sebastien" /> + <substitutionProperty name="USER_HOME" value="/home/sebastien" /> <appender name="FILE" class="ch.qos.logback.core.FileAppender"> - <file>${user.home.dir}/myApp.log</file> + <file>${USER_HOME}/myApp.log</file> <layout class="ch.qos.logback.classic.PatternLayout"> <Pattern>%msg%n</Pattern> </layout> Modified: logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution2.xml ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution2.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution2.xml Sun Aug 24 00:25:55 2008 @@ -1,18 +1,9 @@ <configuration> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> - <file>${user.home.dir}/myApp.log</file> - <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> - myApp-%d{yyyy-MM-dd-HH}.log - </FileNamePattern> - </rollingPolicy> + <appender name="FILE" class="ch.qos.logback.core.FileAppender"> + <file>${USER_HOME}/myApp.log</file> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> - %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> + <Pattern>%msg%n</Pattern> </layout> </appender> Modified: logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution3.xml ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution3.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution3.xml Sun Aug 24 00:25:55 2008 @@ -2,19 +2,10 @@ <substitutionProperty file="variables1.properties" /> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> - <file>${user.home.dir}/myApp.log</file> - <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> - myApp-%d{yyyy-MM-dd-HH}.log - </FileNamePattern> - </rollingPolicy> + <appender name="FILE" class="ch.qos.logback.core.FileAppender"> + <file>${USER_HOME}/myApp.log</file> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> - %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> + <Pattern>%msg%n</Pattern> </layout> </appender> Modified: logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution4.xml ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution4.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter3/variableSubstitution4.xml Sun Aug 24 00:25:55 2008 @@ -2,19 +2,10 @@ <substitutionProperty file="variables2.properties" /> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> - <file>${destination}</file> - <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> - myApp-%d{yyyy-MM-dd-HH}.log - </FileNamePattern> - </rollingPolicy> + <appender name="FILE" class="ch.qos.logback.core.FileAppender"> + <file>${destination}/myApp.log</file> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> - %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> + <Pattern>%msg%n</Pattern> </layout> </appender> Modified: logback/trunk/logback-examples/src/main/java/chapter3/variables1.properties ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter3/variables1.properties (original) +++ logback/trunk/logback-examples/src/main/java/chapter3/variables1.properties Sun Aug 24 00:25:55 2008 @@ -1 +1 @@ -user.home.dir=/Users/seb \ No newline at end of file +USER_HOME=/home/sebastien \ No newline at end of file Modified: logback/trunk/logback-examples/src/main/java/chapter3/variables2.properties ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter3/variables2.properties (original) +++ logback/trunk/logback-examples/src/main/java/chapter3/variables2.properties Sun Aug 24 00:25:55 2008 @@ -1,3 +1,3 @@ -user.home.dir=/Users/seb +USER_HOME=/home/sebastien fileName=myApp.log -destination=${user.home.dir}/${fileName} \ No newline at end of file +destination=${USER_HOME}/${fileName} \ No newline at end of file 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 24 00:25:55 2008 @@ -38,7 +38,11 @@ <li> <a href="dependencies.html">Dependencies per module</a> </li> - + + <li> + <a href="joran.html">Using Joran in your applications</a> + </li> + <li> <a href="jmxConfig.html">How to use the logback JMX Configurator</a> </li> Added: logback/trunk/logback-site/src/site/pages/joran.html ============================================================================== --- (empty file) +++ logback/trunk/logback-site/src/site/pages/joran.html Sun Aug 24 00:25:55 2008 @@ -0,0 +1,512 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" /> +<title>Using Joran</title> +<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" /> +<link rel="stylesheet" type="text/css" media="print" href="css/print.css" /> + +</head> +<body> + <script type="text/javascript">prefix='./'</script> + <script type="text/javascript" src="templates/header.js"></script> +<div id="left"> + <script type="text/javascript" src="templates/left.js"></script> +</div> +<div id="right"><script type="text/javascript" src="templates/right.js"></script></div> +<div id="content"> + + <h2>Using Joran in your own applications</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. + + + 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. + + + The examples + for this chapter can be found under + LOGBACK_HOME/logback-examples/src/main/java/chapter3. + + + 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. + + + In log4j, logback's predecessor, <code>DOMConfigurator</code> + which shipped with log4j version 1.2.x could also 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. + + + <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. + + + 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 location information, available only with + the SAX API. Location information allows Joran to display the exact + line and column number where an error occured, which comes in quite + handy when hunting down problems. + + + + <h2>Actions</h2> + + 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; + +import org.xml.sax.Attributes; +import ch.qos.logback.core.joran.spi.ExecutionContext; + +public abstract class Action { + + + /** + * Called when the parser first encounters an element. + */ + public abstract void begin(ExecutionContext ec, + String name, + Attributes attributes); + + /** + * Called when the parser encounters the element end. At + * this stage, we can assume that child elements, if any, + * have been processed. + */ + public abstract void end(ExecutionContext ec, String name); +}</pre></div> + + Thus, every action must implement the begin and end methods. + + + <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. + + + 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> + + 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: + + + <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. + + + 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. + + + <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.: Calculator configuration file + (logback-examples/src/main/java/chapter3/calculator/calculator3.xml) + +<div class="source"><pre><computation name="toto"> + <computation> + <literal value="7"/> + <literal value="3"/> + <add/> + </computation> + + <literal value="3"/> + <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: + + 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) + +<div class="source"><pre><computation name="toto"> + <new-rule pattern="*/computation/literal" + actionClass="chapter3.calculator.LiteralAction"/> + <new-rule pattern="*/computation/add" + actionClass="chapter3.calculator.AddAction"/> + <new-rule pattern="*/computation/multiply" + actionClass="chapter3.calculator.MultiplyAction"/> + + <computation> + <literal value="7"/> + <literal value="3"/> + <add/> + </computation> + + <literal value="3"/> + <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. + + + 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. + + + Both <code>ImplicitAction</code> and + <code>NestedComponentIA</code> are located in the + <code>ch.qos.logback.core.joran.action</code> package. + + + Refer to the + logback-examples/src/main/java/joran/implicit directory for + an example of an implicit action. + + + In that directory, you will find two actions classes, one xml + file and one class containing the setup of Joran. + + 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: + + Example 3.: Usage of implicit rules + (logback-examples/src/main/java/chapter3/implicit/implicit1.xml) +<div class="source"><pre><foo> + + <xyz printme="true"> + <abc printme="true"/> + </xyz> + + <xyz/> + + <foo printme="true"/> + +</foo></pre></div> + + 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>. + + 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. + + <h3>Non goals</h3> + + The Joran API is not intended to be used to parse documents with + thousands of elements. + + + +<script src="templates/footer.js"></script> +</div> +</body> +</html> 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 Sun Aug 24 00:25:55 2008 @@ -5,7 +5,7 @@ <title>Chapter3: Logback configuration & Joran</title> <link rel="stylesheet" type="text/css" media="screen" href="../css/site.css" /> <link rel="stylesheet" type="text/css" media="print" href="../css/print.css" /> -<link type="text/css" rel="stylesheet" href="../ghighlighter/Styles/SyntaxHighlighter.css"></link> + </head> <body> @@ -881,24 +881,22 @@ <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. - - - 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. + In principle, variable substitution can occur at any point where + a value can be specified. 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 in the + configuration file itself, in an external properties file or as a + system property. 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 next example shows a variable, a.k.a. a substitution + property, declared the beginning of the configuration file. It is + then used further down the file to specify the location of the + output file. Example 3.: Simple Variable substitution @@ -907,21 +905,13 @@ <div class="source"><pre><configuration> - <substitutionProperty name="user.home.dir" value="/Users/seb" /> + <substitutionProperty name="USER_HOME" value="/home/sebastien" /> <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> - <file>${user.home.dir}/myApp.log</file> - <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> - myApp-%d{yyyy-MM-dd-HH}.log - </FileNamePattern> - </rollingPolicy> + class="ch.qos.logback.core.FileAppender"> + <file>${USER_HOME}/myApp.log</file> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> - %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> + <Pattern>%msg%n</Pattern> </layout> </appender> @@ -932,9 +922,13 @@ </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 in the configuration + file, thus logback will look for it in the System properties. Java + system properties can be set on the command line. + + java -DUSER_HOME="/home/sebastien" MyApp2 Example 3.: System Variable substitution (logback-examples/src/main/java/chapter3/variableSubstitution2.xml) @@ -943,18 +937,10 @@ <div class="source"><pre><configuration> <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> - <file>${user.home.dir}/myApp.log</file> - <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> - myApp-%d{yyyy-MM-dd-HH}.log - </FileNamePattern> - </rollingPolicy> + class="ch.qos.logback.core.FileAppender"> + <file>${USER_HOME}/myApp.log</file> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> - %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> + <Pattern>%msg%n</Pattern> </layout> </appender> @@ -964,7 +950,8 @@ </root> </configuration></pre></div> - When many variables are used, it is often more convenient to + + When multiple variables are needed, it may be more convenient to create a separate file that will contain all the variables. Here is how one can do such a setup. @@ -978,19 +965,11 @@ <substitutionProperty file="variables1.properties" /> - <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> - <file>${user.home.dir}/myApp.log</file> - <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> - myApp-%d{yyyy-MM-dd-HH}.log - </FileNamePattern> - </rollingPolicy> + <appender name="FILE" + class="ch.qos.logback.core.FileAppender"> + <file>${USER_HOME}/myApp.log</file> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> - %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> + <Pattern>%msg%n</Pattern> </layout> </appender> @@ -1000,56 +979,53 @@ </root> </configuration></pre></div> - -This configuration file contains a link to another file called variables1.properties. -The variables contained in that other file will be read and will thus be available to the -logback configuration file. Here is what the variable.properties file looks like. - - -Example 3.: Variable file (logback-examples/src/main/java/chapter3/variables1.properties) -<div class="source"><pre>user.home.dir=/Users/seb</pre></div> - - -Nothing more is needed to declare the variable. - - - -Recursive subsitution is also available. If the user wants to use variables to -specify not only the destination directory but also the file name, here is what she -would write in her variables1.properties file. - - - -Example 3.: Recursive use of variables -(logback-examples/src/main/java/chapter3/variables2.properties) -<div class="source"><pre>user.home.dir=/Users/seb + This configuration file contains a reference to a file named + variables1.properties. The variables contained in that + file will be read defined within the context of the logback + configuration file. Here is what the variable.properties + file might look like. + + + Example 3.: Variable file + (logback-examples/src/main/java/chapter3/variables1.properties) + + <div class="source"><pre>USER_HOME=/home/sebastien</pre></div> + + Nested variabled subsitution is also supported. By nested, we + mean that the value definition of a variable contains referenced to + other variables. Here is an example. Suppose you wish to use + variables to specify not only the destination directory but also + the file name, and combine those variable in a third variable + called "destination". The properties file shown below gives an + example. + + + + Example 3.: Recursive use of variables + (logback-examples/src/main/java/chapter3/variables2.properties) + + <div class="source"><pre>USER_HOME=/home/sebastien fileName=myApp.log -destination=${user.home.dir}/${fileName}</pre></div> +destination=${USER_HOME}/${fileName}</pre></div> - In the configuration file, only the last variable, - ${destination} will be used, as shown below: + Note that in the properties file above, "destination" is + composed out of two other variables, namely "USER_HOME" and + "fileName". - - Example 3.: Variable substitution using a separate file + + 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" /> + <substitutionProperty file="variables2.properties" /> <appender name="FILE" - class="ch.qos.logback.core.rolling.RollingFileAppender"> + class="ch.qos.logback.core.FileAppender"> <file>${destination}</file> - <rollingPolicy - class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <FileNamePattern> - myApp-%d{yyyy-MM-dd-HH}.log - </FileNamePattern> - </rollingPolicy> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern> - %date %level [%thread] %logger{10} [%file : %line] %msg%n - </Pattern> + <Pattern>%msg%n</Pattern> </layout> </appender> @@ -1059,546 +1035,62 @@ </root> </configuration></pre></div> + <h3>Default substitution values for variables</h3> + + Under certain circumstances, it may be desirable for a variable + to have a default value in case it is not declared or its value is + null. As in the <a + href="http://tldp.org/LDP/abs/html/parameter-substitution.html">Bash + shell</a>, default values can be specified using the ":-" + operator. For example, assuming aKey is not defined, + <code>"${aKey:-golden}"</code> will be interpreted as + "golden". + + <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: + Joran supports including parts of a configuration file from + another file. This is done by declaring a <code><include></code> + element, as shown below: Example 3.: File include - (logback-examples/src/main/java/chapter3/redirectConfig.xml) + (logback-examples/src/main/java/chapter3/containingConfig.xml) <div class="source"><pre><configuration> - <include file="path/to/configuration/file"/> - </configuration></pre></div> + <include file="src/main/java/chapter3/includedConfig.xml"/> - The target file must have its elements nested inside an - included element. For example, a - <code>ConsoleAppender</code> would be declared this way: + <root level="DEBUG"> + <appender-ref ref="includedConsole" /> + </root> + +</configuration></pre></div> + + The target file MUST have its elements nested inside an + <code><included></code> element. For example, a + <code>ConsoleAppender</code> could be declared as: 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"> + <div class="source"><pre><included> + <appender name="includedConsole" class="ch.qos.logback.core.ConsoleAppender"> <layout class="ch.qos.logback.classic.PatternLayout"> - <param name="Pattern" value="%d - %m%n" /> + <Pattern>"%d - %m%n"</Pattern> </layout> </appender> +</included></pre></div> - <root> - <level value="DEBUG" /> - <appender-ref ref="redirectConsole" /> - </root> - -</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. - - - - <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. - - - 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. - - - The examples for this chapter can be found under - LOGBACK_HOME/logback-examples/src/main/java/chapter3. - - - 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. - - - 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. - - - <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. - - - 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. - - - - <h2>Actions</h2> - - Actions extend the - <code>ch.qos.logback.core.joran.action.Action</code> class which - consists of the following abstract methods. + The file to be included can be referenced as a file, as a URL or + as a resource. To reference a file use the file attribute. To reference a URL use the url attribute. To reference a resource, use the + resource attribute. -<div class="source"><pre>package ch.qos.logback.core.joran.action; - -import org.xml.sax.Attributes; -import ch.qos.logback.core.joran.spi.ExecutionContext; - -public abstract class Action { - - - /** - * Called when the parser first encounters an element. - */ - public abstract void begin(ExecutionContext ec, - String name, - Attributes attributes); - - /** - * Called when the parser encounters the element end. At - * this stage, we can assume that child elements, if any, - * have been processed. - */ - public abstract void end(ExecutionContext ec, String name); -}</pre></div> - - Thus, every action must implement the begin and end methods. - - - <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. - - - 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> - - 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: - - - <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. - - - 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. - - - <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.: Calculator configuration file - (logback-examples/src/main/java/chapter3/calculator/calculator3.xml) - -<div class="source"><pre><computation name="toto"> - <computation> - <literal value="7"/> - <literal value="3"/> - <add/> - </computation> - - <literal value="3"/> - <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: - - 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) - -<div class="source"><pre><computation name="toto"> - <new-rule pattern="*/computation/literal" - actionClass="chapter3.calculator.LiteralAction"/> - <new-rule pattern="*/computation/add" - actionClass="chapter3.calculator.AddAction"/> - <new-rule pattern="*/computation/multiply" - actionClass="chapter3.calculator.MultiplyAction"/> - - <computation> - <literal value="7"/> - <literal value="3"/> - <add/> - </computation> - - <literal value="3"/> - <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. - - - 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. - - - Both <code>ImplicitAction</code> and - <code>NestedComponentIA</code> are located in the - <code>ch.qos.logback.core.joran.action</code> package. - - - Refer to the - logback-examples/src/main/java/joran/implicit directory for - an example of an implicit action. - - - In that directory, you will find two actions classes, one xml - file and one class containing the setup of Joran. - - 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: - - Example 3.: Usage of implicit rules - (logback-examples/src/main/java/chapter3/implicit/implicit1.xml) -<div class="source"><pre><foo> - - <xyz printme="true"> - <abc printme="true"/> - </xyz> - - <xyz/> - - <foo printme="true"/> - -</foo></pre></div> - - 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>. - - 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. - - <h3>Non goals</h3> - - The Joran API is not intended to be used to parse documents with - thousands of elements. - - - - -

1 0