|
Log4j 1.1.1 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--org.apache.log4j.Layout | +--org.apache.log4j.PatternLayout
パターン文字列を用いた柔軟なレイアウト設定。
このクラスの目的は、
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形式が仮定されます。
日付形式指定子は、
log4jの日付フォーマットを使用するときによりよい結果として推奨されます。
これらはひとつの文字列を使用して指定することができます。
"ABSOLUTE", "DATE" and "ISO8601" for specifying これらの専用の日付フォーマッタは、著しく
|
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文字より長ければ先頭から削除される。 |
以下は変換パターンの例です。
上記のテキストは、Peter A. Darnell と Philip E. Margolis の さても参照になる書籍 "C -- a Software Engineering Approach", ISBN 0-387-97389-3 から 大きく影響を受けている。
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 |
public static final String CONVERSION_PATTERN_OPTION
Note that the search for all option keys is case sensitive.
public static final String DEFAULT_CONVERSION_PATTERN
public static final String TTCC_CONVERSION_PATTERN
protected final int BUF_SIZE
protected final int MAX_CAPACITY
Constructor Detail |
public PatternLayout()
public PatternLayout(String pattern)
Method Detail |
public String[] getOptionStrings()
PatternLayout
recognizes. The only recognized option string is
the value of CONVERSION_PATTERN_OPTION
.public void setOption(String option, String value)
setOption
method.
public void setConversionPattern(String conversionPattern)
public String getConversionPattern()
public void activateOptions()
setOption(java.lang.String, java.lang.String)
method.public boolean ignoresThrowable()
LoggingEvents
. Thus, it returns
true
.ignoresThrowable
in class Layout
protected PatternParser createPatternParser(String pattern)
public String format(LoggingEvent event)
format
in class Layout
|
Log4j 1.1.1 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |