Oracle® Fusion Middleware Oracle WebLogic Server 12.1.3にデプロイされたアプリケーションへのWebLogicロギング・サービスの追加 12c (12.1.3) E56257-02 |
|
![]() 前 |
![]() 次 |
この章では、WebLogic Server 12.1.3のメッセージ・カタログとその使用方法について説明します。メッセージ・カタログは、テキスト・メッセージのコレクションが格納される単一のXMLファイルです。各メッセージは一意の識別子で索引付けされます。これらのXMLファイルをメソッドが含まれるクラス(実行時にメッセージをログに記録するために使用されるオブジェクト)にコンパイルします。
この章には次の項が含まれます:
メッセージ・カタログでは、複数のロケールまたは言語がサポートされています。特定のメッセージ・カタログには、最上位カタログというデフォルト・バージョンが必ず1つあり、英語版のメッセージが含まれます。さらに、追加してサポートされるロケールごとに、対応するロケール固有のカタログが付加されます。ビルド・プロセスでweblogic.i18ngen
ユーティリティを使用し、XMLメッセージ・カタログ・ファイルをコンパイルします。詳細は、weblogic.i18ngenユーティリティを参照してください。
最上位カタログ(英語版)には、メッセージの定義に必要な情報がすべて含まれます。ロケール固有のカタログには、メッセージID、変更された日付、および特定ロケールに対応するメッセージの変換だけが含まれます。
メッセージ・カタログ・ファイルは、XML DTD (Document Type Definition :ドキュメント・タイプ定義)によって定義されます。DTDはWL_HOME
\server\lib\weblogic.jar
のweblogic\msgcat
ディレクトリに格納されています。WL_HOME
は、WebLogic Serverの最上位のインストール・ディレクトリを示します。デフォルト・パスは、c:\Oracle\Middleware\Oracle_Home\wlserver
ですが、このディレクトリをORACLE_HOME
で表されるOracleホームにインストールする必要はありません。
インストールされたWebLogic Serverには、以下の2つのDTDが付属しています。
msgcat.dtd
- 最上位のデフォルト・カタログの構文を記述します。
l10n_msgcat.dtd
- ロケール固有のカタログの構文を記述します。
WL_HOME
\server\lib\weblogic.jar
のweblogic\msgcat
ディレクトリには、最上位のメッセージ・カタログおよびロケール固有のメッセージ・カタログ作成に使用できるテンプレートが入っています。
メッセージ・カタログの作成では、ロギングのすべての必要条件に対応するログ・メッセージ・カタログを1つ作成したり、サブシステムまたはJavaパッケージごとに細かく分けてカタログを作成することもできます。表示するときにそのログの特定の部分に焦点を当てることができるよう、複数のサブシステム・カタログの使用をお薦めします。
シンプル・テキストのカタログの場合は、国際化されるユーティリティごとに1つのカタログを作成することをお薦めします。第6章「WebLogic Serverメッセージ・エディタの使い方」の説明に従い、メッセージ・エディタを使用してメッセージ・カタログを作成します。
すべてのメッセージは、デフォルトの最上位カタログで定義する必要があります。WebLogic Serverのインストールでは、EXAMPLES_HOME
\wl_server\examples\src\examples\i18n\msgcat
ディレクトリ内にサンプル・カタログのコレクションが格納されています。ここで、EXAMPLES_HOME
は、WebLogic Serverのサンプル・コードが構成されるディレクトリを示します。
基本カタログの様々なローカライゼーションを提供するカタログは、ロケールに基づいた名前がついたmsgcat
のサブディレクトリ(ドイツ語の場合はmsgcat/de
など)に定義されています。たとえば、mycat.xml
という最上位カタログと..de/mycat.xml
というそのドイツ語版のカタログがあります。通常、最上位カタログは英語です。ただし、どのカタログでも、EXAMPLES_HOME
\wl_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パッケージ。プロパティ・ファイルの名前はカタログ・ファイル名に基づいて設定されます。
たとえば、 |
|
None |
必須 | 使用されるmsgcat.dtd のバージョンを指定します。書式はn.n です(たとえば、version="1.0" )。"1.0"以上である必要があります。
|
ロケール固有のカタログでは、最上位のログ・メッセージ・カタログのlog_message
要素で定義された属性が使用されるため、この要素は改めて定義する必要はありません。
ロケール固有のカタログでは、最上位のログ・メッセージ・カタログで定義されたmessagebody
、messagedetail
、cause
、およびaction
の各カタログ要素を使用するため、これらの要素を改めて定義する必要はありません。