[LOGBack-dev] svn commit: r593 - logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic
noreply.seb at qos.ch
noreply.seb at qos.ch
Tue Sep 19 15:36:32 CEST 2006
Author: seb
Date: Tue Sep 19 15:36:32 2006
New Revision: 593
Modified:
logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/PatternLayout.java
Log:
- improved javadoc
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 Tue Sep 19 15:36:32 2006
@@ -34,90 +34,412 @@
import ch.qos.logback.core.pattern.PatternLayoutBase;
/**
+ * <p>
+ * A flexible layout configurable with pattern string. The goal of this class is
+ * to {@link #format format} a {@link LoggingEvent} and return the results in a
+ * {#link String}. The format of the result depends on the
+ * <em>conversion pattern</em>.
+ * <p>
+ *
+ * <p>
+ * The conversion pattern is closely related to the conversion pattern of the
+ * printf function in C. A conversion pattern is composed of literal text and
+ * format control expressions called <em>conversion specifiers</em>.
+ *
+ * <p>
+ * <i>Note that you are free to insert any literal text within the conversion
+ * pattern.</i>
+ * </p>
+ *
+ * <p>
+ * Each conversion specifier starts with a percent sign (%) and is followed by
+ * optional <em>format modifiers</em> and a <em>conversion character</em> or
+ * <em>conversion word</em>. The conversion character or word specifies the
+ * type of data, e.g. logger, level, date, thread name. The format modifiers
+ * control such things as field width, padding, left and right justification.
+ * The following is a simple example.
+ *
+ * <p>
+ * Let the conversion pattern be <b>"%-5level [%thread]: %message%n"</b> and
+ * assume that the logback environment was set to use a PatternLayout. Then the
+ * statements
+ *
+ * <pre>
+ * Logger logger = LoggerFactory.getLogger("root");
+ * root.debug("Message 1");
+ * root.warn("Message 2");
+ * </pre>
+ *
+ * would yield the output
+ *
+ * <pre>
+ * DEBUG [main]: Message 1
+ * WARN [main]: Message 2
+ * </pre>
+ *
+ * <p>
+ * Note that there is no explicit separator between text and conversion
+ * specifiers. The pattern parser knows when it has reached the end of a
+ * conversion specifier when it reads a conversion character. In the example
+ * above the conversion specifier <b>%-5level</b> means the level of the
+ * logging event should be left justified to a width of five characters.
+ *
+ * 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>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>
+ * 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.
*
- * 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>
+ * 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.
+ *
+ * </td>
+ * </tr>
+ *
+ * <tr>
+ * <td align=center><b>C / class</b></td>
+ *
+ * <td>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>
+ * 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>
+ * For example, for the class name "org.apache.xyz.SomeClass", the pattern
+ * <b>%class{1}</b> will output "SomeClass". See more examples of name
+ * abbreviations further down this document.
+ *
+ * <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.
+ *
+ * </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>Used to output the file name where the logging request was issued.
+ *
+ * <p>
+ * <b>WARNING</b> Generating caller file information is extremely slow. Its use
+ * should be avoided unless execution speed is not an issue.
+ *
+ * </tr>
+ *
+ * <tr>
+ * <td align=center><b>caller</b></td>
+ *
+ * <td>Used to output location information of the caller which generated the
+ * logging event.
+ *
+ * <p>
+ * The location information depends on the JVM implementation but usually
+ * consists of the fully qualified name of the calling method followed by the
+ * callers source the file name and line number between parentheses.
+ *
+ * <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.
+ *
+ * </td>
+ * </tr>
+ *
+ * <tr>
+ * <td align=center><b>L / line</b></td>
+ *
+ * <td>Used to output the line number from where the logging request was
+ * issued.
+ *
+ * <p>
+ * <b>WARNING</b> Generating caller location information is extremely slow.
+ * It's use should be avoided unless execution speed is not an issue.
+ *
+ * </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>Used to output the method name where the logging request was issued.
+ *
+ * <p>
+ * <b>WARNING</b> Generating caller location information is extremely slow.
+ * It's use should be avoided unless execution speed is not an issue.
+ *
+ * </tr>
+ *
+ * <tr>
+ * <td align=center><b>n</b></td>
+ *
+ * <td>Outputs the platform dependent line separator character or characters.
+ *
+ * <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.
+ *
+ *
+ * </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 {@link MDC} 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>
+ * The optional format modifier is placed between the percent sign and the
+ * conversion character or word.
+ *
+ * <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>
+ * 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>
+ * Below are various format modifier examples for the logger conversion
+ * specifier.
+ *
+ * <p>
+ * <TABLE BORDER=1 CELLPADDING=8>
+ * <th>Format modifier
+ * <th>Left justify
+ * <th>Minimum width
+ * <th>Maximum width
+ * <th>Comment
+ *
+ * <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.
+ *
+ * <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.
+ *
+ * <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.
+ *
+ * <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.
+ *
+ * <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.
+ *
* </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>
+ * Below are some examples of conversion patterns.
+ *
+ * <dl>
+ *
+ * <p>
+ * <dt><b>%relative [%thread] %-5level %logger %mdc - %message\n</b>
+ * <p>
+ * <dd>This is essentially the TTCC layout.
+ *
+ * <p>
+ * <dt><b>%-6relative [%15.15thread] %-5level %30.30logger %mdc - %message\n</b>
+ *
+ * <p>
+ * <dd>Similar to the TTCC layout except that the relative time is right padded
+ * if less than 6 digits, thread name is right padded if less than 15 characters
+ * and truncated if longer and the logger name is left padded if shorter than 30
+ * characters and truncated if longer.
+ *
+ * </dl>
+ * <p> Here are a few more examples of the format modifier behaviour, with emphasis on
+ * the way it affects class names.
+ * <p>
+ *
+ * <table BORDER=1 CELLPADDING=8>
+ *
+ * <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>
+ *
+ * <p>
+ * The above text is largely inspired from Peter A. Darnell and Philip E.
+ * Margolis' highly recommended book "C -- a Software Engineering Approach",
+ * ISBN 0-387-97389-3.
+ *
*
*/
+
public class PatternLayout extends PatternLayoutBase implements ClassicLayout {
// FIXME fix exception handling
@@ -135,14 +457,14 @@
defaultConverterMap.put("level", LevelConverter.class.getName());
defaultConverterMap.put("le", LevelConverter.class.getName());
defaultConverterMap.put("p", LevelConverter.class.getName());
-
+
defaultConverterMap.put("t", ThreadConverter.class.getName());
defaultConverterMap.put("thread", ThreadConverter.class.getName());
defaultConverterMap.put("lo", LoggerConverter.class.getName());
defaultConverterMap.put("logger", LoggerConverter.class.getName());
defaultConverterMap.put("c", LoggerConverter.class.getName());
-
+
defaultConverterMap.put("m", MessageConverter.class.getName());
defaultConverterMap.put("msg", MessageConverter.class.getName());
defaultConverterMap.put("message", MessageConverter.class.getName());
@@ -158,10 +480,10 @@
defaultConverterMap.put("F", FileOfCallerConverter.class.getName());
defaultConverterMap.put("file", FileOfCallerConverter.class.getName());
-
+
defaultConverterMap.put("X", MDCConverter.class.getName());
defaultConverterMap.put("mdc", MDCConverter.class.getName());
-
+
defaultConverterMap
.put("ex", ThrowableInformationConverter.class.getName());
defaultConverterMap.put("exception", ThrowableInformationConverter.class
More information about the logback-dev
mailing list