Oracle® Fusion Middleware Oracle WebLogic Server アプリケーション ロギングのロギング サービス ユーザーズ ガイド 11g リリース 1 (10.3.1) B55513-01 |
|
戻る |
次へ |
以下の節では、メッセージ カタログとその使い方について説明します。
メッセージ カタログは、テキスト メッセージのコレクションが格納される単一の XML ファイルです。各メッセージには、ユニークな識別子が付けられます。これらの XML ファイルを、ビルド プロセス中に weblogic.i18ngen
を使用してクラスにコンパイルします(詳細については、「weblogic.i18ngen ユーティリティ」を参照してください)。生成されたクラスのメソッドは、実行時にメッセージをログに記録するために使用されるオブジェクトとなります。
メッセージ カタログでは、複数のロケールまたは言語がサポートされています。特定のメッセージ カタログには、最上位カタログというデフォルト バージョンが必ず 1 つあり、英語版のメッセージが含まれます。さらに、追加してサポートされるロケールごとに、対応するロケール固有のカタログが付加されます。
最上位カタログ (英語版) には、メッセージの定義に必要な情報がすべて含まれます。ロケール固有のカタログには、メッセージ ID、変更された日付、および特定ロケールに対応するメッセージの変換だけが含まれます。
メッセージ カタログ ファイルは、XML DTD (Document Type Definition : 文書型定義) によって定義されます。DTD は WL_HOME
\server\lib\weblogic.jar
の weblogic\msgcat
ディレクトリに格納されています。WL_HOME
は、WebLogic Server の最上位のインストール ディレクトリを示します。デフォルトのパスは c:\Oracle\Middleware\wlserver_10.3
です。ただし、このディレクトリを Oracle Middleware ホーム ディレクトリ MW_HOME
にインストールする必要はありません。
インストールされた WebLogic Server には、以下の 2 つの DTD が付属しています。
msgcat.dtd
- 最上位のデフォルト カタログの構文を記述します。
l10n_msgcat.dtd
- ロケール固有のカタログの構文を記述します。
WL_HOME
\server\lib\weblogic.jar
の weblogic\msgcat
ディレクトリには、最上位のメッセージ カタログおよびロケール固有のメッセージ カタログ作成に使用できるテンプレートが入っています。
メッセージ カタログの作成では、ロギングのすべての必要条件に対応するログ メッセージ カタログを 1 つ作成したり、サブシステムまたは Java パッケージごとに細かく分けてカタログを作成することもできます。表示するときにそのログの特定の部分に焦点を当てることができるよう、複数のサブシステム カタログの使用をお勧めします。
シンプル テキストのカタログの場合は、インターナショナライズされるユーティリティごとに 1 つのカタログを作成することをお勧めします。「WebLogic Server メッセージ エディタの使い方」の説明に従い、メッセージ エディタを使用してメッセージ カタログを作成します。
すべてのメッセージは、デフォルトの最上位カタログで定義する必要があります。インストールされた WebLogic Server では、SAMPLES_HOME
\server\examples\src\examples\i18n\msgcat
ディレクトリ内にサンプル カタログのコレクションが格納されています。SAMPLES_HOME
は、WL_HOME
\samples
にある WebLogic Server サンプル ホーム ディレクトリを示します。
基本カタログのさまざまなローカライゼーションを提供するカタログは、ロケールに基づいた名前がついた msgcat
のサブディレクトリ (ドイツ語の場合は msgcat/de
など) に定義されています。たとえば、mycat.xml
という最上位カタログと ..de/mycat.xml
というそのドイツ語版のカタログがあります。通常、最上位カタログは英語です。ただし、どのカタログでも、SAMPLES_HOME
\server\examples\src\examples\i18n\msgcat
ディレクトリ内のものを除き、英語は必須ではありません。
java.util.Locale
のドキュメントで定義されているように、ロケールの指定 (de
など) にも階層があります。ロケールでは言語、国、およびバリアントを指定できます。言語は、ロケール指定でもっとも一般的なものです。言語は国コードによって拡張できます。たとえば、en\US
はアメリカ英語を示します。これに関連付けられたカタログの名前は、..en\US\mycat.xml
となります。バリアントはベンダまたはブラウザに固有であり、言語または国で定義された複数のロケールの間で細かな違い (照合順序など) を持たせるために使用します。
メッセージ カタログ ファイルの名前 (xml
拡張子を除く) は、実行時クラスおよびプロパティ名の生成に使用されるため、命名は慎重に行ってください。
メッセージ カタログに名前を付ける場合、以下のガイドラインに従ってください。
メッセージ カタログを作成している対象パッケージ内の既存クラスの名前と衝突するようなメッセージ カタログ名は避ける。
メッセージ カタログ名に含まれる文字は、クラス名に使用できる文字のみを使用する。
クラス名の命名規約に従う。
たとえば、カタログの名前が Xyz.xml
の場合、生成されるクラス名は XyzLogLocalizer
および XyzLogger
になります。
以下の考慮事項も、メッセージ カタログ ファイルに適用されます。
メッセージ ID は、通常は先頭に 0 が付く 6 文字の文字列。一部のインタフェースでは、整数表現もサポートされています。
注意 : これは、ログ メッセージ カタログにのみ適用されます。シンプル テキスト カタログは任意の文字列をとることができます。 |
Java では、パッケージと呼ばれるコレクションにクラスをまとめることができる。パッケージ名は、特定のカタログが存在するサブシステムの名前と一致している必要があります。
ログの Localizer「クラス」は、実際には ResourceBundle
プロパティ ファイルである。
ログ メッセージのメッセージ本文、メッセージ詳細、原因、およびアクションなどのセクションには、java.text.MessageFormat
に記載されているようなメッセージ引数を組み込むことができます。メッセージの内容が、java.text.MessageFormat
で指定されたパターンに準拠していることを確認してください。シンプル テキスト メッセージでは、引数を入れられるのは、メッセージ本文のセクションに限られます。引数は、実行時に動的に設定される値を表します。これらの値は、メッセージを出力するなどのルーチンに渡されます。1 つのメッセージには 0 ~ 9 で番号付けされた 10 個までの引数をサポートできます。メッセージ本文にはすべての引数を入れる必要がありますが、メッセージ定義 (メッセージ本文、メッセージ詳細、妥当な原因) の任意のテキスト セクションにもこれらの引数の任意のサブセットを入れることができます。メッセージ引数は開発時にメッセージ定義に挿入され、実行時においてメッセージがログに記録されるときに適切なメッセージ コンテンツに置き換えられます。
以下は、XML ログ メッセージ定義の抜粋で、メッセージ引数の使い方を示しています。引数の番号は、method
属性で指定された引数の 1 つと対応している必要があります。具体的には、{0}
は最初の引数と、{1}
は 2 番目の引数と対応している必要があります。コード リスト 4-1 では、{0}
は開けないファイルを表し、{1}
は適切に開かれるファイルを表します。
コード リスト 4-1 メッセージ引数の例
<messagebody>Unable to open file, {0}. Opening {1}. All arguments must be in body.</messagebody> <messagedetail> File, {0} does not exist. The server will restore the file contents from {1}, resulting in the use of default values for all future requests. </messagedetail> <cause>The file was deleted</cause> <action>If this error repeats then investigate unauthorized access to the file system.</action>
次に、method
属性の例を示します。
-method="logNoFile(String name, String path)"
コード リスト 4-1 のメッセージの例では、2 つの引数 {0}
および {1}
が使用されています。
両方とも <messagebody>
で使用されている。
両方とも <messagedetail>
で使用されている。
どちらも <cause>
または <action>
では使用されていない。
注意 : 1 つのメッセージには 0 ~ 9 で番号付けされた 10 個までの引数をサポートできます。メッセージ本文にはすべての引数を入れる必要がありますが、メッセージ定義 (メッセージ詳細、原因、アクション) の任意のテキスト セクションにもこれらの引数の任意のサブセットを入れることができます。 |
また、引数は文字列であるか、文字列として表現可能である必要があります。数値データは {n,number}
として表されます。日付は {n,date}
としてサポートされます。また、ログ メッセージでは重大度レベルを割り当てる必要があります。ログ メッセージは、Logger
メソッドによって method
属性で定義されているとおりに生成されます。
最上位のカタログ ファイルとロケール固有のカタログ ファイルでは、カタログのフォーマットが若干異なります。最上位カタログでは、基本ロケール (デフォルトでは、英語) のテキスト メッセージが定義されます。ロケール固有のカタログ (スペイン語に翻訳されたカタログなど) は、最上位バージョンで定義されているテキストの翻訳だけを備えています。さらに、ログ メッセージ カタログではシンプル テキスト カタログと定義の方法が異なります。
各タイプのメッセージ カタログの例および要素は、以下の節で説明されています。
次の例は、ログ メッセージを 1 つ持つログ メッセージ カタログ MyUtilLog.xml
を示しています。このログ メッセージは、messagebody
、messagedetail
、cause
、および action
の各要素の使用方法を示しています。
コード リスト 4-2 ログ メッセージ カタログの例
<?xml version="1.0"?> <!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd" "http://www.bea.com/servers/wls90/dtd/msgcat.dtd"> <message_catalog l10n_package="programs.utils" i18n_package="programs.utils" subsystem="MYUTIL" version="1.0" baseid="600000" endid="600100" <log_message messageid="600001" severity="warning" method="logNoAuthorization(String arg0, java.util.Date arg1, int arg2)" <messagebody> Could not open file, {0} on {1,date} after {2,number} attempts. </messagebody> <messagedetail> The configuration for this application will be defaulted to factory settings. Custom configuration information resides in file, {0}, created on {1,date}, but is not readable. </messagedetail> <cause> The user is not authorized to use custom configurations. Custom configuration information resides in file, {0}, created on {1,date}, but is not readable.The attempt has been logged to the security log. </cause> <action> The user needs to gain approriate authorization or learn to live with the default settings. </action> </log_message> </message_catalog>
この節では、ログ メッセージ カタログの以下の要素に関するリファレンス情報を提供します。
message_catalog
要素は、ログ メッセージ カタログを表します。次の表では、message_catalog
要素で定義できる各属性について説明します。
属性 | デフォルト値 | 必須/省略可能 | 説明 |
---|---|---|---|
i18n_package |
weblogic.i18n |
省略可能 | このカタログの Logger クラスを含む Java パッケージ。クラスの名前はカタログ ファイルの名前に基づいて付けられる。たとえば、カタログの名前が mycat.xml の場合、生成される Logger クラスの名前は <i18n_package> .mycatLogger.class になる。
構文 : 標準の Java パッケージ構文 例 : |
l10n_package |
weblogic.i18n |
省略可能 | カタログの LogLocalizer プロパティを含む Java パッケージ。たとえば、カタログの名前が mycat.xml の場合は、<l10n_package> .mycatLogLocalizer.properties および <l10n_package> mycatLogLocalizerDetail.properties という名前のプロパティ ファイルが生成される。
構文 : 標準の Java パッケージ構文 例 : |
subsystem |
なし | 必須 | このカタログと関連付けられているサブシステムを識別する頭字語。サブシステムの名前はサーバ ログに含まれ、メッセージの分離を目的として使用される。
構文 : 文字列 例 : |
version |
なし | 必須 | 使用される msgcat.dtd のバージョンを指定する。
使用方法 : 「 構文 : x.y (x および y は数値) 例 : |
baseid |
000000 : WebLogic Server カタログ
|
省略可能 | このカタログで使用される最低のメッセージ ID を指定する。
構文 : 1 桁から 6 桁の数値。 例 : |
endid |
499999 : WebLogic Server カタログ
|
省略可能 | このカタログで使用される最高のメッセージ ID を指定する。
構文 : 1 桁から 6 桁の数値。 例 : |
loggable |
false | 省略可能 | Loggable オブジェクトを返す追加メソッドを生成するかどうかを示す。
構文 : 例 : |
prefix |
ユーザ定義のカタログの場合は Null
WebLogic Server カタログの場合は「 |
省略可能 | ログに記録されるときにメッセージ ID の先頭に追加する文字列を指定する。サーバ メッセージは、プレフィックスのデフォルトは「BEA」で、別のプレフィックスを指定することはできない。ユーザ メッセージは、任意のプレフィックスを指定することが可能。プレフィックスが付いたメッセージ ID は、ログ エントリで次のように表示される。
<[prefix-]id> ここで、 たとえば、 構文 : 任意の文字列 (5 文字まで) 例 : |
description |
Null (説明なし) | 省略可能 | カタログの内容を説明する省略可能な属性。
構文 : 任意の文字列 例 : |
次の表では、log_message
要素で定義できる各属性について説明します。
属性 | デフォルト値 | 必須/省略可能 | 説明 |
---|---|---|---|
messageid |
なし | 必須 | このログ メッセージのユニークな識別子。識別子は、すべてのカタログにわたりユニークである必要がある。値は、baseid 属性と endid 属性で定義された範囲で指定する必要がある。
使用方法 : 値は、message_catalog 属性の 構文 : 1 桁から 6 桁の数値。 例 : |
datelastchanged |
なし | 省略可能 | このメッセージの修正管理に使用される日付と時刻のスタンプ。日付は、カタログで動作するユーティリティによって提供される。
構文 : Long.toString(new Date().getTime()); 使用方法 : 日付は、カタログで動作するユーティリティ (メッセージ エディタなど) によって提供される。 構文 : |
severity |
なし | 必須 | ログ メッセージの重大度を示す。値は、debug 、info 、warning 、error 、notice 、critical 、alert 、または emergency のいずれかである必要がある。ユーザ定義のカタログで使用できるのは、debug 、info 、warning 、および error に限られる場合がある。
例 : |
method |
なし | 必須 | このメッセージをログに記録するためのメソッド シグネチャ。
構文は標準の Java メソッド シグネチャから修飾子、セミコロン、および拡張子を除いたもの。引数の型には Java プリミティブまたは Java クラスを使用できる。クラスは 引数には有効であればどのような名前でも指定できるが、 |
methodtype |
logger |
省略可能 | 生成するメソッドのタイプを指定する。メソッドは、Logger または Getter のいずれかである。Logger メソッドは、メッセージ本文をデフォルトのロケールにフォーマットし、結果をログに記録する。Getter メソッドは、[susbsystem:msgid]text のように、メッセージ本文の前にサブシステムおよびメッセージ ID を付けて返す。
構文 : 値は、「 |
stacktrace |
true |
省略可能 | Throwable の引数としてスタック トレースを生成するかどうかを示す。true または false を指定できる。値が true の場合はトレースが生成される。
構文 : |
|
false |
省略可能 | メッセージが廃止されているかどうかを示す。廃止されたメッセージとは、前のリリースで使用されていたが、今は古くなり、現在のバージョンでは使用されないメッセージ。廃止されたメッセージは、クラスまたはリソースの生成で使用しない。
構文 : 値は、 例 : |
次の表では、log_message 要素の子要素を説明します。
要素 | 親要素 | 必須/省略可能 | 説明 |
---|---|---|---|
messagebody |
log_message |
必須 | このメッセージの短い説明。
最後の引数が Throwable またはサブクラスでない場合、メッセージ本文には、対応するメソッド属性にリストされたすべての引数に対するプレースホルダを含める必要がある。 一重引用符は、 構文 : 文字列 例 :
|
messagedetail |
log_message |
省略可能 | イベントの詳しい説明。この要素には、任意の引数のプレースホルダを含めることができる。
構文 : 文字列 例 :
|
|
|
省略可能 | 問題の根本的な原因。この要素には、任意の引数のプレースホルダを含めることができる。
構文 : 文字列 例 : |
|
|
省略可能 | 適切な解決策。この要素には、任意の引数のプレースホルダを含めることができる。
構文 : 文字列 例 : |
次の例は、1 つのシンプル テキスト定義を備えるシンプル テキスト カタログ MyUtilLabels.xml
を示しています。
<messagebody> File </messagebody>
コード リスト 4-3 シンプル テキスト カタログの例
<?xml version="1.0"?> <!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd" "http://www.bea.com/servers/wls90/dtd/msgcat.dtd"> <message_catalog> l10n_package="programs.utils" i18n_package="programs.utils" subsystem="MYUTIL" version="1.0" <message> messageid="FileMenuTitle" <messagebody> File </messagebody> </message> </message_catalog>
この節では、シンプル テキスト カタログの以下の要素に関するリファレンス情報を提供します。
次の表では、message_catalog
要素で定義できる各属性について説明します。
属性 | デフォルト値 | 必須/省略可能 | 説明 |
---|---|---|---|
|
|
省略可能 | このカタログに生成された TextFormatter クラスおよび TextLocalizer プロパティを含む Java パッケージ。クラスの名前はカタログ ファイルの名前に基づいて付けられる。カタログ ファイルの名前が mycat.xml の場合は、< l10n_package >.mycatLogLocalizer.properties という名前のプロパティ ファイルが生成される。
構文 : 標準の Java パッケージ構文 例 : |
|
なし | 必須 | このカタログと関連付けられているサブシステムを識別する頭字語。サブシステムの名前はサーバ ログに含まれ、メッセージの分離を目的として使用される。
構文 : 文字列 例 : |
|
なし | 必須 | 使用される msgcat.dtd のバージョンを指定する。書式は n.n で、たとえば version="1.0" のように定義する。「1.0」以上である必要がある。
例 : |
|
Null | 省略可能 | カタログの内容を説明する省略可能な属性。
構文 : 文字列 例 : |
次の表では、message
要素で定義できる各属性について説明します。
属性 | デフォルト値 | 必須/省略可能 | 説明 |
---|---|---|---|
|
なし | 必須 | このログ メッセージのユニークな識別子 (英数字の文字列)。識別子はこのカタログのコンテキストの中でユニークであれば良い。message は message_catalog の子要素である。 |
|
なし | 省略可能 | このメッセージの修正の管理に便利な日付と時刻のスタンプ。 |
|
なし | 省略可能 | このメッセージをフォーマットするためのメソッド シグネチャ。
構文は標準の Java メソッド シグネチャから戻り値の型、修飾子、セミコロン、および拡張子を除いたもの。戻り値の型は常に 各引数について、次に説明する 例 :
この例は、次のように
|
次の例は、...\msgcat\fr\MyUtilLabels.xml
にあるメッセージのフランス語版です。
翻訳されたメッセージをコード リスト 4-4 に示します。
コード リスト 4-4 フランス語に翻訳されたメッセージの例
<?xml version="1.0"?> <!DOCTYPE message_catalog PUBLIC "weblogic-locale-message-catalog-dtd" "http://www.bea.com/servers/wls90/dtd/l10n_msgcat.dtd"> <locale_message_catalog l10n_package="programs.utils" subsystem="MYUTIL" version="1.0"> <message> <messageid="FileMenuTitle"> <messagebody> Fichier </messagebody> </message> </locale_message_catalog>
messagebody
、messagedetail
、cause
、および action
の各要素でテキストを入力するときには、有効な UTF-8 (Unicode Transformation Format-8) 文字を生成するツールを使用するとともに、適切なキーボードのマッピングがインストールされている必要があります。UTF-8 は、ASCII 文字のエンコーディングを最適化する、効率的な Unicode 文字列エンコーディング方式です。メッセージ カタログでは常に UTF-8 エンコーディング方式が使用されます。WebLogic Server と共にインストールされる MessageLocalizer
ユーティリティは、有効な UTF-8 文字の生成に使用できるツールです。
ロケール固有のカタログは、最上位カタログのサブセットです。ロケール固有のカタログは、それらが表すロケールに基づいた名前のサブディレクトリに格納されます。以下の節で説明する要素および属性は、ロケール固有のカタログに有効なものです。
次の表では、locale_message_catalog
要素で定義できる各属性について説明します。
属性 | デフォルト値 | 必須/省略可能 | 説明 |
---|---|---|---|
|
|
省略可能 | このカタログに対して生成された LogLocalizer または TextLocalizer プロパティを含む Java パッケージ。プロパティ ファイルの名前はカタログ ファイル名に基づいて設定される。
たとえば、 |
|
なし |
必須 | 使用される msgcat.dtd のバージョンを指定する。書式は n.n で、たとえば version="1.0" のように定義する。「"1.0」以上である必要がある。
|
ロケール固有のカタログでは、最上位のログ メッセージ カタログの log_message
要素で定義された属性が使用されるため、この要素は改めて定義する必要はありません。
ロケール固有のカタログでは、最上位のログ メッセージ カタログで定義された messagebody
、messagedetail
、cause
、および action
の各カタログ要素を使用するため、これらの要素を改めて定義する必要はありません。