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