1 // Module: Log4CPLUS
2 // File: Layout.h
3 // Created: 6/2001
4 // Author: Tad E. Smith
5 //
6 //
7 // Copyright (C) Tad E. Smith All rights reserved.
8 //
9 // This software is published under the terms of the Apache Software
10 // License version 1.1, a copy of which has been included with this
11 // distribution in the LICENSE.APL file.
12 //
13
14 /** @file */
15
16 #ifndef _LOG4CPLUS_LAYOUT_HEADER_
17 #define _LOG4CPLUS_LAYOUT_HEADER_
18
19 #include <log4cplus/config.h>
20 #include <log4cplus/loglevel.h>
21 #include <log4cplus/streams.h>
22 #include <log4cplus/tstring.h>
23 #include <log4cplus/helpers/logloguser.h>
24 #include <log4cplus/helpers/property.h>
25 #include <log4cplus/helpers/timehelper.h>
26 #include <log4cplus/spi/loggingevent.h>
27
28 #include <vector>
29
30
31 namespace log4cplus {
32
33 // Forward Declarations
34 namespace pattern {
35 class PatternConverter;
36 }
37
38
39 /**
40 * This class is used to layout strings sent to an {@link
41 * #Appender}.
42 */
43 class LOG4CPLUS_EXPORT Layout : protected :: log4cplus::helpers::LogLogUser {
44 public:
45 Layout() : llmCache(getLogLevelManager()) {}
46 Layout(const log4cplus::helpers::Properties&)
47 : llmCache(getLogLevelManager()) {}
48 virtual ~Layout() {}
49
50 virtual void formatAndAppend(log4cplus::tostream& output,
51 const log4cplus::spi::InternalLoggingEvent& event) = 0;
52 protected:
53 LogLevelManager& llmCache;
54
55 private:
56 // Disable copy
57 Layout(const Layout&);
58 Layout& operator=(Layout&);
59 };
60
61
62
63 /**
64 * SimpleLayout consists of the LogLevel of the log statement,
65 * followed by " - " and then the log message itself. For example,
66 *
67 * <pre>
68 * DEBUG - Hello world
69 * </pre>
70 *
71 * <p>
72 *
73 * <p>{@link PatternLayout} offers a much more powerful alternative.
74 */
75 class LOG4CPLUS_EXPORT SimpleLayout : public Layout {
76 public:
77 SimpleLayout() {}
78 SimpleLayout(const log4cplus::helpers::Properties& properties) : Layout(properties) {}
79
80 virtual void formatAndAppend(log4cplus::tostream& output,
81 const log4cplus::spi::InternalLoggingEvent& event);
82
83 private:
84 // Disallow copying of instances of this class
85 SimpleLayout(const SimpleLayout&);
86 SimpleLayout& operator=(const SimpleLayout&);
87 };
88
89
90
91 /**
92 * TTCC layout format consists of time, thread, Logger and nested
93 * diagnostic context information, hence the name.
94 *
95 * <p>The time format depends on the <code>DateFormat</code> used. Use the
96 * <code>Use_gmtime</code> to specify whether messages should be logged using
97 * <code>localtime</code> or <code>gmtime</code>.
98 *
99 * <p>Here is an example TTCCLayout output with the {@link RelativeTimeDateFormat}.
100 *
101 * <pre>
102 * 176 [main] INFO org.apache.log4j.examples.Sort - Populating an array of 2 elements in reverse order.
103 * 225 [main] INFO org.apache.log4j.examples.SortAlgo - Entered the sort method.
104 * 262 [main] DEBUG org.apache.log4j.examples.SortAlgo.OUTER i=1 - Outer loop.
105 * 276 [main] DEBUG org.apache.log4j.examples.SortAlgo.SWAP i=1 j=0 - Swapping intArray[0] = 1 and intArray[1] = 0
106 * 290 [main] DEBUG org.apache.log4j.examples.SortAlgo.OUTER i=0 - Outer loop.
107 * 304 [main] INFO org.apache.log4j.examples.SortAlgo.DUMP - Dump of interger array:
108 * 317 [main] INFO org.apache.log4j.examples.SortAlgo.DUMP - Element [0] = 0
109 * 331 [main] INFO org.apache.log4j.examples.SortAlgo.DUMP - Element [1] = 1
110 * 343 [main] INFO org.apache.log4j.examples.Sort - The next log statement should be an error message.
111 * 346 [main] ERROR org.apache.log4j.examples.SortAlgo.DUMP - Tried to dump an uninitialized array.
112 * 467 [main] INFO org.apache.log4j.examples.Sort - Exiting main method.
113 * </pre>
114 *
115 * <p>The first field is the number of milliseconds elapsed since the
116 * start of the program. The second field is the thread outputting the
117 * log statement. The third field is the LogLevel, the fourth field is
118 * the logger to which the statement belongs.
119 *
120 * <p>The fifth field (just before the '-') is the nested diagnostic
121 * context. Note the nested diagnostic context may be empty as in the
122 * first two statements. The text after the '-' is the message of the
123 * statement.
124 *
125 * <p>PatternLayout offers a much more flexible alternative.
126 */
127 class LOG4CPLUS_EXPORT TTCCLayout : public Layout {
128 public:
129 // Ctor and dtor
130 TTCCLayout(bool use_gmtime = false);
131 TTCCLayout(const log4cplus::helpers::Properties& properties);
132 virtual ~TTCCLayout();
133
134 virtual void formatAndAppend(log4cplus::tostream& output,
135 const log4cplus::spi::InternalLoggingEvent& event);
136
137 protected:
138 log4cplus::tstring dateFormat;
139 bool use_gmtime;
140
141 private:
142 // Disallow copying of instances of this class
143 TTCCLayout(const TTCCLayout&);
144 TTCCLayout& operator=(const TTCCLayout&);
145 };
146
147
148
149
150 /**
151 * A flexible layout configurable with pattern string.
152 *
153 * <p>The goal of this class is to format a InternalLoggingEvent and return
154 * the results as a string. The results depend on the <em>conversion
155 * pattern</em>.
156 *
157 * <p>The conversion pattern is closely related to the conversion
158 * pattern of the printf function in C. A conversion pattern is
159 * composed of literal text and format control expressions called
160 * <em>conversion specifiers</em>.
161 *
162 * <p><i>You are free to insert any literal text within the conversion
163 * pattern.</i>
164 *
165 * <p>Each conversion specifier starts with a percent sign (%%) and is
166 * followed by optional <em>format modifiers</em> and a <em>conversion
167 * character</em>. The conversion character specifies the type of
168 * data, e.g. Logger, LogLevel, date, thread name. The format
169 * modifiers control such things as field width, padding, left and
170 * right justification. The following is a simple example.
171 *
172 * <p>Let the conversion pattern be <b>"%-5p [%t]: %m%n"</b> and assume
173 * that the log4cplus environment was set to use a PatternLayout. Then the
174 * statements
175 * <pre>
176 * Logger root = Logger.getRoot();
177 * LOG4CPLUS_DEBUG(root, "Message 1");
178 * LOG4CPLUS_WARN(root, "Message 2");
179 * </pre>
180 * would yield the output
181 * <pre>
182 * DEBUG [main]: Message 1
183 * WARN [main]: Message 2
184 * </pre>
185 *
186 * <p>Note that there is no explicit separator between text and
187 * conversion specifiers. The pattern parser knows when it has reached
188 * the end of a conversion specifier when it reads a conversion
189 * character. In the example above the conversion specifier
190 * <b>"%-5p"</b> means the LogLevel of the logging event should be left
191 * justified to a width of five characters.
192 *
193 * The recognized conversion characters are
194 *
195 * <p>
196 * <table border="1" CELLPADDING="8">
197 * <tr>
198 * <td>Conversion Character</td>
199 * <td>Effect</td>
200 * </tr>
201 *
202 * <tr>
203 * <td align=center><b>c</b></td>
204 *
205 * <td>Used to output the logger of the logging event. The
206 * logger conversion specifier can be optionally followed by
207 * <em>precision specifier</em>, that is a decimal constant in
208 * brackets.
209 *
210 * <p>If a precision specifier is given, then only the corresponding
211 * number of right most components of the logger name will be
212 * printed. By default the logger name is printed in full.
213 *
214 * <p>For example, for the logger name "a.b.c" the pattern
215 * <b>%c{2}</b> will output "b.c".
216 *
217 * </td>
218 * </tr>
219 *
220 * <tr>
221 * <td align=center><b>d</b></td>
222 *
223 * <td>Used to output the date of the logging event in <b>localtime</b>.
224 *
225 * <p>The date conversion specifier may be followed by a <em>date format
226 * specifier</em> enclosed between braces. For example, <b>%%d{%%H:%%M:%%s}</b>
227 * or <b>%%d{%%d %%b %%Y %%H:%%M:%%s}</b>. If no date format
228 * specifier is given then <b>%%d{%%d %%m %%Y %%H:%%M:%%s}</b>
229 * is assumed.
230 *
231 * <p>The Following format options are possible:
232 * <ul>
233 * <li>%%a -- Abbreviated weekday name</li>
234 * <li>%%A -- Full weekday name</li>
235 * <li>%%b -- Abbreviated month name</li>
236 * <li>%%B -- Full month name</li>
237 * <li>%%c -- Standard date and time string</li>
238 * <li>%%d -- Day of month as a decimal(1-31)</li>
239 * <li>%%H -- Hour(0-23)</li>
240 * <li>%%I -- Hour(1-12)</li>
241 * <li>%%j -- Day of year as a decimal(1-366)</li>
242 * <li>%%m -- Month as decimal(1-12)</li>
243 * <li>%%M -- Minute as decimal(0-59)</li>
244 * <li>%%p -- Locale's equivalent of AM or PM</li>
245 * <li>%%q -- milliseconds as decimal(0-999) -- <b>Log4CPLUS specific</b>
246 * <li>%%Q -- fractional milliseconds as decimal(0-999.999) -- <b>Log4CPLUS specific</b>
247 * <li>%%S -- Second as decimal(0-59)</li>
248 * <li>%%U -- Week of year, Sunday being first day(0-53)</li>
249 * <li>%%w -- Weekday as a decimal(0-6, Sunday being 0)</li>
250 * <li>%%W -- Week of year, Monday being first day(0-53)</li>
251 * <li>%%x -- Standard date string</li>
252 * <li>%%X -- Standard time string</li>
253 * <li>%%y -- Year in decimal without century(0-99)</li>
254 * <li>%%Y -- Year including century as decimal</li>
255 * <li>%%Z -- Time zone name</li>
256 * <li>%% -- The percent sign</li>
257 * </ul>
258 *
259 * <p>Lookup the documentation for the <code>strftime()</code> function
260 * found in the <code><ctime></code> header for more information.
261 * </td>
262 * </tr>
263 *
264 * <tr>
265 * <td align=center><b>D</b></td>
266 *
267 * <td>Used to output the date of the logging event in <b>Local</b> time.
268 *
269 * <p>All of the above information applies.
270 * </td>
271 * </tr>
272 *
273 * <tr>
274 * <td align=center><b>F</b></td>
275 *
276 * <td>Used to output the file name where the logging request was
277 * issued.
278 *
279 * <p><b>NOTE</b> Unlike log4j, there is no performance penalty for
280 * calling this method.
281 *
282 * </tr>
283 *
284 * <tr>
285 * <td align=center><b>l</b></td>
286 *
287 * <td>Equivalent to using "%F:%L"
288 *
289 * <p><b>NOTE:</b> Unlike log4j, there is no performance penalty for
290 * calling this method.
291 *
292 * </td>
293 * </tr>
294 *
295 * <tr>
296 * <td align=center><b>L</b></td>
297 *
298 * <td>Used to output the line number from where the logging request
299 * was issued.
300 *
301 * <p><b>NOTE:</b> Unlike log4j, there is no performance penalty for
302 * calling this method.
303 *
304 * </tr>
305 *
306 *
307 * <tr>
308 * <td align=center><b>m</b></td>
309 * <td>Used to output the application supplied message associated with
310 * the logging event.</td>
311 * </tr>
312 *
313 * <tr>
314 * <td align=center><b>n</b></td>
315 *
316 * <td>Outputs the platform dependent line separator character or
317 * characters.
318 * </tr>
319 *
320 * <tr>
321 * <td align=center><b>p</b></td>
322 * <td>Used to output the LogLevel of the logging event.</td>
323 * </tr>
324 *
325 * <tr>
326 * <td align=center><b>t</b></td>
327 *
328 * <td>Used to output the name of the thread that generated the
329 * logging event.</td>
330 * </tr>
331 *
332 * <tr>
333 *
334 * <td align=center><b>x</b></td>
335 *
336 * <td>Used to output the NDC (nested diagnostic context) associated
337 * with the thread that generated the logging event.
338 * </td>
339 * </tr>
340 *
341 * <tr>
342 * <td align=center><b>"%%"</b></td>
343 * <td>The sequence "%%" outputs a single percent sign.
344 * </td>
345 * </tr>
346 *
347 * </table>
348 *
349 * <p>By default the relevant information is output as is. However,
350 * with the aid of format modifiers it is possible to change the
351 * minimum field width, the maximum field width and justification.
352 *
353 * <p>The optional format modifier is placed between the percent sign
354 * and the conversion character.
355 *
356 * <p>The first optional format modifier is the <em>left justification
357 * flag</em> which is just the minus (-) character. Then comes the
358 * optional <em>minimum field width</em> modifier. This is a decimal
359 * constant that represents the minimum number of characters to
360 * output. If the data item requires fewer characters, it is padded on
361 * either the left or the right until the minimum width is
362 * reached. The default is to pad on the left (right justify) but you
363 * can specify right padding with the left justification flag. The
364 * padding character is space. If the data item is larger than the
365 * minimum field width, the field is expanded to accommodate the
366 * data. The value is never truncated.
367 *
368 * <p>This behavior can be changed using the <em>maximum field
369 * width</em> modifier which is designated by a period followed by a
370 * decimal constant. If the data item is longer than the maximum
371 * field, then the extra characters are removed from the
372 * <em>beginning</em> of the data item and not from the end. For
373 * example, it the maximum field width is eight and the data item is
374 * ten characters long, then the first two characters of the data item
375 * are dropped. This behavior deviates from the printf function in C
376 * where truncation is done from the end.
377 *
378 * <p>Below are various format modifier examples for the logger
379 * conversion specifier.
380 *
381 * <p>
382 * <TABLE BORDER=1 CELLPADDING=8>
383 * <tr>
384 * <td>Format modifier</td>
385 * <td>left justify</td>
386 * <td>minimum width</td>
387 * <td>maximum width</td>
388 * <td>comment</td>
389 * </tr>
390 *
391 * <tr>
392 * <td align=center>%20c</td>
393 * <td align=center>false</td>
394 * <td align=center>20</td>
395 * <td align=center>none</td>
396 *
397 * <td>Left pad with spaces if the logger name is less than 20
398 * characters long.
399 * </tr>
400 *
401 * <tr> <td align=center>%-20c</td> <td align=center>true</td> <td
402 * align=center>20</td> <td align=center>none</td> <td>Right pad with
403 * spaces if the logger name is less than 20 characters long.
404 * </tr>
405 *
406 * <tr>
407 * <td align=center>%.30c</td>
408 * <td align=center>NA</td>
409 * <td align=center>none</td>
410 * <td align=center>30</td>
411 *
412 * <td>Truncate from the beginning if the logger name is longer than 30
413 * characters.
414 * </tr>
415 *
416 * <tr>
417 * <td align=center>%20.30c</td>
418 * <td align=center>false</td>
419 * <td align=center>20</td>
420 * <td align=center>30</td>
421 *
422 * <td>Left pad with spaces if the logger name is shorter than 20
423 * characters. However, if logger name is longer than 30 characters,
424 * then truncate from the beginning.
425 * </tr>
426 *
427 * <tr>
428 * <td align=center>%-20.30c</td>
429 * <td align=center>true</td>
430 * <td align=center>20</td>
431 * <td align=center>30</td>
432 *
433 * <td>Right pad with spaces if the logger name is shorter than 20
434 * characters. However, if logger name is longer than 30 characters,
435 * then truncate from the beginning.
436 * </tr>
437 *
438 * </table>
439 *
440 * <p>Below are some examples of conversion patterns.
441 *
442 * <dl>
443 *
444 * <p><dt><b>"%r [%t] %-5p %c %x - %m%n"</b>
445 * <p><dd>This is essentially the TTCC layout.
446 *
447 * <p><dt><b>"%-6r [%15.15t] %-5p %30.30c %x - %m%n"</b>
448 *
449 * <p><dd>Similar to the TTCC layout except that the relative time is
450 * right padded if less than 6 digits, thread name is right padded if
451 * less than 15 characters and truncated if longer and the logger
452 * name is left padded if shorter than 30 characters and truncated if
453 * longer.
454 *
455 * </dl>
456 *
457 * <p>The above text is largely inspired from Peter A. Darnell and
458 * Philip E. Margolis' highly recommended book "C -- a Software
459 * Engineering Approach", ISBN 0-387-97389-3.
460 */
461 class LOG4CPLUS_EXPORT PatternLayout : public Layout {
462 public:
463 // Ctors and dtor
464 PatternLayout(const log4cplus::tstring& pattern);
465 PatternLayout(const log4cplus::helpers::Properties& properties);
466 virtual ~PatternLayout();
467
468 virtual void formatAndAppend(log4cplus::tostream& output,
469 const log4cplus::spi::InternalLoggingEvent& event);
470
471 protected:
472 void init(const log4cplus::tstring& pattern);
473
474 // Data
475 log4cplus::tstring pattern;
476 std::vector<pattern::PatternConverter*> parsedPattern;
477
478 private:
479 // Disallow copying of instances of this class
480 PatternLayout(const PatternLayout&);
481 PatternLayout& operator=(const PatternLayout&);
482 };
483
484
485
486 } // end namespace log4cplus
487
488 #endif // _LOG4CPLUS_LAYOUT_HEADER_
syntax highlighted by Code2HTML, v. 0.9.1