Oracle® Fusion Middleware Oracle Stream Analyticsによるイベント処理用アプリケーションの開発 12c (12.2.1.1.0) E77666-02 |
|
![]() 前へ |
![]() 次へ |
メッセージ・カタログを使用して、サーバー・ログに送信されるメッセージ・テキストまたはユーザーに対して表示されるメッセージ・テキストをインターナショナライズできます。これらのメッセージは、どのユーザーが特定のアプリケーション・コンポーネントやエラー条件を呼び出したかなど、アプリケーション内で発生した事象に関する情報を提供したり、アプリケーションをリリースする前にデバッグする上で役立ちます。
この章の内容は次のとおりです。
メッセージ・カタログは、メッセージのコレクションが格納される単一のXMLファイルです。各メッセージには、一意のIDが付けられます。インターナショナライズするテキストはすべて、メッセージ・カタログで定義および具体化されます。各メッセージ・カタログでは、ログ・メッセージまたはシンプル・テキストのコレクションが定義されます。
メッセージ・カタログを使用すると、アプリケーション・コードを変更または再コンパイルせずにメッセージ文字列を複数のロケールに変換できます。
メッセージIDは、すべてのログ・メッセージまたはロケール・メッセージ・カタログを通じて一意です。メッセージ・カタログ・ファイル内で、各メッセージのローカライズされたバージョンには、エラーを特定する一意のメッセージIDとメッセージ・テキストが割り当てられます。原則的に、メッセージは、サポート担当者が簡単に見つけられるように、システム内の1つの場所からログに記録します。シンプル・テキスト・カタログのメッセージIDは、各シンプル・テキスト・カタログ内で一意です。
メッセージ・カタログには、次の3つのタイプがあります。
ログ・メッセージ・カタログ: アプリケーションでサーバー・ログに記録される情報メッセージまたはエラー・メッセージ。
シンプル・テキスト・メッセージ・カタログ: ユーザーに対して表示されるシンプル・メッセージ。
ロケール・メッセージ・カタログ: 英語版のメッセージが含まれる最上位のログ・メッセージ・カタログまたはシンプル・テキスト・カタログに対応する、ロケール固有のメッセージのコレクション。対応するロケール固有のカタログがあり、追加してサポートされるロケールごとに1つのカタログが付加されます。
最上位の英語版カタログには、メッセージの定義に必要な情報がすべてあります。ロケール固有のカタログには、メッセージID、変更された日付、および特定ロケールに対応するメッセージの変換だけが含まれます。
独自のログ・メッセージまたはシンプル・テキスト・メッセージのカタログを作成し、Oracle WebLogicユーティリティを使用して、ロギング・メソッドを持つJavaクラスを生成できます。Javaクラスをアプリケーション・コードにインポートし、ロギング・メソッドにランタイム値を提供するようアプリケーション・コードを実装します。ロギング・メソッドによって生成されたログ・メッセージは、Oracle Stream Analyticsサーバーによって生成されたログ・メッセージと同じ方法で統合および処理されます。
メッセージ・カタログ・ファイルは次のXMLドキュメント・タイプ定義(DTD)ファイルのいずれかで定義されます。
msgcat.dtd
: 最上位のデフォルト・カタログの構文を記述します。
l10n_msgcat.dtd
: ロケール固有のカタログの構文を記述します。
DTDは、/Oracle/Middleware/wlevserver/modules/ com.bea.core.i18n.generator_VERSION.jar
に格納されます。VERSION
は特定のバージョンを表し、これは変更されます。
ロギングのすべての要件に対応するログ・メッセージ・カタログを1つ作成したり、サブシステムまたはJavaパッケージに基づいて細かく分けてカタログを作成することもできます。表示するときにそのログの特定の部分に焦点を当てることができるよう、複数のサブシステム・カタログの使用をお薦めします。シンプル・テキストのカタログの場合は、インターナショナライズされるユーティリティごとに1つのカタログを作成することをお薦めします。
すべてのメッセージは、デフォルトの最上位カタログで定義する必要があります。基本カタログの様々なローカライゼーションを提供するカタログは、ロケールに基づいた名前が付けられたmsgcat
のサブディレクトリ(ドイツ語の場合はmsgcat/de
など)に定義されています。たとえば、mycat.xml
という最上位カタログと..de/mycat.xml
というそのドイツ語版のカタログがあります。通常、最上位カタログは英語です。ただし、どのカタログでも英語は必須ではありません。
java.util.Locale
のドキュメントで定義されているように、ロケールの指定(de
など)にも階層があります。ロケールでは言語、国、およびバリアントを指定できます。言語は、ロケール指定でもっとも一般的なものです。言語は国コードによって拡張できます。たとえば、en\US
はアメリカ英語を示します。これに関連付けられたカタログの名前は、..en\US\mycat.xml
となります。バリアントはベンダーまたはブラウザに固有であり、言語または国で定義された複数のロケールの間で細かな違い(照合順序など)を持たせるために使用します。
メッセージ・カタログ・ファイルの名前(.xml
拡張子を除く)は、実行時クラスおよびプロパティ名の生成に使用されるため、命名は慎重に行ってください。メッセージ・カタログに名前を付ける場合、次のガイドラインに従ってください。
メッセージ・カタログを作成しているターゲット・パッケージ内の既存クラスの名前と競合するようなメッセージ・カタログ名は避けます。
クラス名に使用できる文字のみが含まれるメッセージ・カタログ名を使用します。
クラス名の命名規則に従います。
たとえば、カタログの名前がXyz.xml
の場合、生成されるクラス名はXyzLogLocalizer
およびXyzLogger
になります。
以下の考慮事項も、メッセージ・カタログ・ファイルに適用されます。
ログ・メッセージIDは、通常は先頭に0が付く6文字の文字列です。一部のインタフェースでは、整数表現もサポートされています。
シンプル・テキスト・カタログのメッセージIDは、任意の文字列値で構成できます。
Javaでは、パッケージと呼ばれるコレクションにクラスをまとめることができます。パッケージ名は、特定のカタログが存在するサブシステムの名前と一致させることをお薦めします。命名が一環していると、OSGiインポートの定義が容易になります。
ログのLocalizerクラスは、実際にはResourceBundle
プロパティ・ファイルです。
ログ・メッセージのメッセージ本文、メッセージ詳細、原因、およびアクションなどのセクションには、java.text.MessageFormat
に記載されているようなメッセージ引数を組み込むことができます。メッセージ・コンテンツがjava.text.MessageFormat
によって定義されているパターンに準拠していることを確認してください。
引数は、実行時に動的に設定される値を表します。これらの値はルーチン(メッセージを出力するためのルーチンなど)に渡されます。1つのメッセージには0 - 9で番号付けされた10個までの引数をサポートできます。メッセージ本文にはすべての引数を入れる必要がありますが、メッセージ定義(メッセージ本文、メッセージ詳細、妥当な原因)の任意のテキスト・セクションにもこれらの引数の任意のサブセットを入れることができます。
シンプル・テキスト・メッセージでは、引数を入れられるのは、メッセージ本文のセクションに限られます。
また、ログ・メッセージでは重大度レベルを割り当てる必要があります。ログ・メッセージはmethod属性で定義されているとおり、生成済のLoggerメソッドによって生成されます。
メッセージ引数は開発時にメッセージ定義に挿入され、実行時においてメッセージがログに記録されるときに適切なメッセージ・コンテンツに置き換えられます。
引数はString
型であるか、String
型として表現可能です。
数値データは{n,number}
として表されます。
日付は{n,date}
としてサポートされます。
次に、XMLログ・メッセージ定義の抜粋で、メッセージ引数の使用方法を示します。引数の番号は、method属性で指定された引数の1つと対応している必要があります。具体的には、{0}
は最初の引数と、{1}
は2番目の引数と対応している必要があります。次の例では、{0}
は開けないファイルを表し、{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)"
このメッセージの例では、2つの引数{0}
および{1}
が使用されています。
両方とも<messagebody>
で使用されています。
両方とも<messagedetail>
で使用されています。
どちらも<cause>
または<action>
では使用されていません。
最上位のカタログ・ファイルとロケール固有のカタログ・ファイルでは、カタログのフォーマットが異なります。最上位のカタログでは、ベース・ロケールのテキスト・メッセージが定義されます。ロケール固有のカタログは、最上位バージョンで定義されているテキストの翻訳のみを備えています。さらに、ログ・メッセージ・カタログではシンプル・テキスト・カタログと定義の方法が異なります。
ログ・メッセージ・カタログ
この例は、messagebody
、messagedetail
、cause
、およびaction
の各要素の使用方法を示すために1つのログ・メッセージを持つMyUtilLog.xml
メッセージ・カタログを示します。
<?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 </cause> the security log. <action> The user needs to gain approriate authorization or learn to live with the default settings. </action> </log_message> </message_catalog>
シンプル・テキスト・カタログ
この例は、1つのテキストが定義されているMyUtilLabels.xml
テキスト・カタログを示します。
<?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>
ロケール固有のカタログ
この例は、..\msgcat\fr\MyUtilLabels.xml
ファイルにあるメッセージのフランス語版です。
<?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エンコーディング方式が使用されます。
カタログ・サブディレクトリの名前は、小文字2文字のISO 639言語コード(日本語はja
、フランス語はfr
など)に基づいて付けられます。サポートされている言語コードは、java.util.Locale
Javadocで確認できます。
言語コードのバリエーションは、言語コードの下位にある大文字2文字のISO 3166国コードとバリアントを使用して実現できます。一般的な構文は、lang\country\variant
です。
たとえば、zh
は中国の言語コードです。CN
は簡体字中国語の国コードで、TW
は繁体字中国語の国コードです。このため、zh\CN
およびzh\TW
は中国語の異なる2つのロケールです。
バリアントは、特定のロケールを扱うプラットフォーム・ベンダーの機能に違いがある場合に役立ちます。ベンダー・バリアントには、WIN
、MAC
、POSIX
などがあります。ロケールをさらに修飾するために2つのバリアントが使用される場合もあります。この場合、バリアントはアンダースコアで区切ります(Traditional_Mac
とModern_MAC
など)。
注:
言語、国、およびバリアントは、すべて大文字/小文字が区別されます。
完全修飾ロケールはzh\TW\WIN
のようになり、Win32プラットフォームでの繁体字中国語を識別します。前述のロケールをサポートするメッセージ・カタログには、次のファイルが含まれます。
\*.xml
- デフォルト・カタログ
\zh\*.xml
- 中国語ローカライゼーション
\zh\TW\*.xml
- 繁体字中国語ローカライゼーション
\zh\TW\WIN\*.xml
- Win32コード・セットに対する繁体字中国語ローカライゼーション
特定のローカライゼーションは、親ローカライゼーションで定義されたすべてのメッセージに対応する必要はありません。
メッセージ・カタログのXMLファイルを作成した後、weblogic.i18ngen
ユーティリティを使用して、ログ・メッセージ内のテキストをローカライズするLogger
およびTextFormatter
クラスを作成します。weblogic.i18ngenユーティリティにより、メッセージIDのルックアップ・ハッシュ表weblogic.i18n.L10nLookup
をロードするi18n_user.properties
プロパティ・ファイルが作成または更新されます。
エラーや警告などのメッセージはすべてstderr
に送信されます。
ユーザー・カタログが認識されるように、i18n_user.properties
ファイルはOracle Stream Analyticsサーバー・クラス・パスで識別されたディレクトリに置く必要があります。i18n_user.properties
ファイルは、Oracle Stream Analyticsサーバー・クラス・パスに置くことをお薦めします。i18n_user.properties
ファイルがtargetdirectory
にある場合は、targetdirectory
がOracle Stream Analyticsサーバー・クラス・パスにある必要があります。
LoggerおよびTextFormatterクラスを生成するためのメッセージ・カタログの解析
次の手順は、Oracle Stream Analyticsサーバーで使用する、インターナショナライズされたメッセージを作成する方法を示します。
カタログ内のメッセージを定義して、最上位のログ・メッセージ・カタログまたはシンプル・テキスト・メッセージ・カタログを作成、または編集します。
メッセージ・テキストだけでなく、メッセージが格納するランタイム値の型と配置に関する情報も含みます。
weblogic.i18ngen
を実行して、手順1で作成または編集したカタログを検証し、Logger
およびTextFormatter
クラスを生成します。
java weblogic.i18ngen [options
] [filelist
]
生成されたクラスには、各メッセージで使用するメソッドが組み込まれています。このクラスは、メッセージ・カタログ・エントリで指定されたデータに従って定義されます。クラスには、カタログのタイプによって、メッセージ・テキストをロギングまたは取得するメソッドが組み込まれます。クラス名の末尾には、LoggerまたはTextFormatterが付きます。詳細は、「weblogic.i18ngenユーティリティ」を参照してください。
表12-1 weblogic.i18ngenユーティリティ・オプション
|
手順1で作成したメッセージ・カタログ用に、必要に応じてロケール固有カタログを作成します。
weblogic.l10ngen
を実行して、手順3で作成したロケール固有のカタログを処理します。
手順2で生成したLogger
またはTextFormatter
クラスを使用できるようにアプリケーションをコーディングします。
アプリケーションのMANIFEST.MF
ファイル内のOSGiインポート文を使用して、次のパッケージをOracle Stream Analyticsアプリケーションにインポートします。
weblogic.i18n.logging
weblogic.logging
アプリケーションがLogger
またはTextFormatter
メソッドの1つを呼び出してメッセージをログに記録するか戻すと、メッセージ・テキストのローカライズ・バージョンがターゲット・ロケーションに書き込まれます。Logger
メソッドはローカライズされたログ・ファイルにメッセージのローカライズ・バージョンを書き込み、TextFormatter
メソッドはメッセージのローカライズ・バージョンをディスプレイに書き込みます。
i18n_user.properties
ファイルがOracle Stream Analyticsサーバー・クラス・パスに配置されていることを確認してください。
weblogic.i18ngen
ユーティリティにより、メッセージIDのルックアップ・ハッシュ表weblogic.i18n.L10nLookup
をロードするi18n_user.properties
ファイルが生成されます。