[LOGBack-dev] svn commit: r585 - logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic

[noreply.seb at qos.ch]

Author: seb
Date: Thu Sep 14 15:57:58 2006
New Revision: 585

Modified:
   logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/PatternLayout.java

Log:
Added javadoc:
- quick intro about PatternLayout and pattern conversion
- explanation of format modifier on classnames, with examples
- doc in progress 

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	Thu Sep 14 15:57:58 2006
@@ -33,7 +33,91 @@
 import ch.qos.logback.core.pattern.Converter;
 import ch.qos.logback.core.pattern.PatternLayoutBase;
 
-
+/**
+ * 
+ * PatternLayout is a simple yet powerfull way to turn a LoggingEvent into
+ * a String.
+ * <p>
+ * The returned String can be modified by specifying a pattern to the layout.
+ * A pattern is composed of literal text and format control expressions called
+ * conversion specifiers. Any literal can be inserted between the conversions
+ * specifiers. When literals are inserted, PatternLayout is able to differentiate
+ * which part of the pattern are conversion specifiers and which should be 
+ * added as-is to the output string.
+ * <p>
+ * A conversion specifier starts with a percent sign (%) and is followed by
+ * a letter or a word, describing the type of data that will be displayed.
+ * A format modifier can be added to the conversion specifier. It will tweak
+ * the way that the conversion specifier will display the data.
+ * <p>
+ * Here are a few quick examples:
+ * <p>
+ * <table cellpadding=10>
+ *   <tr>
+ *     <th>Conversion pattern</th>
+ *     <th>Result</th>
+ *     <th>Explanation</th>
+ *   </tr>
+ *   <tr>
+ *     <td>%level [%thread]: %message</td>
+ *     <td>DEBUG [main]: Message 1</td>
+ *     <td>Simple pattern</td>
+ *   </tr>
+ *   <tr>
+ *     <td>%level [%logger]: %message</td>
+ *     <td>DEBUG [org.foo.bar.SampleClass]: Message 2</td>   
+ *     <td>With <em>%logger</em>, the fully qualified name is displayed</td>
+ *   </tr>
+ *   <tr>
+ *     <td>%level [%logger{10}]: %message</td>
+ *     <td>DEBUG [o.f.b.SampleClass]: Message 2</td>  
+ *     <td>A format modifier has been added to the conversion specifier, thus
+ *     modifying the string displayed.</td> 
+ *   </tr>        
+ * </table>
+ * <p>
+ * When a conversion specifier is used in conjunction with a format modifier, 
+ * the resulting string is modified. It is modified in a way that one can still
+ * read the class name, and deduce its fully qualified name by looking at the
+ * packages' first letter.
+ * <p>
+ * The format modifier can have a milder effect on the resulting string. If a 
+ * larger number is specified, a longer part of the fully qualified name will be
+ * displayed without modification. In that case, the name of deeper packages 
+ * are displayed first.
+ * <p>
+ * Here are a few more examples of the format modifier behaviour.
+ * <p>
+ * <table cellpadding=10>
+ *   <tr>
+ *     <th>Conversion Pattern</th>
+ *     <th>Class name</th>
+ *     <th>Result</th>
+ *   </tr>
+ *   <tr>
+ *     <td>%logger{10}</td>
+ *     <td>mainPackage.sub.sample.Bar</td>
+ *     <td>m.s.s.Bar</td>
+ *   </tr>
+ *   <tr>
+ *     <td>%logger{15}</td>
+ *     <td>mainPackage.sub.sample.Bar</td>
+ *     <td>m.s.sample.Bar</td>
+ *   </tr>
+ *   <tr>
+ *     <td>%logger{16}</td>
+ *     <td>mainPackage.sub.sample.Bar</td>
+ *     <td>m.sub.sample.Bar</td>
+ *   </tr> 
+ *   <tr>
+ *     <td>%logger{26}</td>
+ *     <td>mainPackage.sub.sample.Bar</td>
+ *     <td>mainPackage.sub.sample.Bar</td>
+ *   </tr>
+ * </table>
+ *<p>
+ * 
+ */
 public class PatternLayout extends PatternLayoutBase implements ClassicLayout {
 
   // FIXME fix exception handling