Author: seb Date: Wed Oct 11 17:26:04 2006 New Revision: 666 Added: logback/trunk/logback-classic/examples/src/chapter5/ logback/trunk/logback-classic/examples/src/chapter5/PatternSample.java logback/trunk/logback-site/src/site/xdocTemplates/layouts.xml Modified: logback/trunk/ (props changed) logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/PatternLayout.java logback/trunk/logback-classic/src/main/java/org/slf4j/LoggerFactory.java logback/trunk/logback-site/src/site/xdocTemplates/accessLogJetty.xml logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml logback/trunk/logback-site/src/site/xdocTemplates/joran.xml Log: - corrected javadoc in PatternLayout.java - supressed call to system.out in LoggerFactory - added keyword option in accessLogJetty.xml - added link to layouts.xml in documentation.xml - added a first working copy of layouts.xml Added: logback/trunk/logback-classic/examples/src/chapter5/PatternSample.java ============================================================================== --- (empty file) +++ logback/trunk/logback-classic/examples/src/chapter5/PatternSample.java Wed Oct 11 17:26:04 2006 @@ -0,0 +1,28 @@ +package chapter5; + +import org.slf4j.LoggerFactory; + +import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.PatternLayout; +import ch.qos.logback.core.ConsoleAppender; + +public class PatternSample { + + static public void main(String[] args) throws Exception { + Logger rootLogger = (Logger) LoggerFactory.getLogger("root"); + + PatternLayout layout = new PatternLayout(); + layout.setPattern("%-5level [%thread]: %message%n"); + layout.start(); + + ConsoleAppender appender = new ConsoleAppender(); + appender.setContext(rootLogger.getLoggerContext()); + appender.setLayout(layout); + appender.start(); + + rootLogger.addAppender(appender); + + rootLogger.debug("Message 1"); + rootLogger.warn("Message 2"); + } +} \ No newline at end of file Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/PatternLayout.java ============================================================================== --- logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/PatternLayout.java (original) +++ logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/PatternLayout.java Wed Oct 11 17:26:04 2006 @@ -104,7 +104,7 @@ * logger name is printed in full. * * <p> - * For example, for the category name "a.b.c" the pattern <b>%logger{2}</b> + * For example, for the logger name "a.b.c" the pattern <b>%logger{2}</b> * will output "b.c". See more examples of name abbreviations further down this * document. * @@ -124,7 +124,7 @@ * name is output in fully qualified form. * * <p> - * For example, for the class name "org.apache.xyz.SomeClass", the pattern + * For example, for the class name "ch.logback.xyz.SomeClass", the pattern * <b>%class{1}</b> will output "SomeClass". See more examples of name * abbreviations further down this document. * @@ -153,7 +153,7 @@ * <p> * <b>WARNING</b> Generating caller file information is extremely slow. Its use * should be avoided unless execution speed is not an issue. - * + * </td> * </tr> * * <tr> @@ -184,7 +184,7 @@ * <p> * <b>WARNING</b> Generating caller location information is extremely slow. * It's use should be avoided unless execution speed is not an issue. - * + * </td> * </tr> * * @@ -202,7 +202,7 @@ * <p> * <b>WARNING</b> Generating caller location information is extremely slow. * It's use should be avoided unless execution speed is not an issue. - * + * </td> * </tr> * * <tr> @@ -215,7 +215,7 @@ * non-portable line separator strings such as "\n", or "\r\n". Thus, it is the * preferred way of specifying a line separator. * - * + * </td> * </tr> * * <tr> @@ -394,7 +394,7 @@ * characters and truncated if longer. * * </dl> - * <p> Here are a few more examples of the format modifier behaviour, with emphasis on + * <p> Here are a few more examples of the precision specifier behaviour, with emphasis on * the way it affects class names. * <p> * Modified: logback/trunk/logback-classic/src/main/java/org/slf4j/LoggerFactory.java ============================================================================== --- logback/trunk/logback-classic/src/main/java/org/slf4j/LoggerFactory.java (original) +++ logback/trunk/logback-classic/src/main/java/org/slf4j/LoggerFactory.java Wed Oct 11 17:26:04 2006 @@ -71,7 +71,6 @@ try { loggerFactory = StaticLoggerBinder.SINGLETON.getLoggerFactory(); URL url = Loader.getResource("logback-classic.xml"); - System.out.println("URL = " + url); if (url != null) { JoranConfigurator configurator = new JoranConfigurator(); configurator.setContext((Context)loggerFactory); Modified: logback/trunk/logback-site/src/site/xdocTemplates/accessLogJetty.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/accessLogJetty.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/accessLogJetty.xml Wed Oct 11 17:26:04 2006 @@ -303,17 +303,16 @@ </tr> <tr> - <td align="center"><b>reqParameter</b></td> + <td align="center"><b>reqParameter{paramName}</b></td> <td> <p> Parameter of the response. This conversion word can be followed by a key whose corresponding data will be extracted from the header information. </p> - <p>Example: <em>%reqParameter{userName}</em></p> </td> </tr> <tr> - <td align="center"><b>i / header</b></td> + <td align="center"><b>i{header} / header{header}</b></td> <td> <p> Request header. Just like the reqParameter @@ -386,7 +385,7 @@ </td> </tr> <tr> - <td align="center"><b>reqAttribute</b></td> + <td align="center"><b>reqAttribute{attributeName}</b></td> <td> <p> Attribute of the request. Just like the reqParameter @@ -395,7 +394,7 @@ </td> </tr> <tr> - <td align="center"><b>reqCookie</b></td> + <td align="center"><b>reqCookie{cookie}</b></td> <td> <p> Request cookie. Just like the reqParameter @@ -404,7 +403,7 @@ </td> </tr> <tr> - <td align="center"><b>responseHeader</b></td> + <td align="center"><b>responseHeader{header}</b></td> <td> <p> Header of the response. Just like the reqParameter Modified: logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml Wed Oct 11 17:26:04 2006 @@ -17,12 +17,15 @@ <li> <a href="shortIntro.html"><b>A short introduction to logback-classic</b></a> </li> - <li> <a href="accessLogJetty.html"><b>A short introduction to access logging with logback-access and Jetty</b></a> </li> <li> + <a href="layouts.html"><b>Layout reference</b></a> + </li> + + <li> <a href="apidocs/index.html"><b>Javadoc</b></a> </li> Modified: logback/trunk/logback-site/src/site/xdocTemplates/joran.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/joran.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/joran.xml Wed Oct 11 17:26:04 2006 @@ -21,7 +21,7 @@ </p> <p>Joran is actually a generic configuration system which can be used -independently of logging. To emphaises this point, I should mention +independently of logging. To emphaises this point, We should mention that the logback-core module does not have a notion of loggers. In that sprit, many of the examples related to this tutorial, have nothing to do with loggers, appenders or layouts. @@ -188,7 +188,7 @@ <!-- Pretty dirty, thanks site-generation... --> <p>It creates a <code>RuleStore</code> and a <code>Context</code></p> <p>It adds the <em>hello-world</em> pattern, with it's corresponding action</p> - <p>It creates a Joran interpreted, and passes the <code>RuleStore</code></p> + <p>It creates a Joran interpreter, and passes the <code>RuleStore</code></p> <p>It creates a SAX parser and parses the given file, specifying the newly created Joran interpreter as the <code>ContentHandler</code></p> </ul> Added: logback/trunk/logback-site/src/site/xdocTemplates/layouts.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-site/src/site/xdocTemplates/layouts.xml Wed Oct 11 17:26:04 2006 @@ -0,0 +1,614 @@ +<document> + <!-- + + Warning: do not use any auto-format function on this file. + Since "source" divs use pre as white-space, it affects the + look of the code parts in this document. + + --> + + + <body> + <h2>Layouts</h2> + <div class="author"> + Authors: Ceki Gülcü, Sébastien Pennec + </div> + + + <table> + <tr> + <td valign="top" align="top"> + <a rel="license" + href="http://creativecommons.org/licenses/by-nc-nd/2.5/"> + <img alt="Creative Commons License" border="0" + valign="top" align="top" + src="http://creativecommons.org/images/public/somerights20.png" /> + </a> + </td> + <td> + <p>Copyright © 2000-2006, QOS.ch</p> + + <p> + This work is licensed under a + <a rel="license" + href="http://creativecommons.org/licenses/by-nc-nd/2.5/"> + Creative Commons + Attribution-Noncommercial-No Derivative + Works 2.5 License + </a> + . + </p> + </td> + </tr> + </table> + + <h2>What is a layout</h2> + + <p> + While appenders are responsible for writing logging output + to an appender dependent device, layouts are responsible for + the format of the output. In case you were wondering, + lay-outs have nothing to do with large estates in Florida. + The + <code>format()</code> + method in the Layout class takes in a object that represents + the logging event and returns a String. A synopsis of the + Layout interface is shown below. + </p> + <div class="source"> + public interface Layout extends ContextAware, LifeCycle { + + String doLayout(Object event); + + String getHeader(); + + String getFooter(); + + String getContentType(); + </div> + <p> + This interface is really simple and yet is sufficent for + many formatting needs. + </p> + + <!-- Do we add here something about one's personal implementation of Layout? --> + + <h2>Logback classic</h2> + + <p> + As we've seen, a Layout implementation takes as a parameter + an object that represents a logging event. The typing of the + parameter to <code>Object</code> + is because logging events may have different way of being + designed. In logback classic, a logging event is represented + by the <code>ch.qos.logback.classic.LoggingEvent</code> + class. Therefore, all layouts in logback classic implement a + sub-interface of <code>Layout</code> named <code>ClassicLayout</code>. + </p> + + <p> + Here is what a + <code>ClassicLayout</code> + looks like: + </p> + + <div class="source"> + public interface ClassicLayout extends Layout { + + String doLayout(LoggingEvent event); + + } + </div> + + <h3>PatternLayout</h3> + + <p> + Logback ships with a flexible layout called <code>PatternLayout</code>. + As all layouts, <code>PatternLayout</code> + takes in a logging event and returns a String. However, the + returned String can be modified at will by tweaking its + conversion pattern. + </p> + <p> + The conversion pattern of <code>PatternLayout</code> + is closely related to the conversion pattern of the + <code>printf()</code> function in the C programming language. + A conversion pattern is composed of literal text and format + control expressions called conversion specifiers. + You are free to insert any literal text within the conversion pattern. + Each conversion specifier starts with a percent sign (%) and is followed by + optional format modifiers and a conversion character. The + conversion character controls the type of data to use, e.g. + logger name, level, date, thread name. The format modifiers + control such things as field width, padding, and left or + right justification. The following is a simple example. + </p> +<em>Example 5.1: Sample usage of a PatternLayout (examples/chapter5/PatternSample.java)</em> +<div class="source">public class PatternSample { + + static public void main(String[] args) throws Exception { + Logger rootLogger = (Logger) LoggerFactory.getLogger("root"); + + <b>PatternLayout layout = new PatternLayout(); + layout.setPattern("%-5level [%thread]: %message%n"); + layout.start();</b> + + ConsoleAppender appender = new ConsoleAppender(); + appender.setContext(rootLogger.getLoggerContext()); + appender.setLayout(layout); + appender.start(); + + rootLogger.addAppender(appender); + + rootLogger.debug("Message 1"); + rootLogger.warn("Message 2"); + } +}</div> + + <p> + The conversion pattern is set to be "%-5level [%thread]: %message%n". + Running PatternSample will yield the following output on the console. + </p> +<div class="source">DEBUG [main]: Message 1 +WARN [main]: Message 2</div> + <p> + Note that in the conversion pattern "%-5level [%thread]: %message%n" + there is no explicit separator between literal text and conversion + specifiers. When parsing a conversion pattern, <code>PatternLayout</code> + is capable of differentiating between literal text (space characters, the brackets, + colon character) and conversion specifiers. In the example above, + the conversion specifier %-5level means the level of the logging event + should be left justified to a width of five characters. + Format specifiers will be explained in a short moment. + </p> + <p> + The recognized conversion characters and words are + </p> + <table border="1" CELLPADDING="8"> + <th>Conversion Character or Word</th> + <th>Effect</th> + + <tr> + <td align="center"> + <b>c / l / lo / logger</b> + </td> + + <td> + <p> + Used to output the logger of the logging event. + The logger conversion specifier can be + optionally followed by + <em>precision specifier</em> + , that is a decimal constant in brackets. + </p> + <p> + If a precision specifier is given, then only the + corresponding number of right most components of + the logger name will be printed. By default the + logger name is printed in full. + </p> + <p> + For example, for the category name "a.b.c" the + pattern + <b>%logger{2}</b> + will output "b.c". See more examples of name + abbreviations further down this document. + </p> + </td> + </tr> + + <tr> + <td align="center"> + <b>C / class</b> + </td> + + <td> + <p> + Used to output the fully qualified class name of + the caller issuing the logging request. This + conversion specifier can be optionally followed + by + <em>precision specifier</em> + , that is a decimal constant in brackets. + </p> + <p> + If a precision specifier is given, then only the + corresponding number of right most components of + the class name will be printed. By default the + class name is output in fully qualified form. + </p> + <p> + For example, for the class name + "ch.logback.xyz.SomeClass", the pattern + <b>%class{1}</b> + will output "SomeClass". See more examples of + name abbreviations further down this document. + </p> + <p> + <b>WARNING</b> + Generating the caller class information is slow. + Thus, it's use should be avoided unless + execution speed is not an issue. + </p> + </td> + </tr> + + <tr> + <td align="center"> + <b>d / date</b> + </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 + {@link java.text.SimpleDateFormat}, + <em>ABSOLUTE</em> + , + <em>DATE</em> + or + <em>ISO8601</em> + . For example, + <b>%d{HH:mm:ss,SSS}</b> + , + <b>%d{dd MMM yyyy ;HH:mm:ss,SSS}</b> + or + <b>%d{DATE}</b> + . If no date format specifier is given then ISO8601 + format is assumed. + </td> + </tr> + + <tr> + <td align="center"> + <b>F / file</b> + </td> + + <td> + <p> + Used to output the file name where the logging + request was issued. + </p> + <p> + <b>WARNING</b> + Generating caller file information is extremely + slow. Its use should be avoided unless execution + speed is not an issue. + </p> + </td> + </tr> + + <tr> + <td align="center"> + <b>caller</b> + </td> + + <td> + <p> + Used to output location information of the + caller which generated the logging event. + </p> + <p> + The location information depends on the JVM + implementation but usually consists of the fully + qualified name of the calling method followed by + the caller's source the file name and line + number between parentheses. + </p> + <p> + The location information can be very useful. + However, it's generation is + <em>extremely</em> + slow. It's use should be avoided unless + execution speed is not an issue. + </p> + </td> + </tr> + + <tr> + <td align="center"> + <b>L / line</b> + </td> + + <td> + <p> + Used to output the line number from where the + logging request was issued. + </p> + <p> + <b>WARNING</b> + Generating caller location information is + extremely slow. It's use should be avoided + unless execution speed is not an issue. + </p> + </td> + </tr> + + + <tr> + <td align="center"> + <b>m / msg / message</b> + </td> + <td> + Used to output the application supplied message + associated with the logging event. + </td> + </tr> + + <tr> + <td align="center"> + <b>M / method</b> + </td> + + <td> + <p> + Used to output the method name where the logging + request was issued. + </p> + <p> + <b>WARNING</b> + Generating caller location information is + extremely slow. It's use should be avoided + unless execution speed is not an issue. + </p> + </td> + </tr> + + <tr> + <td align="center"> + <b>n</b> + </td> + + <td> + <p> + Outputs the platform dependent line separator + character or characters. + </p> + <p> + This conversion character offers practically the + same performance as using non-portable line + separator strings such as "\n", or "\r\n". Thus, + it is the preferred way of specifying a line + separator. + </p> + </td> + + </tr> + + <tr> + <td align="center"> + <b>p / le / level</b> + </td> + <td>Used to output the level of the logging event.</td> + </tr> + + <tr> + + <td align="center"> + <b>r / relative</b> + </td> + + <td> + Used to output the number of milliseconds elapsed + since the start of the application until the + creation of the logging event. + </td> + </tr> + + + <tr> + <td align="center"> + <b>t / thread</b> + </td> + + <td> + Used to output the name of the thread that generated + the logging event. + </td> + + </tr> + + <tr> + <td align="center"> + <b>X</b> + </td> + + <td> + + <p> + Used to output the MDC (mapped diagnostic + context) associated with the thread that + generated the logging event. The + <b>X</b> + conversion character can be followed by the key + for the map placed between braces, as in + <b>%X{clientNumber}</b> + where + <code>clientNumber</code> + is the key. The value in the MDC corresponding + to the key will be output. If no additional + sub-option is specified, then the entire + contents of the MDC key value pair set is output + using a format key1=val1, key2=val2 + </p> + + <p> + See + <a + href="http://logback.qos.ch/apidocs/ch/qos/logback/classic/MDC.html"> + MDC + </a> + class for more details. + </p> + + </td> + </tr> + <tr> + <td align="center"> + <b>throwable</b> + </td> + + <td> + <p> + Used to output the Throwable trace that has been + bound to the LoggingEvent, by default this will + output the full trace as one would normally find + by a call to Throwable.printStackTrace(). The + throwable conversion word can be followed by an + option in the form + <b>%throwable{short}</b> + which will only output the first line of the + ThrowableInformation. + </p> + </td> + </tr> + + <tr> + + <td align="center"> + <b>%</b> + </td> + + <td>The sequence %% outputs a single percent sign.</td> + </tr> + + </table> + <p> + By default the relevant information is output as is. + However, with the aid of format modifiers it is possible to + change the minimum field width, the maximum field width and + justification. + </p> + <p> + The optional format modifier is placed between the percent + sign and the conversion character or word. + </p> + <p> + The first optional format modifier is the + <em>left justification flag</em> + which is just the minus (-) character. Then comes the + optional + <em>minimum field width</em> + modifier. This is a decimal constant that represents the + minimum number of characters to output. If the data item + requires fewer characters, it is padded on either the left + or the right until the minimum width is reached. The default + is to pad on the left (right justify) but you can specify + right padding with the left justification flag. The padding + character is space. If the data item is larger than the + minimum field width, the field is expanded to accommodate + the data. The value is never truncated. + </p> + <p> + This behavior can be changed using the + <em>maximum field width</em> + modifier which is designated by a period followed by a + decimal constant. If the data item is longer than the + maximum field, then the extra characters are removed from + the + <em>beginning</em> + of the data item and not from the end. For example, it the + maximum field width is eight and the data item is ten + characters long, then the first two characters of the data + item are dropped. This behavior deviates from the printf + function in C where truncation is done from the end. + </p> + <p> + Below are various format modifier examples for the logger + conversion specifier. + </p> + + <table BORDER="1" CELLPADDING="8"> + <th>Format modifier</th> + <th>Left justify</th> + <th>Minimum width</th> + <th>Maximum width</th> + <th>Comment</th> + + <tr> + <td align="center">%20c</td> + <td align="center">false</td> + <td align="center">20</td> + <td align="center">none</td> + <td> + Left pad with spaces if the category name is less + than 20 characters long. + </td> + </tr> + <tr> + <td align="center">%-20c</td> + <td align="center">true</td> + <td align="center">20</td> + <td align="center">none</td> + <td> + Right pad with spaces if the logger name is less + than 20 characters long. + </td> + </tr> + <tr> + <td align="center">%.30c</td> + <td align="center">NA</td> + <td align="center">none</td> + <td align="center">30</td> + <td> + Truncate from the beginning if the logger name is + longer than 30 characters. + </td> + </tr> + <tr> + <td align="center">%20.30c</td> + <td align="center">false</td> + <td align="center">20</td> + <td align="center">30</td> + <td> + Left pad with spaces if the logger name is shorter + than 20 characters. However, if logger name is + longer than 30 characters, then truncate from the + beginning. + </td> + </tr> + <tr> + <td align="center">%-20.30c</td> + <td align="center">true</td> + <td align="center">20</td> + <td align="center">30</td> + <td> + Right pad with spaces if the logger name is shorter + than 20 characters. However, if logger name is + longer than 30 characters, then truncate from the + beginning. + </td> + </tr> + </table> + + + + + + + + + + + + + + + + + <h3>HTMLLayout</h3> + + <em> + Example 1.1: Basic template for logging + (examples/chapter1/HelloWorld1.java) + </em> + + + + + + <h2>Logback access</h2> + <h3>PatternLayout</h3> + <h3>HTMLLayout</h3> + +</body> +</document>