org.log5j.format
Class PatternFormat

java.lang.Object
  org.log5j.format.PatternFormat

All Implemented Interfaces:

Format

public final class PatternFormat
extends java.lang.Object
implements Format

The PatternFormat class allows a developer to customise the output of a logger.

The conversion pattern for a PatternFormat is specified by the configuration property <logger-name>.format.pattern, or <logger-name>.writer.format.pattern for writer-specific formats.

Configuration is very similar to the log4j PatternLayout class although a couple of options are missing. Log5j does not yet provide mapped diagnostic contexts or nested diagnostic contexts.

Each conversion specifier starts with a percent sign (%) and is followed by optional format modifiers and a conversion character. Without a preceding percent sign, any character will be printed literally.

Conversion Character	Effect
%	Print a literal percent sign (%) by using two percent signs (%%) as an escape sequence.
c	Print the name of the logger. This conversion character can be followed by an optional precision specifier. The precision specifier is a decimal constant inside curly braces. For example, %c{3} Where the name of a logger is made up of a words separated by periods (.) this conversion specifier will print the three rightmost words. That is, if the logger name is, "a.b.c.d", this conversion specifier will print, "b.c.d".
d	Print the current date and/or time. This conversion character can be followed by an optional date format pattern enclosed in curly braces. Log5j uses Joda's DateTimeFormat class to format the date, and the format pattern should match the specification for that class.
n	Print (an) end-of-line character(s). The character(s) printed are those returned by System.getProperty("line.separator").
p	Print the name of the logging level.
t	Print the name of the current thread.
m	Print the log message.
C	Print the fully qualified class name of the object issuing the logging request. This conversion character can be followed by an optional precision specifier. The precision specifier is a decimal constant inside curly braces. For example, %C{3} This conversion specifier will print the two rightmost package names and the class name. That is, if the object's class name is, "a.b.c.MyClass", this conversion specifier will print, "b.c.MyClass". Generating this information is very slow, do not use this feature where performance is an issue.
F	Print out the filename of the class where the logging call was issued. Generating this information is extremely slow, do not use this feature where performance is an issue.
L	Print out the line number in the filename of the class where the logging call was issued. Generating this information is extremely slow, do not use this feature where performance is an issue.
M	Print out the name of the method where the logging call was issued. Generating this information is very slow, do not use this feature where performance is an issue.
l	Print out all location information from the stack trace where the logging call was issued. Generating this information is extremely slow, do not use this feature where performance is an issue.

Format modifiers affect the minimum and maximum width, and justification of each field in the pattern. Without format modifiers, each field is printed as is.

A minus character (-) at the beginning of the format modifier causes the the field to be left-justified. By default fields are right-justified.

A decimal number immediately after the minus character (or after the percent sign if there is no minus character) defines the minimum field width.

The maximum field width is also defined by a decimal number. It must be preceded by a period (.) which must follow the left justification flag and minimum field width if these exist. If a field must be truncated, the leftmost end will be truncated and the rightmost end preserved.

Some examples follow;

%10m	The log message will fill at least 10 spaces, and be right-justified if necessary.
%-15m	The log message will fill at least 15 spaces, and be left-justified if necessary.
%.20m	The log message will fill no more than 20 spaces.
%-10.20m	The log message will fill at least 10 spaces but no more than 20, It will be left-justified if necessary.

PatternFormat also recognises the configuration properties

• arrayDepth. An integer value that specifies the number of levels of nesting of arrays to recurse through when printing the contents of arrays.
• traceThrowable. if set to true, any Throwable object will have its full stack trace logged. The rules for setting the value of traceThrowable are those of the Boolean.valueOf(String) method.

Author:

Bruce Ashton

Constructor Summary

PatternFormat(java.util.Properties properties)
The standard constructor takes as arguments the properties that may affect how PatternFormat formats log lines.

Method Summary

java.lang.String

format(java.lang.String logName, java.lang.String levelName, java.lang.Object... objects) Return a formatted String derived from a number of objects or primitives to append to a logger output stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PatternFormat

public PatternFormat(java.util.Properties properties)

The standard constructor takes as arguments the properties that may affect how PatternFormat formats log lines.

PatternFormat recognises the following properties;

• arrayDepth: The number of levels of nesting of arrays to recurse through when printing the contents of arrays
• traceThrowable: Print out the entire stack trace of any Throwable if true
• pattern: The format pattern for this PatternFormat

Parameters:

properties - the properties of this format object.

Method Detail

format

public java.lang.String format(java.lang.String logName,
                               java.lang.String levelName,
                               java.lang.Object... objects)

Description copied from interface: Format

Return a formatted String derived from a number of objects or primitives to append to a logger output stream.

Specified by:

format in interface Format

Parameters:

logName - the name of the logger

levelName - the logging level name

objects - the array of objects or primitives providing Strings to log