410 lines
14 KiB
C++
410 lines
14 KiB
C++
/*
|
|
* Licensed to the Apache Software Foundation (ASF) under one or more
|
|
* contributor license agreements. See the NOTICE file distributed with
|
|
* this work for additional information regarding copyright ownership.
|
|
* The ASF licenses this file to You under the Apache License, Version 2.0
|
|
* (the "License"); you may not use this file except in compliance with
|
|
* the License. You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
#ifndef _LOG4CXX_PATTERN_LAYOUT_H
|
|
#define _LOG4CXX_PATTERN_LAYOUT_H
|
|
|
|
#if defined(_MSC_VER)
|
|
#pragma warning ( push )
|
|
#pragma warning ( disable: 4231 4251 4275 4786 )
|
|
#endif
|
|
|
|
|
|
|
|
#include <log4cxx/layout.h>
|
|
#include <log4cxx/pattern/loggingeventpatternconverter.h>
|
|
#include <log4cxx/pattern/formattinginfo.h>
|
|
#include <log4cxx/pattern/patternparser.h>
|
|
|
|
namespace log4cxx
|
|
{
|
|
|
|
/**
|
|
|
|
A flexible layout configurable with pattern string.
|
|
|
|
<p>The goal of this class is to #format a {@link
|
|
spi::LoggingEvent LoggingEvent} and return the results as a string.
|
|
The results depend on the <em>conversion pattern</em>.
|
|
|
|
<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>You are free to insert any literal text within the conversion
|
|
pattern.</i>
|
|
|
|
<p>Each conversion specifier starts with a percent sign (\%) and is
|
|
followed by optional <em>format modifiers</em> and a <em>conversion
|
|
character</em>. The conversion character 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>"\%-5p [\%t]: \%m\%n"</b> and assume
|
|
that the log4cxx environment was set to use a PatternLayout. Then the
|
|
statements
|
|
<pre>
|
|
LoggerPtr root = Logger::getRoot();
|
|
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>\%-5p</b> means the level of the logging event should be left
|
|
justified to a width of five characters.
|
|
|
|
The recognized conversion characters are
|
|
|
|
<p>
|
|
<table border="1" CELLPADDING="8">
|
|
<tr>
|
|
<td align=center><b>Conversion Character</b></td>
|
|
<td align=center><b>Effect</b></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align=center><b>c</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.
|
|
|
|
<p>For example, for the logger name "a.b.c" the pattern
|
|
<b>\%c{2}</b> will output "b.c".
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr> <td align=center><b>d</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 string compatible with 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</b></td>
|
|
|
|
<td>Used to output the file name where the logging request was
|
|
issued.
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align=center><b>l</b></td>
|
|
|
|
<td>Used to output location information of the caller which generated
|
|
the logging event.
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align=center><b>L</b></td>
|
|
|
|
<td>Used to output the line number from where the logging request
|
|
was issued.
|
|
</tr>
|
|
|
|
|
|
<tr>
|
|
<td align=center><b>m</b></td>
|
|
<td>Used to output the application supplied message associated with
|
|
the logging event.</td>
|
|
</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</b></td>
|
|
<td>Used to output the level of the logging event.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td align=center><b>r</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</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>Used to output the NDC (nested diagnostic context) associated
|
|
with 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 <em>must</em> 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.</p>
|
|
|
|
<p>See MDC class for more details.
|
|
</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.
|
|
|
|
<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>
|
|
<tr>
|
|
<td align=center><b>Format modifier</b></td>
|
|
<td align=center><b>left justify</b></td>
|
|
<td align=center><b>minimum width</b></td>
|
|
<td align=center><b>maximum width</b></td>
|
|
<td align=center><b>comment</b></td>
|
|
</tr>
|
|
|
|
<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 logger 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>Below are some examples of conversion patterns.
|
|
|
|
<p><b>\%r [\%t] \%-5p \%c \%x - \%m\n</b>
|
|
<p>This is essentially the TTCC layout.
|
|
|
|
<p><b>\%-6r [\%15.15t] \%-5p \%30.30c \%x - \%m\n</b>
|
|
|
|
<p>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.
|
|
|
|
<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.
|
|
*/
|
|
class LOG4CXX_EXPORT PatternLayout : public Layout
|
|
{
|
|
/**
|
|
* Conversion pattern.
|
|
*/
|
|
LogString conversionPattern;
|
|
|
|
/**
|
|
* Pattern converters.
|
|
*/
|
|
LOG4CXX_LIST_DEF(LoggingEventPatternConverterList, log4cxx::pattern::LoggingEventPatternConverterPtr);
|
|
LoggingEventPatternConverterList patternConverters;
|
|
|
|
/**
|
|
* Field widths and alignment corresponding to pattern converters.
|
|
*/
|
|
LOG4CXX_LIST_DEF(FormattingInfoList, log4cxx::pattern::FormattingInfoPtr);
|
|
FormattingInfoList patternFields;
|
|
|
|
|
|
public:
|
|
DECLARE_LOG4CXX_OBJECT(PatternLayout)
|
|
BEGIN_LOG4CXX_CAST_MAP()
|
|
LOG4CXX_CAST_ENTRY(PatternLayout)
|
|
LOG4CXX_CAST_ENTRY_CHAIN(Layout)
|
|
END_LOG4CXX_CAST_MAP()
|
|
|
|
/**
|
|
Does nothing
|
|
*/
|
|
PatternLayout();
|
|
|
|
/**
|
|
Constructs a PatternLayout using the supplied conversion pattern.
|
|
*/
|
|
PatternLayout(const LogString& pattern);
|
|
|
|
/**
|
|
Set the <b>ConversionPattern</b> option. This is the string which
|
|
controls formatting and consists of a mix of literal content and
|
|
conversion specifiers.
|
|
*/
|
|
void setConversionPattern(const LogString& conversionPattern);
|
|
|
|
/**
|
|
Returns the value of the <b>ConversionPattern</b> option.
|
|
*/
|
|
inline LogString getConversionPattern() const
|
|
{ return conversionPattern; }
|
|
|
|
/**
|
|
Call createPatternParser
|
|
*/
|
|
virtual void activateOptions(log4cxx::helpers::Pool& p);
|
|
|
|
virtual void setOption(const LogString& option, const LogString& value);
|
|
|
|
/**
|
|
The PatternLayout does not handle the throwable contained within
|
|
{@link spi::LoggingEvent LoggingEvents}. Thus, it returns
|
|
<code>true</code>.
|
|
*/
|
|
virtual bool ignoresThrowable() const
|
|
{ return true; }
|
|
|
|
/**
|
|
Produces a formatted string as specified by the conversion pattern.
|
|
*/
|
|
virtual void format(LogString& output,
|
|
const spi::LoggingEventPtr& event, log4cxx::helpers::Pool& pool) const;
|
|
|
|
protected:
|
|
virtual log4cxx::pattern::PatternMap getFormatSpecifiers();
|
|
};
|
|
LOG4CXX_PTR_DEF(PatternLayout);
|
|
} // namespace log4cxx
|
|
|
|
#if defined(_MSC_VER)
|
|
#pragma warning ( pop )
|
|
#endif
|
|
|
|
|
|
#endif //_LOG4CXX_PATTERN_LAYOUT_H
|