Log4j 1.1.1

org.apache.log4j
Class PatternLayout

java.lang.Object
  |
  +--org.apache.log4j.Layout
        |
        +--org.apache.log4j.PatternLayout
All Implemented Interfaces:
OptionHandler
Direct Known Subclasses:
AppServerPatternLayout, MyPatternLayout

public class PatternLayout
extends Layout

パターン文字列を用いた柔軟なレイアウト設定。

このクラスの目的は、 format LoggingEvent そして、結果としてStringを返すことです。結果は、変換パターンに依存します。

変換パターンは、C言語のprintf関数の変換パターンに似ています。 変換パターンは、文字テキストとフォーマット制御式から構成され、 変換指定子と呼ばれます。

あたなは自由に変換パターンの内部に文字を入れることが出来ます。

それぞれの変換指定子は、パーセント記号(%)から始まり、 それにつづいてオプションと変換修飾子変換文字 があります。変換文字は、データの型を指定します。たとえば、 カテゴリー、優先度、日付、スレッド名などです。フォーマット 修飾子は、それらのフィールドの幅や、パディング、左詰、右詰などを 制御します。以下に簡単な例を示します。

変換パターンが"%-5p [%t]: %m%n"として、log4j環境で PatternLayoutが使用されたとすると、以下の文は

Category root = Category.getRoot();
root.debug("Message 1");
root.warn("Message 2");   
このように出力されるでしょう。
DEBUG [main]: Message 1
WARN  [main]: Message 2  

テキストと変換識別子の間には明確なセパレータは不要です。 パターン解析では変換文字を読み込んだときに、変換指定の 終わりを検出できます。上記の例では変換指定子の%-5pは 5文字の左詰めとしてログの優先度を示しています。 The recognized conversion characters are 認識できる変換文字は

変換文字 効果
c ロギングイベントのカテゴリーを出力するために使用します。 カテゴリー変換指定子は括弧内に10進数の定数で精密な指定 が続いて指定できます。

もし厳密指定子が与えられれば、カテゴリー名の 一番右側からして指定した数だけ出力されます。 デ不折るとではカテゴリー名は全て出力されます。

例えば、カテゴリー名"a.b.c"の場合には、パターン %c{2} は、"b.c"を出力します。

C ロギング要求を行なった完全限定クラス名を出力するときにしようします。 この変換識別子はオプションで厳密指定子で、10進数の定数を 括弧で指定することができます。

もし厳密指定子が与えられれば、クラス名のコンポーネントの 右端から対応する長さだけを印刷します。デフォルトではクラス名は 完全限定形式で出力されます。

例えば、クラス名"org.apache.xyz.SomeClass"で、パターン %C{1} は、"SomeClass"を出力します。

警告 呼び出しクラス情報の生成は遅いので、 実行速度が問題にならない場合だけ適用したほうがよい。

d ログイベントの日時の 出力に使用します。日付変換指定子は、括弧に囲まれた 日付形式指定子に従って指定されます。 たとえば、%d{HH:mm:ss,SSS}%d{dd MMM yyyy HH:mm:ss,SSS}などです。 日付形式指定子が省略された場合には、ISO8601形式が仮定されます。

日付形式指定子は、 SimpleDateFormat の時刻パターン文字列と同様な文法を受け付けます。 標準 JDK の部分とはいえ、SimpleDateFormat は、とても貧弱です。

log4jの日付フォーマットを使用するときによりよい結果として推奨されます。 これらはひとつの文字列を使用して指定することができます。 "ABSOLUTE", "DATE" and "ISO8601" for specifying AbsoluteTimeDateFormat, DateTimeDateFormat と respectively ISO8601DateFormat. 例えば、%d{ISO8601}%d{ABSOLUTE}です。

これらの専用の日付フォーマッタは、著しく SimpleDateFormat よりもよいです。

F ログ要求が発生したファイル名を出力します。

警告呼び出し位置情報の生成は、とても遅いので、 実行速度が気にならない場合のみ使用すること。

l ログが生成されたときに呼び出された位置を出力します。

位置情報は、JVMの実装に依存しています。しかし、通常 括弧の間の呼び出しソース名のファイル名と 行番号の呼び出しメソッドの完全特定名は一致します。

位置情報は、とても便利です。しかし、その生成は とても遅いので、実行速度が問題にならない場合のみ 使用するようにしてください。

L ロギング要求を行なった行番号を出力するのに使用します。

警告 呼び出し位置情報の生成はとても遅いので、 実行速度が問題にならない場合のみ使用すること。

m ロギングイベントで設定されたメッセージを出力します。
M ログ要求が行なわれたメソッド名を出力します。

警告 呼び出し位置情報の生成は、とても遅いので 実行速度が問題にならない場合のみ使用すること。

n プラットフォーム依存の改行文字を出力します。

この変換文字は、移植性のない改行文字の"\n"や"\r\n"を使用するのと 事実上パフォーマンスは同じなので、これを使用することを推奨します。

p ログの優先度を出力します。
r アプリケーションが開始してからログが出力されるまでのの 時間をミリ秒単位で出力します。
t ログを生成したスレッドの名前を出力します。
x ログが生成されたスレッドのNDC(ネスト化診断コンテキスト) を出力します。
% %%の連続は、単一のパーセント文字を出力します。

デフォルトでは、関連する情報が出力されます。 しかし、フォーマットmodifiresの助けを借りて最小幅と最大幅と 右寄せ、左寄せをすることが可能です。

オプションのフォーマット指定は、パーセント記号と 変換文字の間で行います。

最初のオプション形式指定は、左詰めフラグで、これは マイナス(-)文字です。つぎに、フィールド最小幅修飾子 がきます。これは、10進数の定数で出力の最小幅を示します。 もしデータ項目が文字数より少ない場合には、左または右に最小幅 になるまで空白が追加されます。デフォルトでは左(右詰め)に空白が 入りますが、右側にそろえることもできます。パディング文字は 空白です。データ項目がフィールドの最小幅より大きい場合には、 フィールドはデータが入りきるまで拡張されます。値は決して 切り捨てられません。

この振る舞いは、フィールド最大幅修飾子を使用して 10進数の定数にピリオドにつづけて指定することで変更することができます。 もしデータ項目がフィールドの最大幅より長ければ、データの 後ろではなく先頭から削除されていきます。 例えば、最大フィールド幅が8でデータ項目が10文字あった場合には、 最初の2文字が切り捨てられます。この振る舞いは、C言語のprintf 関数のように後ろが切り捨てられるものとは異なります。

以下にカテゴリー指示子のいろいろなフォーマット修飾の例を示します。

フォーマット指定 左詰め 最少幅 最大幅 コメント
%20c false 20 none カテゴリー名が20文字に満たなければ 左側は空白が詰められます。
%-20c true 20 none カテゴリー名が20文字に満たなければ、 右側に空白がパディングされる
%.30c NA none 30 カテゴリー名が30文字より長ければ、先頭から削除される
%20.30c false 20 30 カテゴリー名が20文字より短ければ左に空白がパディングされる。 しかし、カテゴリー名が30文字より長ければ、先頭から削除される。
%-20.30c true 20 30 カテゴリー名が20文字より短ければ右側に空白がパディングされる。 しかし、カテゴリー名が30文字より長ければ先頭から削除される。

以下は変換パターンの例です。

%r [%t] %-5p %c %x - %m\n

これは本質的にTTCCレイアウトです。

%-6r [%15.15t] %-5p %30.30c %x - %m\n

同様にTTCC レイアウトは、関連時間は、 6桁に満たない場合には右にパディングされ、スレッド名は 15文字に満たない場合には、右側にパディングされ 30文字を超える場合には、切り詰められます。

上記のテキストは、Peter A. Darnell と Philip E. Margolis の さても参照になる書籍 "C -- a Software Engineering Approach", ISBN 0-387-97389-3 から 大きく影響を受けている。

Since:
0.8.2
Author:
James P. Cakalic, Ceki Gülcü

Field Summary
protected  int BUF_SIZE
           
static String CONVERSION_PATTERN_OPTION
          Deprecated. Options are now handled using the JavaBeans paradigm. This constant is not longer needed and will be removed in the near term.
static String DEFAULT_CONVERSION_PATTERN
          Default pattern string for log output.
protected  int MAX_CAPACITY
           
static String TTCC_CONVERSION_PATTERN
          A conversion pattern equivalent to the TTCCCLayout.
 
Fields inherited from class org.apache.log4j.Layout
LINE_SEP, LINE_SEP_LEN
 
Constructor Summary
PatternLayout()
          Constructs a PatternLayout using the DEFAULT_LAYOUT_PATTERN.
PatternLayout(String pattern)
          Constructs a PatternLayout using the supplied conversion pattern.
 
Method Summary
 void activateOptions()
          Does not do anything as options become effective immediately.
protected  PatternParser createPatternParser(String pattern)
          Returns PatternParser used to parse the conversion string.
 String format(LoggingEvent event)
          Produces a formatted string as specified by the conversion pattern.
 String getConversionPattern()
          Returns the value of the ConversionPattern option.
 String[] getOptionStrings()
          Deprecated. We now use JavaBeans introspection to configure components. Options strings are no longer needed.
 boolean ignoresThrowable()
          The PatternLayout does not handle the throwable contained within LoggingEvents.
 void setConversionPattern(String conversionPattern)
          Set the ConversionPattern option.
 void setOption(String option, String value)
          Deprecated. Use the setter method for the option directly instead of the generic setOption method.
 
Methods inherited from class org.apache.log4j.Layout
getContentType, getFooter, getHeader
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CONVERSION_PATTERN_OPTION

public static final String CONVERSION_PATTERN_OPTION
Deprecated. Options are now handled using the JavaBeans paradigm. This constant is not longer needed and will be removed in the near term.

A string constant used in naming the option for setting the layout pattern. Current value of this string constant is ConversionPattern.

Note that the search for all option keys is case sensitive.


DEFAULT_CONVERSION_PATTERN

public static final String DEFAULT_CONVERSION_PATTERN
Default pattern string for log output. Currently set to the string "%m%n" which just prints the application supplied message.

TTCC_CONVERSION_PATTERN

public static final String TTCC_CONVERSION_PATTERN
A conversion pattern equivalent to the TTCCCLayout. Current value is %r [%t] %p %c %x - %m%n.

BUF_SIZE

protected final int BUF_SIZE

MAX_CAPACITY

protected final int MAX_CAPACITY
Constructor Detail

PatternLayout

public PatternLayout()
Constructs a PatternLayout using the DEFAULT_LAYOUT_PATTERN. The default pattern just produces the application supplied message.

PatternLayout

public PatternLayout(String pattern)
Constructs a PatternLayout using the supplied conversion pattern.
Method Detail

getOptionStrings

public String[] getOptionStrings()
Deprecated. We now use JavaBeans introspection to configure components. Options strings are no longer needed.

Returns the the array of option strings that PatternLayout recognizes. The only recognized option string is the value of CONVERSION_PATTERN_OPTION.

setOption

public void setOption(String option,
                      String value)
Deprecated. Use the setter method for the option directly instead of the generic setOption method.

The PatternLayout specific options are:

ConversionPattern

The value determines the conversion pattern used.

setConversionPattern

public void setConversionPattern(String conversionPattern)
Set the ConversionPattern option. This is the string which controls formatting and consists of a mix of literal content and conversion specifiers.

getConversionPattern

public String getConversionPattern()
Returns the value of the ConversionPattern option.

activateOptions

public void activateOptions()
Does not do anything as options become effective immediately. See setOption(java.lang.String, java.lang.String) method.

ignoresThrowable

public boolean ignoresThrowable()
The PatternLayout does not handle the throwable contained within LoggingEvents. Thus, it returns true.
Overrides:
ignoresThrowable in class Layout
Since:
0.8.4

createPatternParser

protected PatternParser createPatternParser(String pattern)
Returns PatternParser used to parse the conversion string. Subclasses may override this to return a subclass of PatternParser which recognize custom conversion characters.
Since:
0.9.0

format

public String format(LoggingEvent event)
Produces a formatted string as specified by the conversion pattern.
Overrides:
format in class Layout

Log4j 1.1.1

Please notify me about new log4j releases.