4 WebLogic Serverでのメッセージ・カタログの使い方

以下の節では、メッセージ・カタログとその使い方について説明します。

• メッセージ・カタログの概要

• メッセージ・カタログの階層

• メッセージ・カタログの命名のガイドライン

• メッセージ引数の使い方

• メッセージ・カタログのフォーマット

メッセージ・カタログの概要

メッセージ・カタログは、テキスト・メッセージのコレクションが格納される単一のXMLファイルです。ビルド処理中にweblogic.i18ngenを使用してこれらのXMLファイルをクラスにコンパイルします。(詳細は、「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つのカタログを作成することをお薦めします。第6章「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要素

• log_message要素

• log_message要素の子要素

message_catalog要素

message_catalog要素は、ログ・メッセージ・カタログを表します。次の表では、message_catalog要素で定義できる各属性について説明します。

属性	デフォルト値	必須/オプション	説明
i18n_package	weblogic.i18n	オプション	このカタログのLoggerクラスを含むJavaパッケージ。クラスの名前はカタログ・ファイルの名前に基づいて付けられます。たとえば、カタログの名前がmycat.xmlの場合、生成されるLoggerクラスの名前は<i18n_package>.mycatLogger.classになります。 構文:標準のJavaパッケージ構文 例: i18n_package="programs.utils"
l10n_package	weblogic.i18n	オプション	カタログのLogLocalizerプロパティを含むJavaパッケージ。たとえば、カタログの名前がmycat.xmlの場合は、<l10n_package>.mycatLogLocalizer.propertiesおよび<l10n_package>mycatLogLocalizerDetail.propertiesという名前のプロパティ・ファイルが生成されます。 構文:標準のJavaパッケージ構文 例: l10n_package="programs.utils"
subsystem	なし	必須	このカタログと関連付けられているサブシステムを識別する頭字語。サブシステムの名前はサーバー・ログに含まれ、メッセージの分離を目的として使用されます。 構文:文字列 例: subsystem="MYUTIL"
version	なし	必須	使用されるmsgcat.dtdのバージョンを指定します。 使用方法: 「1.0」である必要があります。 構文: x.y (xおよびyは数値) 例: version="1.0"
baseid	000000 : WebLogic Serverカタログ 500000 :ユーザー定義のカタログ	オプション	このカタログで使用される最低のメッセージIDを指定します。 構文: 1桁から6桁の数値。 例: baseid="600000"
endid	499999 : WebLogic Serverカタログ 999999 :ユーザー定義のカタログ	オプション	このカタログで使用される最高のメッセージIDを指定します。 構文: 1桁から6桁の数値。 例: endid="600100"
loggable	false	オプション	Loggableオブジェクトを返す追加メソッドを生成するかどうかを示します。 構文: "true"または"false" 例: loggable="true"
prefix	ユーザー定義のカタログの場合はNull WebLogic Serverカタログの場合は「BEA」	オプション	ログに記録されるときにメッセージIDの先頭に追加する文字列を指定します。サーバー・メッセージは、接頭辞のデフォルトは「BEA」で、別の接頭辞を指定することはできません。ユーザー・メッセージは、任意の接頭辞を指定することが可能です。接頭辞が付いたメッセージIDは、ログ・エントリで次のように表示されます。 <[prefix-]id> ここで、prefixはこの属性であり、idは特定のメッセージに関連付けられた6桁のメッセージID。 たとえば、prefixが「XYZ」の場合、メッセージ987654はログ・エントリでは<XYZ-987654>として表示されます。接頭辞が定義されていない場合、ログ・エントリは<987654>となります。 構文:任意の文字列(5文字まで) 例: prefix="BEA"
description	Null(説明なし)	オプション	カタログの内容を説明するオプションな属性。 構文:任意の文字列 例: description="Contains messages logged by the foobar application"

log_message要素

次の表では、log_message要素で定義できる各属性について説明します。

属性	デフォルト値	必須/オプション	説明
messageid	なし	必須	このログ・メッセージの一意の識別子。識別子は、すべてのカタログにわたり一意である必要があります。値は、baseid属性とendid属性で定義された範囲で指定する必要があります。 使用方法:値は、message_catalog属性のbaseid属性とendid属性で定義された範囲で指定する必要があります。 構文: 1桁から6桁の数値。 例: messageid="600001"
datelastchanged	なし	オプション	このメッセージの修正管理に使用される日付と時刻のスタンプ。日付は、カタログで動作するユーティリティによって提供されます。 構文: Long.toString(new Date().getTime()); 使用方法:日付は、カタログで動作するユーティリティ(メッセージ・エディタなど)によって提供されます。 構文: Long.toString(new Date().getTime());
severity	なし	必須	ログ・メッセージの重大度を示します。値は、debug、info、warning、error、notice、critical、alert、またはemergencyのいずれかである必要があります。ユーザー定義のカタログで使用できるのは、debug、info、warning、およびerrorに限られる場合があります。 例: severity="warning"
method	なし	必須	このメッセージをログに記録するためのメソッド・シグネチャ。 構文は標準のJavaメソッド・シグネチャから修飾子、セミコロン、および拡張子を除いたもの。引数の型にはJavaプリミティブまたはJavaクラスを使用できます。クラスはjava.langにない場合は完全修飾である必要があります。また、クラスはjava.text.MessageFormatの規約に準拠している必要があります。たいていの場合、クラス引数は便利なtoString()メソッドを備えています。 引数には有効であればどのような名前でも指定できますが、argn (nは0 - 9)の規約に従っている必要があります。指定できる引数は10個まで。各argnについて、「log_message要素の子要素」で説明されているテキスト要素に少なくとも1つの対応するプレースホルダーが存在している必要があります。プレースホルダーの形式は{n}、{n,number}または{n,date}です。
methodtype	logger	オプション	生成するメソッドのタイプを指定します。メソッドは、LoggerまたはGetterのいずれかです。Loggerメソッドは、メッセージ本文をデフォルトのロケールにフォーマットし、結果をログに記録します。Getterメソッドは、[susbsystem:msgid]textのように、メッセージ本文の前にサブシステムおよびメッセージIDを付けて返します。 構文:値は、「logger」および「getter」
stacktrace	true	オプション	Throwableの引数としてスタック・トレースを生成するかどうかを示します。trueまたはfalseを指定できます。値がtrueの場合はトレースが生成されます。 構文: stacktrace="true"
retired	false	オプション	メッセージがリタイアされているかどうかを示します。リタイアされたメッセージとは、前のリリースで使用されていたが、今は古くなり、現在のバージョンでは使用されないメッセージです。リタイアされたメッセージは、クラスまたはリソースの生成で使用しません。 構文:値は、trueおよびfalse 例: retired="true"

log_message要素の子要素

次の表では、log_message要素の子要素を説明します。

要素	親要素	必須/オプション	説明
messagebody	log_message	必須	このメッセージの短い説明。 messagebody要素では、0から10のプレースホルダー{n}を使用できます。プレースホルダーは、ログ・メッセージがローカライズされるときに適切な引数で置き換えられます。 最後の引数がThrowableまたはサブクラスでない場合、メッセージ本文には、対応するメソッド属性にリストされたすべての引数に対するプレースホルダーを含める必要があります。 一重引用符は、java.text.MessageFormatによって特別に解析されるため、使用は慎重に行います。メッセージ引数に引用符を付けた方がよい場合は、(下記の例のように)二重引用符を使用します。メッセージが1つ以上のプレースホルダーを持つ場合、一重引用符が正しく表示されるようにするには(たとえば、アポストロフィとして)、もう1つ一重引用符を付ける必要があります。 構文:文字列 例: <messagebody>Could not open file "{0}" created on {1,date}.</messagebody>
messagedetail	log_message	オプション	イベントの詳しい説明。この要素には、任意の引数のプレースホルダーを含めることができます。 構文:文字列 例: <messagedetail>The configuration for this application will be defaulted to factory settings.</messagedetail>
cause	log_message	オプション	問題の根本的な原因。この要素には、任意の引数のプレースホルダーを含めることができます。 構文:文字列 例: <cause>The user is not authorized to use custom configurations.The attempt has been logged to the security log.</cause>
action	log_message	オプション	適切な解決策。この要素には、任意の引数のプレースホルダーを含めることができます。 構文:文字列 例: <action>The user needs to gain appropriate authorization or learn to live with the default settings.</action>

シンプル・テキスト・カタログの例

次の例は、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要素

• message要素

• messagebody要素

message_catalog要素

次の表では、message_catalog要素で定義できる各属性について説明します。

属性	デフォルト値	必須/オプション	説明
l10n_package	weblogic.i18n	オプション	このカタログに生成されたTextFormatterクラスおよびTextLocalizerプロパティを含むJavaパッケージ。クラスの名前はカタログ・ファイルの名前に基づいて付けられます。カタログ・ファイルの名前がmycat.xmlの場合は、<l10n_package>.mycatLogLocalizer.propertiesという名前のプロパティ・ファイルが生成されます。 構文:標準のJavaパッケージ構文 例: l10n_package="programs.utils"
subsystem	なし	必須	このカタログと関連付けられているサブシステムを識別する頭字語。サブシステムの名前はサーバー・ログに含まれ、メッセージの分離を目的として使用されます。 構文:文字列 例: subsystem="MYUTIL"
version	なし	必須	使用されるmsgcat.dtdのバージョンを指定します。書式はn.nで、たとえばversion="1.0"のように定義します。"1.0"以上である必要があります。 例: version="1.0"
description	Null	オプション	カタログの内容を説明する省略可能な属性。 構文:文字列 例: description="Contains labels used in the foobar GUI"

message要素

次の表では、message要素で定義できる各属性について説明します。

属性	デフォルト値	必須/オプション	説明
messageid	なし	必須	このログ・メッセージの一意の識別子(英数字の文字列)。一意性はこのカタログのコンテキスト内でのみ必須です。messageはmessage_catalogの子要素です。
datelastchanged	なし	オプション	このメッセージの修正の管理に便利な日付と時刻のスタンプ。
method	なし	オプション	このメッセージをフォーマットするためのメソッド・シグネチャ。 構文は標準のJavaメソッド・シグネチャから戻り値の型、修飾子、セミコロン、および拡張子を除いたもの。戻り値の型は常にStringです。引数の型にはJavaプリミティブまたはJavaクラスを使用できます。クラスはjava.langにない場合は完全修飾である必要があります。また、クラスはjava.text.MessageFormatの規約に準拠している必要があります。たいていのクラス引数は便利なtoString()メソッドを備えており、対応するMessageFormatプレースホルダーは文字列である必要があります(つまり{n}の形式)。引数には有効であればどのような名前でも指定できます。指定できる引数は10個までです。 各引数について、次に説明するmessagebody要素に少なくとも1つの対応するプレースホルダーが存在する必要があります。プレースホルダーの形式は{n}、{n,number}、または{n,date}です。 例: method="getNoAuthorization (String filename, java.util.Date creDate)" この例は、次のようにTextFormatterクラスのメソッドになります。 public String getNoAuthorization (String filename, java.util.Date creDate)

messagebody要素

次の表では、message要素の子要素を説明します。

要素	親要素	必須/オプション	説明
messagebody	message	必須	メッセージと関連付けられたテキスト。 この要素では、0個以上のプレースホルダー{n}を使用できます。プレースホルダーは、ログ・メッセージがローカライズされるときに適切な引数で置き換えられます。

ロケール固有のカタログの例

次の例は、...\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要素

• log_message要素

• その他のlocale_message_catalog要素

locale_message_catalog要素

次の表では、locale_message_catalog要素で定義できる各属性について説明します。

属性	デフォルト値	必須/オプション	説明
l10n_package	weblogic.i18n	オプション	このカタログに対して生成されたLogLocalizerまたはTextLocalizerプロパティを含むJavaパッケージ。プロパティ・ファイルの名前はカタログ・ファイル名に基づいて設定されます。 たとえば、mycat.xmlという名前のフランス語版のログ・メッセージ・カタログでは、プロパティ・ファイルは<l10n_package>.mycatLogLocalizer_fr_FR.propertiesとなります。
version	None	必須	使用されるmsgcat.dtdのバージョンを指定します。書式はn.nで、たとえばversion="1.0"のように定義します。"1.0"以上である必要があります。

log_message要素

ロケール固有のカタログでは、最上位のログ・メッセージ・カタログのlog_message要素で定義された属性が使用されるため、この要素は改めて定義する必要はありません。

その他のlocale_message_catalog要素

ロケール固有のカタログでは、最上位のログ・メッセージ・カタログで定義されたmessagebody、messagedetail、cause、およびactionの各カタログ要素を使用するため、これらの要素を改めて定義する必要はありません。