001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 * 
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 * 
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.log4j;
019
020import org.apache.log4j.spi.LoggingEvent;
021import org.apache.log4j.helpers.PatternParser;
022import org.apache.log4j.helpers.PatternConverter;
023
024
025// Contributors:   Nelson Minar <nelson@monkey.org>
026//                 Anders Kristensen <akristensen@dynamicsoft.com>
027
028/**
029
030   A flexible layout configurable with pattern string.
031   
032   This code is known to have synchronization and other issues
033   which are not present in org.apache.log4j.EnhancedPatternLayout.
034   EnhancedPatternLayout should be used in preference to PatternLayout.
035   EnhancedPatternLayout is distributed in the log4j extras companion.
036
037   <p>The goal of this class is to {@link #format format} a {@link
038   LoggingEvent} and return the results as a String. The results
039   depend on the <em>conversion pattern</em>.
040
041   <p>The conversion pattern is closely related to the conversion
042   pattern of the printf function in C. A conversion pattern is
043   composed of literal text and format control expressions called
044   <em>conversion specifiers</em>.
045
046   <p><i>You are free to insert any literal text within the conversion
047   pattern.</i>
048
049   <p>Each conversion specifier starts with a percent sign (%) and is
050   followed by optional <em>format modifiers</em> and a <em>conversion
051   character</em>. The conversion character specifies the type of
052   data, e.g. category, priority, date, thread name. The format
053   modifiers control such things as field width, padding, left and
054   right justification. The following is a simple example.
055
056   <p>Let the conversion pattern be <b>"%-5p [%t]: %m%n"</b> and assume
057   that the log4j environment was set to use a PatternLayout. Then the
058   statements
059   <pre>
060   Category root = Category.getRoot();
061   root.debug("Message 1");
062   root.warn("Message 2");
063   </pre>
064   would yield the output
065   <pre>
066   DEBUG [main]: Message 1
067   WARN  [main]: Message 2
068   </pre>
069
070   <p>Note that there is no explicit separator between text and
071   conversion specifiers. The pattern parser knows when it has reached
072   the end of a conversion specifier when it reads a conversion
073   character. In the example above the conversion specifier
074   <b>%-5p</b> means the priority of the logging event should be left
075   justified to a width of five characters.
076
077   The recognized conversion characters are
078
079   <p>
080   <table border="1" CELLPADDING="8">
081   <th>Conversion Character</th>
082   <th>Effect</th>
083
084   <tr>
085     <td align=center><b>c</b></td>
086
087     <td>Used to output the category of the logging event. The
088     category conversion specifier can be optionally followed by
089     <em>precision specifier</em>, that is a decimal constant in
090     brackets.
091
092     <p>If a precision specifier is given, then only the corresponding
093     number of right most components of the category name will be
094     printed. By default the category name is printed in full.
095
096     <p>For example, for the category name "a.b.c" the pattern
097     <b>%c{2}</b> will output "b.c".
098
099     </td>
100   </tr>
101
102   <tr>
103     <td align=center><b>C</b></td>
104
105     <td>Used to output the fully qualified class name of the caller
106     issuing the logging request. This conversion specifier
107     can be optionally followed by <em>precision specifier</em>, that
108     is a decimal constant in brackets.
109
110     <p>If a precision specifier is given, then only the corresponding
111     number of right most components of the class name will be
112     printed. By default the class name is output in fully qualified form.
113
114     <p>For example, for the class name "org.apache.xyz.SomeClass", the
115     pattern <b>%C{1}</b> will output "SomeClass".
116
117     <p><b>WARNING</b> Generating the caller class information is
118     slow. Thus, use should be avoided unless execution speed is
119     not an issue.
120
121     </td>
122     </tr>
123
124   <tr> <td align=center><b>d</b></td> <td>Used to output the date of
125         the logging event. The date conversion specifier may be
126         followed by a <em>date format specifier</em> enclosed between
127         braces. For example, <b>%d{HH:mm:ss,SSS}</b> or
128         <b>%d{dd&nbsp;MMM&nbsp;yyyy&nbsp;HH:mm:ss,SSS}</b>.  If no
129         date format specifier is given then ISO8601 format is
130         assumed.
131
132         <p>The date format specifier admits the same syntax as the
133         time pattern string of the {@link
134         java.text.SimpleDateFormat}. Although part of the standard
135         JDK, the performance of <code>SimpleDateFormat</code> is
136         quite poor.
137
138         <p>For better results it is recommended to use the log4j date
139         formatters. These can be specified using one of the strings
140         "ABSOLUTE", "DATE" and "ISO8601" for specifying {@link
141         org.apache.log4j.helpers.AbsoluteTimeDateFormat
142         AbsoluteTimeDateFormat}, {@link
143         org.apache.log4j.helpers.DateTimeDateFormat DateTimeDateFormat}
144         and respectively {@link
145         org.apache.log4j.helpers.ISO8601DateFormat
146         ISO8601DateFormat}. For example, <b>%d{ISO8601}</b> or
147         <b>%d{ABSOLUTE}</b>.
148
149         <p>These dedicated date formatters perform significantly
150         better than {@link java.text.SimpleDateFormat}.
151     </td>
152   </tr>
153
154   <tr>
155   <td align=center><b>F</b></td>
156
157   <td>Used to output the file name where the logging request was
158   issued.
159
160   <p><b>WARNING</b> Generating caller location information is
161   extremely slow and should be avoided unless execution speed
162   is not an issue.
163
164   </tr>
165
166   <tr>
167   <td align=center><b>l</b></td>
168
169     <td>Used to output location information of the caller which generated
170     the logging event.
171
172     <p>The location information depends on the JVM implementation but
173     usually consists of the fully qualified name of the calling
174     method followed by the callers source the file name and line
175     number between parentheses.
176
177     <p>The location information can be very useful. However, its
178     generation is <em>extremely</em> slow and should be avoided
179     unless execution speed is not an issue.
180
181     </td>
182   </tr>
183
184   <tr>
185   <td align=center><b>L</b></td>
186
187   <td>Used to output the line number from where the logging request
188   was issued.
189
190   <p><b>WARNING</b> Generating caller location information is
191   extremely slow and should be avoided unless execution speed
192   is not an issue.
193
194   </tr>
195
196
197   <tr>
198     <td align=center><b>m</b></td>
199     <td>Used to output the application supplied message associated with
200     the logging event.</td>
201   </tr>
202
203   <tr>
204   <td align=center><b>M</b></td>
205
206   <td>Used to output the method name where the logging request was
207   issued.
208
209   <p><b>WARNING</b> Generating caller location information is
210   extremely slow and should be avoided unless execution speed
211   is not an issue.
212
213   </tr>
214
215   <tr>
216     <td align=center><b>n</b></td>
217
218     <td>Outputs the platform dependent line separator character or
219     characters.
220
221     <p>This conversion character offers practically the same
222     performance as using non-portable line separator strings such as
223     "\n", or "\r\n". Thus, it is the preferred way of specifying a
224     line separator.
225
226
227   </tr>
228
229   <tr>
230     <td align=center><b>p</b></td>
231     <td>Used to output the priority of the logging event.</td>
232   </tr>
233
234   <tr>
235
236     <td align=center><b>r</b></td>
237
238     <td>Used to output the number of milliseconds elapsed from the construction 
239     of the layout until the creation of the logging event.</td>
240   </tr>
241
242
243   <tr>
244     <td align=center><b>t</b></td>
245
246     <td>Used to output the name of the thread that generated the
247     logging event.</td>
248
249   </tr>
250
251   <tr>
252
253     <td align=center><b>x</b></td>
254
255     <td>Used to output the NDC (nested diagnostic context) associated
256     with the thread that generated the logging event.
257     </td>
258   </tr>
259
260
261   <tr>
262     <td align=center><b>X</b></td>
263
264     <td> 
265     
266     <p>Used to output the MDC (mapped diagnostic context) associated
267     with the thread that generated the logging event. The <b>X</b>
268     conversion character <em>must</em> be followed by the key for the
269     map placed between braces, as in <b>%X{clientNumber}</b> where
270     <code>clientNumber</code> is the key. The value in the MDC
271     corresponding to the key will be output.</p>
272     
273     <p>See {@link MDC} class for more details.
274     </p>
275     
276     </td>
277   </tr>
278
279   <tr>
280
281     <td align=center><b>%</b></td>
282
283     <td>The sequence %% outputs a single percent sign.
284     </td>
285   </tr>
286
287   </table>
288
289   <p>By default the relevant information is output as is. However,
290   with the aid of format modifiers it is possible to change the
291   minimum field width, the maximum field width and justification.
292
293   <p>The optional format modifier is placed between the percent sign
294   and the conversion character.
295
296   <p>The first optional format modifier is the <em>left justification
297   flag</em> which is just the minus (-) character. Then comes the
298   optional <em>minimum field width</em> modifier. This is a decimal
299   constant that represents the minimum number of characters to
300   output. If the data item requires fewer characters, it is padded on
301   either the left or the right until the minimum width is
302   reached. The default is to pad on the left (right justify) but you
303   can specify right padding with the left justification flag. The
304   padding character is space. If the data item is larger than the
305   minimum field width, the field is expanded to accommodate the
306   data. The value is never truncated.
307
308   <p>This behavior can be changed using the <em>maximum field
309   width</em> modifier which is designated by a period followed by a
310   decimal constant. If the data item is longer than the maximum
311   field, then the extra characters are removed from the
312   <em>beginning</em> of the data item and not from the end. For
313   example, it the maximum field width is eight and the data item is
314   ten characters long, then the first two characters of the data item
315   are dropped. This behavior deviates from the printf function in C
316   where truncation is done from the end.
317
318   <p>Below are various format modifier examples for the category
319   conversion specifier.
320
321   <p>
322   <TABLE BORDER=1 CELLPADDING=8>
323   <th>Format modifier
324   <th>left justify
325   <th>minimum width
326   <th>maximum width
327   <th>comment
328
329   <tr>
330   <td align=center>%20c</td>
331   <td align=center>false</td>
332   <td align=center>20</td>
333   <td align=center>none</td>
334
335   <td>Left pad with spaces if the category name is less than 20
336   characters long.
337
338   <tr> <td align=center>%-20c</td> <td align=center>true</td> <td
339   align=center>20</td> <td align=center>none</td> <td>Right pad with
340   spaces if the category name is less than 20 characters long.
341
342   <tr>
343   <td align=center>%.30c</td>
344   <td align=center>NA</td>
345   <td align=center>none</td>
346   <td align=center>30</td>
347
348   <td>Truncate from the beginning if the category name is longer than 30
349   characters.
350
351   <tr>
352   <td align=center>%20.30c</td>
353   <td align=center>false</td>
354   <td align=center>20</td>
355   <td align=center>30</td>
356
357   <td>Left pad with spaces if the category name is shorter than 20
358   characters. However, if category name is longer than 30 characters,
359   then truncate from the beginning.
360
361   <tr>
362   <td align=center>%-20.30c</td>
363   <td align=center>true</td>
364   <td align=center>20</td>
365   <td align=center>30</td>
366
367   <td>Right pad with spaces if the category name is shorter than 20
368   characters. However, if category name is longer than 30 characters,
369   then truncate from the beginning.
370
371   </table>
372
373   <p>Below are some examples of conversion patterns.
374
375   <dl>
376
377   <p><dt><b>%r [%t] %-5p %c %x - %m%n</b>
378   <p><dd>This is essentially the TTCC layout.
379
380   <p><dt><b>%-6r [%15.15t] %-5p %30.30c %x - %m%n</b>
381
382   <p><dd>Similar to the TTCC layout except that the relative time is
383   right padded if less than 6 digits, thread name is right padded if
384   less than 15 characters and truncated if longer and the category
385   name is left padded if shorter than 30 characters and truncated if
386   longer.
387
388  </dl>
389
390   <p>The above text is largely inspired from Peter A. Darnell and
391   Philip E. Margolis' highly recommended book "C -- a Software
392   Engineering Approach", ISBN 0-387-97389-3.
393
394   @author <a href="mailto:cakalijp@Maritz.com">James P. Cakalic</a>
395   @author Ceki G&uuml;lc&uuml;
396
397
398   @since 0.8.2 */
399public class PatternLayout extends Layout {
400
401
402  /** Default pattern string for log output. Currently set to the
403      string <b>"%m%n"</b> which just prints the application supplied
404      message. */
405  public final static String DEFAULT_CONVERSION_PATTERN ="%m%n";
406
407  /** A conversion pattern equivalent to the TTCCCLayout.
408      Current value is <b>%r [%t] %p %c %x - %m%n</b>. */
409  public final static String TTCC_CONVERSION_PATTERN
410                                             = "%r [%t] %p %c %x - %m%n";
411
412
413  protected final int BUF_SIZE = 256;
414  protected final int MAX_CAPACITY = 1024;
415
416
417  // output buffer appended to when format() is invoked
418  private StringBuffer sbuf = new StringBuffer(BUF_SIZE);
419
420  private String pattern;
421
422  private PatternConverter head;
423
424  /**
425     Constructs a PatternLayout using the DEFAULT_LAYOUT_PATTERN.
426
427     The default pattern just produces the application supplied message.
428  */
429  public PatternLayout() {
430    this(DEFAULT_CONVERSION_PATTERN);
431  }
432
433  /**
434     Constructs a PatternLayout using the supplied conversion pattern.
435  */
436  public PatternLayout(String pattern) {
437    this.pattern = pattern;
438    head = createPatternParser((pattern == null) ? DEFAULT_CONVERSION_PATTERN :
439                             pattern).parse();
440  }
441
442   /**
443     Set the <b>ConversionPattern</b> option. This is the string which
444     controls formatting and consists of a mix of literal content and
445     conversion specifiers.
446   */
447  public
448  void setConversionPattern(String conversionPattern) {
449    pattern = conversionPattern;
450    head = createPatternParser(conversionPattern).parse();
451  }
452
453  /**
454     Returns the value of the <b>ConversionPattern</b> option.
455   */
456  public
457  String getConversionPattern() {
458    return pattern;
459  }
460
461  /**
462     Does not do anything as options become effective
463  */
464  public
465  void activateOptions() {
466    // nothing to do.
467  }
468
469 /**
470     The PatternLayout does not handle the throwable contained within
471     {@link LoggingEvent LoggingEvents}. Thus, it returns
472     <code>true</code>.
473
474     @since 0.8.4 */
475  public
476  boolean ignoresThrowable() {
477    return true;
478  }
479
480  /**
481    Returns PatternParser used to parse the conversion string. Subclasses
482    may override this to return a subclass of PatternParser which recognize
483    custom conversion characters.
484
485    @since 0.9.0
486  */
487  protected PatternParser createPatternParser(String pattern) {
488    return new PatternParser(pattern);
489  }
490
491
492  /**
493     Produces a formatted string as specified by the conversion pattern.
494  */
495  public String format(LoggingEvent event) {
496    // Reset working stringbuffer
497    if(sbuf.capacity() > MAX_CAPACITY) {
498      sbuf = new StringBuffer(BUF_SIZE);
499    } else {
500      sbuf.setLength(0);
501    }
502
503    PatternConverter c = head;
504
505    while(c != null) {
506      c.format(sbuf, event);
507      c = c.next;
508    }
509    return sbuf.toString();
510  }
511}