Author: seb Date: Wed Oct 25 11:34:32 2006 New Revision: 769 Modified: logback/trunk/logback-classic/examples/src/chapter5/MySampleLayout2.java logback/trunk/logback-classic/examples/src/chapter5/sampleLayoutConfig2.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml Log: updated docs Modified: logback/trunk/logback-classic/examples/src/chapter5/MySampleLayout2.java ============================================================================== --- logback/trunk/logback-classic/examples/src/chapter5/MySampleLayout2.java (original) +++ logback/trunk/logback-classic/examples/src/chapter5/MySampleLayout2.java Wed Oct 25 11:34:32 2006 @@ -13,8 +13,8 @@ this.prefix = prefix; } - public void setPrintThreadName(String printThreadName) { - this.printThreadName = printThreadName.equals("true"); + public void setPrintThreadName(boolean printThreadName) { + this.printThreadName = printThreadName; } public String doLayout(LoggingEvent event) { Modified: logback/trunk/logback-classic/examples/src/chapter5/sampleLayoutConfig2.xml ============================================================================== --- logback/trunk/logback-classic/examples/src/chapter5/sampleLayoutConfig2.xml (original) +++ logback/trunk/logback-classic/examples/src/chapter5/sampleLayoutConfig2.xml Wed Oct 25 11:34:32 2006 @@ -3,7 +3,7 @@ <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <layout class="chapter5.MySampleLayout2"> - <prefix>MyContext</prefix> + <prefix>MyPrefix</prefix> <printThreadName>false</printThreadName> </layout> </appender> Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml Wed Oct 25 11:34:32 2006 @@ -81,13 +81,10 @@ <p> Logback classic only processes events of type <code>ch.qos.logback.classic.LoggingEvent</code>. - Therefore, classic extends <code>Layout</code> - to accept only <code>LoggingEvent</code> objects. - </p> - - <p> - The extending interface is called - <code>ClassicLayout</code>, as shown below. + Therefore, logback classic module imposes that + all its layouts implement + the <code>ClassicLayout</code> interface that is + shown below. </p> <div class="source"><pre>public interface ClassicLayout extends Layout { @@ -132,7 +129,7 @@ sbuf.append(LINE_SEP); return sbuf.toString(); } - + //method declared in ch.qos.logback.core.Layout interface public String doLayout(Object event) { return doLayout((LoggingEvent)event); } @@ -153,7 +150,7 @@ interface, since it is intented to be used with the classic module. Therefore, it offers a trivial implementation of the <code>doLayout(Object event)</code> method, that only casts the event - in the right type and passes it to the method where the actual formatting + to the right type and passes it to the method where the actual formatting takes place.</p> <p>The marginally more interesting <code>doLayout(LoggingEvent event)</code> @@ -164,7 +161,7 @@ build the message in its proper form. </p> <p> - In the previous listing of the <code>Layout</code> class, + In the above listing of the <code>Layout</code> class, we had omitted the class static <code>LINE_SEP</code> field which is simply assigned the value returned by <code>System.getProperty("line.separator")</code> @@ -173,9 +170,9 @@ a String. </p> <p> - The format method ignores any eventual exceptions contained - in the event, leaving the task of handling throwables to the - containing appender. + The <code>doLayout</code> method ignores any eventual exceptions contained + in the event. In a real world layout implementation, you would probably not want + to silently ignore exceptions. </p> <p>Custom layouts are configured as any other layout, as shown below:</p> @@ -213,7 +210,88 @@ The reader shall find a slightly modified version of our custom layout in <code>MySampleLayout2.java</code>. She will discover that adding an option to a layout is as simple as declaring a setter method for the option. - See also <em>chapter5/sampleLayoutConfig2.xml</em> for a configuration example.</p> + </p> + <p> + The + <code>MySampleLayout2</code> + class contains two attributes. The first one is a prefix that + can be added to the output. The second attribute is used to + choose wether to display the name of the thread from which + the logging request was sent. + </p> + <p>Here is the implementation of this class:</p> +<div class="source"><pre>package chapter5; + +import ch.qos.logback.classic.ClassicLayout; +import ch.qos.logback.classic.spi.LoggingEvent; +import ch.qos.logback.core.LayoutBase; + +public class MySampleLayout2 extends LayoutBase implements ClassicLayout { + + String prefix = null; + boolean printThreadName = true; + + <b>public void setPrefix(String prefix) { + this.prefix = prefix; + } + + public void setPrintThreadName(boolean printThreadName) { + this.printThreadName = printThreadName; + }</b> + + public String doLayout(LoggingEvent event) { + StringBuffer sbuf = new StringBuffer(128); + <b>if (prefix != null) { + sbuf.append(prefix + ": "); + }</b> + sbuf.append(event.getTimeStamp() - LoggingEvent.getStartTime()); + sbuf.append(" "); + sbuf.append(event.getLevel()); + <b>if (printThreadName) { + sbuf.append(" ["); + sbuf.append(event.getThreadName()); + sbuf.append("] "); + } else { + sbuf.append(" "); + }</b> + sbuf.append(event.getLoggerRemoteView().getName()); + sbuf.append(" - "); + sbuf.append(event.getFormattedMessage()); + sbuf.append(LINE_SEP); + return sbuf.toString(); + } + + public String doLayout(Object event) { + return doLayout((LoggingEvent) event); + } +}</pre></div> + + <p>Appart from the actual use of the two attributes, in the <code>doLayout</code> method, + the two setter methods are the only addition to the original class. Yet, it is sufficient + to allow the user to configure these attributes, as shown in the configuration file below:</p> + +<div class="source"><pre>%lt;configuration> + + %lt;appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + %lt;layout class="chapter5.MySampleLayout2"> + <b>%lt;prefix>MyPrefix%lt;/prefix> + %lt;printThreadName>false%lt;/printThreadName></b> + %lt;/layout> + %lt;/appender> + + %lt;root> + %lt;level value="debug" /> + %lt;appender-ref ref="STDOUT" /> + %lt;/root> +%lt;/configuration></pre></div> + + <p> + Note that the <code>PrintThreadName</code> attribute is a boolean + and not a <code>String</code>. It can be configured anyway by writing <em>true</em> + of <em>false</em> in the configuration file. + </p> + <a name="AccessPatternLayout" /> <h3>PatternLayout</h3> @@ -226,7 +304,7 @@ <code>PatternLayout</code> takes a logging event and returns a String. However, the - returned String can be modified at will by tweaking its + returned String can be customized at will by tweaking its conversion pattern. </p> <p> @@ -250,7 +328,15 @@ Example 5.1: Sample usage of a PatternLayout (examples/chapter5/PatternSample.java) </em> - <div class="source"><pre>public class PatternSample { + <div class="source"><pre>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) @@ -317,7 +403,8 @@ <td> <p> - Used to output the logger name of the logging event. + Used to output the name of the logger at the + source of the logging event. </p> <p> The logger name conversion word can take an @@ -326,7 +413,7 @@ without significant loss of meaning. </p> - <p>The next table should clear things up.</p> + <p>The next table should clarify the matter.</p> <table BORDER="1" CELLPADDING="8"> <tr> @@ -377,7 +464,7 @@ the caller issuing the logging request. </p> <p> - Just like the <em>logger</em> conversion word, this + Just like the <em>%logger</em> conversion word above, this word can take an interger as it's first option and use its abbreviation algorithm to shorten the class name. @@ -405,11 +492,11 @@ <p>The option admits the same syntax as the time pattern string of the <code>java.text.SimpleDateFormat</code>.</p> <p>A shortcut to the ISO8601 format is available by - specifying <em>ISO8601</em> in the braces. If no option is set, - the converter uses <em>ISO8601</em> as a default value.</p> + specifying the String <em>"ISO8601"</em> in the braces. If no option is set, + the converter uses <em>"ISO8601"</em> as the default value.</p> <p>Here are some sample option values. They assume that the actual date is Friday 20th of October, 2006 and that - the reader finished her meal a short while ago.</p> + the author finished his meal a short while ago.</p> <table BORDER="1" CELLPADDING="8"> <tr> @@ -456,7 +543,8 @@ <tr> <td align="center"> - <b>caller</b> + <b>caller{depth}</b> + <b>caller{depth, evaluator-1, ... evaluator-n}</b> </td> <td> @@ -493,9 +581,7 @@ against a given criteria before creating the output. For example, using <b>%caller{3, CALLER_DISPLAY_EVAL}</b> will display three lines of stacktrace, only if the evaluator called <em>CALLER_DISPLAY_EVAL</em> - returns a <b>positive</b> answer. - This behaviour is justified by the fact that displaying - caller data is rather expensive, and one should generally not want to display it. + returns a <b>positive</b> answer. </p> <p>Evaluators are described further down this document. @@ -646,6 +732,8 @@ <td align="center"> <b>ex</b>{<em>length</em>} <br /> <b>throwable</b>{<em>length</em>} <br /> + <b>ex{length, evaluator-1, ..., evaluator-n}</b> + <b>throwable{length, evaluator-1, ..., evaluator-n}</b> </td> <td> @@ -655,7 +743,7 @@ will be output. </p> <p>The <em>throwable</em> conversion word can followed by one of - the following options:$ + the following options: </p> <ul> <p><em>short</em>: prints the first line of the stack trace</p> @@ -702,9 +790,7 @@ against a given criteria before creating the output. For example, using <b>%ex{full, EX_DISPLAY_EVAL}</b> will display the full stacktrace of the exception, only if the evaluator called <em>EX_DISPLAY_EVAL</em> - returns a <b>negative</b> answer. This behaviour is justified by the fact that - throwable data is generally displayed unless the evaluator would - return a positive value. Evaluators are described + returns a <b>negative</b> answer. Evaluators are described further down this document. </p> </td> @@ -738,7 +824,7 @@ <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 + contains 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 @@ -829,7 +915,7 @@ 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. + <em>beginning</em>. </td> </tr> <tr> @@ -838,7 +924,7 @@ <td align="center">none</td> <td align="center">30</td> <td> - Truncate from the end if the logger name is + Truncate from the <em>end</em> if the logger name is longer than 30 characters. </td> </tr> @@ -882,9 +968,9 @@ example, the MDC conversion specifier: <em>%mdc{someKey}</em>. </p> - <p>A conversion specifier might use more that one options. For example, + <p>A conversion specifier might have more than one options. For example, a conversion specifier that uses evaluators, which we will cover very soon, - simply adds the evaluator names to the options list, as shown above</p> + simply adds the evaluator names to the option list, as shown below:</p> <div class="source"><pre> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> @@ -899,22 +985,21 @@ <h4>Evaluators</h4> <p> - Another very useful way of adding options to a conversion + Another use case for adding options to a conversion specifier is when <code>PatternLayout</code> is used with - <code>EventEvaluators</code> - . + <code>EventEvaluator</code> objects. </p> <p> - <code>EventEvaluators</code> + <code>EventEvaluator</code> objects have the responsability to check wether a given event matches a given criteria. </p> <p> Let's look at an example using - <code>EventEvaluators</code> - . The following configuration file outputs the logging + <code>EventEvaluator</code> objects. + The following configuration file outputs the logging events to the console, displaying date, thread, level, message and caller data. </p> @@ -923,7 +1008,7 @@ expensive, this information will be displayed only when the logging request comes from a specific logger, and whose message contains a certain string. By doing that, we make - sure that only the most important logging requests will have + sure that only the specific logging requests will have their caller information generated and displayed, without penalizing application performance. </p> @@ -955,8 +1040,8 @@ </root> </configuration></pre></div> <p>Please note that the & value cannot be written like one would do in a java - class, because of XML format encoding.</p> - <p>Let's test this configuration with the following code.</p> + class, because of XML encoding rules.</p> + <p>Let us test this configuration with the following code.</p> <em> Example 5.2: Sample usage of EventEvaluators (examples/chapter5/EventEvaluatorExample.java) @@ -986,13 +1071,13 @@ } }</pre></div> <p> - This excerpt does nothing very fancy. Five logging requests + This excerpt does nothing too fancy. Five logging requests are issued, the third one being different from the others. </p> <p> When a logging request is sent, the corresponding logging - event will pass through the evaluation process. Here, - obviously, the third request will match the evaluation, + event will pass through the evaluation process. Here, + the third request will match the evaluation, causing its caller data to be displayed. </p> <p> @@ -1003,8 +1088,8 @@ <div class="source"><pre>0 [main] DEBUG - logging statement0 0 [main] DEBUG - logging statement1 0 [main] DEBUG - logging statement2 -0 [main] DEBUG - stacktrace logging statement3 Caller+0 \ - at chapter5.CallerEvaluatorExample.main(CallerEvaluatorExample.java:28) +0 [main] DEBUG - stacktrace logging statement3 +Caller+0 at chapter5.CallerEvaluatorExample.main(CallerEvaluatorExample.java:28) 0 [main] DEBUG - logging statement4</pre></div> @@ -1018,13 +1103,13 @@ <p><b>Important:</b> With the <em>caller</em> conversion specifier, the data is displayed when <em>the expression evaluates to <b>true</b>.</em></p> <p> - Let's look at a different situation. When exceptions are - added to a logging request, they are usually displayed. However, in some cases, - one might want some exceptions never to be displayed. - </p> - <p>The java code shown below is creating five log requests, each one - with an exception. However, we do not want request number 3 to display - its exception in the logging output.</p> + Let us look at a different situation. When exceptions are included in + a logging request, their stack trace is usually displayed. However, in some cases, + one might want to supress the stack trace of specific exception. + </p> + <p>The java code shown below creates five log requests, each one + with an exception. However, we do not want to have the stack trace of the + third request to be output.</p> <div class="source"><pre>public class ExceptionEvaluatorExample { @@ -1081,11 +1166,9 @@ <p> With this configuration, each time an instance of the <em>chapter5.TestException</em> - will be associated with a logging request containing an - exception, no information will be displayed about the - exception. + is included within a logging request, no stack trace will be displayed. </p> - <p><b>Important:</b> With the <em>ex</em> conversion specifier, the data is + <p><b>Important:</b> With the <b><em>%ex</em></b> conversion specifier, the data is displayed when <em>the expression evaluates to <b>false</b>.</em></p> <a name="ClassicHTMLLayout"/> @@ -1100,22 +1183,27 @@ <p> The content of the table columns are specified using a conversion pattern. See <code>PatternLayout</code> for documentation on - the available patterns. This ensure that the user has full access to the creation + the available patterns. This ensures that the user has full control over the creation of the html table. One can choose to display any (or all) data that <code>PatternLayout</code> can provide. </p> <p>One notable point about the use of <code>PatternLayout</code> with <code>HTMLLayout</code> - is that conversion specifiers should not be separated by a space. Each specifier found in the - pattern will result in a separate column, meaning that spaces will create empty columns.</p> + is that conversion specifiers should not be separated by a space or in general + any literals. Each specifier found in the + pattern will result in a separate column, meaning that each literal will create + an extra column.</p> <p> The pattern <em>%ex</em> used to display an Exception is not the only way to display an Exception with this layout. If you use this pattern, a table column will be created to display the potential - Exception's stacktrace. + Exception's stacktrace. That means that, in most cases, the column + will be empty, and will take quite a lot of space when displaying + an exception's stack trace. </p> <p> - However, a better solution is available in the form of + Since printing a stack trace on a separate column is not very readable, + a better solution is available in the form of implementations of the <code>IThrowableRenderer</code> interface. These implementations can be called and assigned to HTMLLayout to manage the display of anything related to @@ -1123,13 +1211,13 @@ </p> <p> By default, a <code>DefaultThrowableRenderer</code> is - assigned to the HTMLLayout. It writes the Exception on a new - table row, along with its stacktrace, in a easily readable - manner. + assigned to the HTMLLayout. It writes the Exception on a <em>new + table row</em>, along with its stacktrace, in a easily readable + manner, like presented in the picture above. </p> <p> If one wants to use the - <em>&ex</em> + <em>%ex</em> pattern anyway, then a <code>NOPThrowableRenderer</code> can be specified in the configuration file. </p> @@ -1148,21 +1236,19 @@ </layout></pre></div> <p> - The <code>HTMLLayout</code> is often used in conjunction with - <code>SMTPAppender</code>, to send a nicely formatted html email. Of - course, it can be used with any other Appender. + The <code>HTMLLayout</code> is often, although not necessarily used in conjunction with + <code>SMTPAppender</code>, to send a nicely formatted html email. </p> <p> When one wants to use the <code>HTMLLayout</code> with a <code>SMTPAppender</code>, - the following configuration is typically used. + the following configuration would be typical. </p> <div class="source"><pre><configuration> <appender name="SMTP" class="ch.qos.logback.classic.net.SMTPAppender"> <layout class="ch.qos.logback.classic.html.HTMLLayout"> <param name="pattern" value="%relative%thread%mdc%level%class%msg" /> </layout> - <throwableRenderer class="ch.qos.logback.classic.html.DefaultThrowableRenderer" /> <param name="From" value="sender.email@domain.net" /> <param name="SMTPHost" value="mail.domain.net" /> <param name="Subject" value="LastEvent: %class - %msg" /> @@ -1174,13 +1260,7 @@ <appender-ref ref="SMTP" /> </root> </configuration></pre></div> - <p> - In this configuration file, the - <em>throwableRenderer</em> - element specifies the default implementation of - IThrowableRenderer. It could be omitted, but is showed for - educationnal purposes. - </p> + <p>When <code>HTMLLayout</code> is used with any <code>FileAppender</code>, one can specify the html page's title, simply by adding an element to the configuration, as shown above:</p> @@ -1208,9 +1288,9 @@ </configuration></pre></div> <h2>Logback access</h2> - <p>Just like <code>ClassicLayout</code> represents the <code>Layout</code> interface - for the classic module, the <code>AccessLayout</code> exists for the access module. It's - implementation is very straight-forward.</p> + <p>Just like <code>ClassicLayout</code> restricts the possible <code>Layout</code> classes + for the classic module, the <code>AccessLayout</code> imposes a structure for <code>Layout</code> objects + in the access module. It is reproduced below.</p> <div class="source"><pre>public interface AccessLayout extends Layout { @@ -1218,14 +1298,14 @@ }</pre></div> - <p>Many access layouts are actually adaptations of classic layouts. Logback - modules classic and access address pretty different needs, but offer the same power - and flexibility to the user.</p> + <p>Many access layouts are mere adaptations of classic layouts. Logback + classic and access modules address different needs, but offer comparable power + and flexibility.</p> <h3>Writing your own Layout</h3> - <p>Writing a custom <code>Layout</code> for logback access works almost exactly the - same as writing such a component for the classic module.</p> - <p>The only exceptions comes from the fact that layouts in access module imlement + <p>Writing a custom <code>Layout</code> for logback access is nearly identical + as to writing a <code>Layout</code> for the classic module.</p> + <p>The only difference comes from the fact that access layouts must implement the <code>AccessLayout</code> interface instead <code>ClassicLayout</code>.</p> <a name="AccessPatternLayout" />