|
||||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 内部クラス | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
java.lang.Object
|
+--org.apache.log4j.Layout
|
+--org.apache.log4j.PatternLayout
A flexible layout configurable with pattern string.
パターン文字列を用いた柔軟なレイアウト設定。
The goal of this class is to format a LoggingEvent and return the results as a String. The results
depend on the conversion pattern.
このクラスの目的は、
LoggingEvent
を
formatして、その結果としてStringを返すことです。変換結果は、
変換パターンに依存します。
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 conversion specifiers.
変換パターンは、C言語のprintf関数の変換パターンに似ています。 変換パターンは、文字テキストとフォーマット制御式から構成され、 変換指定子と呼ばれます。
You are free to insert any literal text within the conversion pattern.
あたなは自由に変換パターンの内部に文字を入れることが出来ます。
Each conversion specifier starts with a percent sign (%) and is followed by optional format modifiers and a conversion character. The conversion character specifies the type of data, e.g. category, priority, date, thread name. The format modifiers control such things as field width, padding, left and right justification. The following is a simple example.
それぞれの変換指定子は、パーセント記号(%)から始まり、 それにつづくオプションと変換修飾子と変換文字 があります。変換文字は、データの型を指定します。たとえば、 カテゴリー、優先度、日付、スレッド名などです。フォーマット 修飾子は、それらのフィールドの幅や、パディング、左詰、右詰などを 制御します。以下に簡単な例を示します。
Let the conversion pattern be "%-5p [%t]: %m%n" and assume that the log4j environment was set to use a PatternLayout. Then the statements
変換パターンが"%-5p [%t]: %m%n"として、log4j環境で PatternLayoutが使用されたとすると、以下の文は
Category root = Category.getRoot();
root.debug("Message 1");
root.warn("Message 2");
would yield the outputDEBUG [main]: Message 1 WARN [main]: Message 2
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 %-5p means the priority of the logging event should be left justified to a width of five characters. The recognized conversion characters are
テキストと変換識別子の間に明確なセパレータは不要です。 パターン解析では変換文字を読み込んだときに、変換指定の 終わりを検出できます。上記の例では変換指定子の%-5pは 5文字の左詰めとしてログの優先度を示しています。 認識できる変換文字は
| Conversion Character | Effect |
|---|---|
| c | Used to output the category of the logging event. The
category conversion specifier can be optionally followed by
precision specifier, that is a decimal constant in
brackets.
If a precision specifier is given, then only the corresponding number of right most components of the category name will be printed. By default the category name is printed in full. For example, for the category name "a.b.c" the pattern %c{2} will output "b.c". |
| C | Used to output the fully qualified class name of the caller
issuing the logging request. This conversion specifier
can be optionally followed by precision specifier, that
is a decimal constant in brackets.
If a precision specifier is given, then only the corresponding number of right most components of the class name will be printed. By default the class name is output in fully qualified form. For example, for the class name "org.apache.xyz.SomeClass", the pattern %C{1} will output "SomeClass". WARNING Generating the caller class information is slow. Thus, it's use should be avoided unless execution speed is not an issue. |
| d | Used to output the date of
the logging event. The date conversion specifier may be
followed by a date format specifier enclosed between
braces. For example, %d{HH:mm:ss,SSS} or
%d{dd MMM yyyy HH:mm:ss,SSS}. If no
date format specifier is given then ISO8601 format is
assumed.
The date format specifier admits the same syntax as the
time pattern string of the For better results it is recommended to use the log4j date
formatters. These can be specified using one of the strings
"ABSOLUTE", "DATE" and "ISO8601" for specifying These dedicated date formatters perform significantly
better than |
| F | Used to output the file name where the logging request was
issued.
WARNING Generating caller location information is extremely slow. It's use should be avoided unless execution speed is not an issue. |
| l | Used to output location information of the caller which generated
the logging event.
The location information depends on the JVM implementation but usually consists of the fully qualified name of the calling method followed by the callers source the file name and line number between parentheses. The location information can be very useful. However, it's generation is extremely slow. It's use should be avoided unless execution speed is not an issue. |
| L | Used to output the line number from where the logging request
was issued.
WARNING Generating caller location information is extremely slow. It's use should be avoided unless execution speed is not an issue. |
| m | Used to output the application supplied message associated with the logging event. |
| M | Used to output the method name where the logging request was
issued.
WARNING Generating caller location information is extremely slow. It's use should be avoided unless execution speed is not an issue. |
| n | Outputs the platform dependent line separator character or
characters.
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. |
| p | Used to output the priority of the logging event. |
| r | Used to output the number of milliseconds elapsed since the start of the application until the creation of the logging event. |
| t | Used to output the name of the thread that generated the logging event. |
| x | Used to output the NDC (nested diagnostic context) associated with the thread that generated the logging event. |
| % | The sequence %% outputs a single percent sign. |
| 変換文字 | 効果 |
|---|---|
| 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(ネスト化診断コンテキスト) を出力します。 |
| % | %%の連続は、単一のパーセント文字を出力します。 |
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.
デフォルトでは、関連する情報が出力されます。 しかし、フォーマットmodifiresの助けを借りて最小幅と最大幅と 右寄せ、左寄せをすることが可能です。
The optional format modifier is placed between the percent sign and the conversion character.
オプションのフォーマット指定は、パーセント記号と 変換文字の間で行います。
The first optional format modifier is the left justification flag which is just the minus (-) character. Then comes the optional minimum field width 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.
最初のオプション形式指定は、左詰めフラグで、これは マイナス(-)文字です。つぎに、フィールド最小幅修飾子 がきます。これは、10進数の定数で出力の最小幅を示します。 もしデータ項目が文字数より少ない場合には、左または右に最小幅 になるまで空白が追加されます。デフォルトでは左(右詰め)に空白が 入りますが、右側にそろえることもできます。パディング文字は 空白です。データ項目がフィールドの最小幅より大きい場合には、 フィールドはデータが入りきるまで拡張されます。値は決して 切り捨てられません。
This behavior can be changed using the maximum field width 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 beginning 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.
この振る舞いは、フィールド最大幅修飾子を使用して 10進数の定数にピリオドにつづけて指定することで変更することができます。 もしデータ項目がフィールドの最大幅より長ければ、データの 後ろではなく先頭から削除されていきます。 例えば､最大フィールド幅が8でデータ項目が10文字あった場合には、 最初の2文字が切り捨てられます。この振る舞いは、C言語のprintf 関数のように後ろが切り捨てられるものとは異なります。
Below are various format modifier examples for the category conversion specifier.
以下にカテゴリー指示子のいろいろなフォーマット修飾の例を示します。
| Format modifier | left justify | minimum width | maximum width | comment |
|---|---|---|---|---|
| %20c | false | 20 | none | Left pad with spaces if the category name is less than 20 characters long. |
| %-20c | true | 20 | none | Right pad with spaces if the category name is less than 20 characters long. |
| %.30c | NA | none | 30 | Truncate from the beginning if the category name is longer than 30 characters. |
| %20.30c | false | 20 | 30 | Left pad with spaces if the category name is shorter than 20 characters. However, if category name is longer than 30 characters, then truncate from the beginning. |
| %-20.30c | true | 20 | 30 | Right pad with spaces if the category name is shorter than 20 characters. However, if category name is longer than 30 characters, then truncate from the beginning. |
| フォーマット指定 | 左詰め | 最少幅 | 最大幅 | コメント |
|---|---|---|---|---|
| %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文字より長ければ先頭から削除される。 |
Below are some examples of conversion patterns.
以下は変換パターンの例です。
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.
上記のテキストは、Peter A. Darnell と Philip E. Margolis の とても参照になる書籍 "C -- a Software Engineering Approach", ISBN 0-387-97389-3 から 大きく影響を受けている。
| フィールドの概要 | |
protected int |
BUF_SIZE
|
static String |
CONVERSION_PATTERN_OPTION
推奨されていません。 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. |
| クラス org.apache.log4j.Layout から継承したフィールド |
LINE_SEP, LINE_SEP_LEN |
| コンストラクタの概要 | |
PatternLayout()
Constructs a PatternLayout using the DEFAULT_LAYOUT_PATTERN. |
|
PatternLayout(String pattern)
Constructs a PatternLayout using the supplied conversion pattern. |
|
| メソッドの概要 | |
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()
推奨されていません。 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)
推奨されていません。 Use the setter method for the option directly instead of the generic setOption method. |
| クラス org.apache.log4j.Layout から継承したメソッド |
getContentType, getFooter, getHeader |
| クラス java.lang.Object から継承したメソッド |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| フィールドの詳細 |
public static final String CONVERSION_PATTERN_OPTION
文字列定数は、レイアウトパターン設定のための名前を付ける オプションです。この文字列定数の現在の値は、ConversionPatternです。
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
| コンストラクタの詳細 |
public PatternLayout()
public PatternLayout(String pattern)
| メソッドの詳細 |
public String[] getOptionStrings()
PatternLayout recognizes. The only recognized option string is
the value of CONVERSION_PATTERN_OPTION.
PatternLayoutが認識できるオプション文字列の配列を戻す。
認識できるオプション文字列は、
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.
setOption(java.lang.String, java.lang.String) メソッド参照。public boolean ignoresThrowable()
LoggingEvents. Thus, it returns
true.
PatternLayoutは、LoggingEvents内部で
throwable含む取扱いはしない。そのためtureを戻す。Layout 内の ignoresThrowableprotected PatternParser createPatternParser(String pattern)
public String format(LoggingEvent event)
Layout 内の format
|
||||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 内部クラス | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||