shohaku.configutils
クラス XMLResourceBundle

java.lang.Object
  shohaku.configutils.XMLResourceBundle

すべての実装インタフェース:

ConfigurationResources

public class XMLResourceBundle

extends java.lang.Object

implements ConfigurationResources

XMLで定義されたプロパティを用いたリソースバンドルを実装します。

XMLリソースバンドルの特徴

XMLリソースバンドルには、ロケール固有のオブジェクトが含まれます。 プログラムで String などのロケール固有のリソースが必要なときは、 ユーザのロケールに合ったXMLリソースバンドルからロードできます。 このように、XMLリソースバンドルから、ロケール固有の情報のすべてでなくてもその大部分を切り離すことで、 ユーザのロケールにはほとんど依存しないプログラムコードを書くことができます。

これにより、以下の特徴を持つプログラムを書くことが可能になります。

• 異なる言語への地域対応、または翻訳が容易
• 複数のロケールを同時に処理可能
• 将来サポートするロケールを追加する際の修正が容易

この特徴は java.util.ResourceBundle と同様のものであり、 XMLリソースバンドルの設計は java.util.ResourceBundle の国際化モデルを継承しています。 大きな相違点は、 java.util.ResourceBundle が java.util.Properties を内部的に使用するのに対し、 XMLリソースバンドルは shohaku.configutils.XMLProperties をデータモデルに使用している点です。

この機能により java.util.ResourceBundle と同等の柔軟性と、 より複雑なデータ型と複雑な階層データモデルを利用して情報を外部ファイル化する事が出来ます。
XMLリソースバンドルは内部的に shohaku.configutils.XMLProperties を使用するため、 解析ルールを独自にカスタマイズすることが出来ます。
解析ルールの指定に関しては後記の「XMLリソースバンドル固有の名前規約」で説明します。

XMLリソースバンドルの基底名と各ロケールをファミリとして定義する名前規約に関しては java.util.ResourceBundle を参照してください。

XMLリソースバンドル固有の名前規約

XMLリソースバンドルには唯一 java.util.ResourceBundle とは別の名前規約が有ります。
XMLリソースバンドルでは基底名を基にして複数のファイルが読取の対象となるため、 同一の基底名に属すファイルは同一の解析ルールが摘要される必要があります。
よって基底名単位で解析ルールを指定する為の以下の配置規約が定義されています。

• 基底名単位で解析ルールを指定する場合のファイル名は '基底名 + _rule.properties' で指定します。

上記位置に配置しておけばシステムが自動で読み取ります, 配置されていなければデフォルトが使用されます。

XMLリソースバンドル固有の問題

XMLリソースバンドルは複数のデータ型に対応する一方で java.util.ResourceBundle と同様に、 上位階層から値が継承されるモデルを採用しているため、上位階層で定義される型とは別の型を下位の階層が定義する可能性が有ります。
この特徴はデータ型の管理を難しくする可能性があります。 この特徴を踏まえて設計および管理を行うことが推奨されます。
DTDファイルを作成して検証を行う、使用する解析ルールの型制約を厳しくする、ドキュメントレベルで厳密に規定する等、 何らかの補助を設ける事で回避することが出来ると考えます。

メソッドの概要

boolean	containsKey(java.lang.String key) 親のXMLリソースバンドルも検索対象として、 指定されたキーがプロパティセットに含まれている場合に true を返す。
boolean	containsKey(java.lang.String key, java.lang.Class type) 指定されたキーがプロパティセットに含まれていると同時に、 指定されたクラスとキャスト可能な関係に有る場合に true を返す。
static XMLResourceBundle	getBundle(java.lang.String baseName) 指定された基底名、デフォルトのロケール、および呼び出し側のクラスローダを使用して、 リソースバンドルを取得します。
static XMLResourceBundle	getBundle(java.lang.String baseName, java.lang.ClassLoader loader) 指定された基底名、クラスローダ、およびデフォルトのロケールを使用して、 リソースバンドルを取得します。
static XMLResourceBundle	getBundle(java.lang.String baseName, java.util.Locale locale) 指定された基底名、ロケール、および呼び出し側のクラスローダを使用して、 リソースバンドルを取得します。
static XMLResourceBundle	getBundle(java.lang.String baseName, java.util.Locale locale, java.lang.ClassLoader loader) 指定された基底名、ロケール、クラスローダを使用して、XMLリソースバンドルを取得します。
static shohaku.composer.CompositeRule	getDefaultComposeRule() デフォルトの構成ルールを返却します。
java.util.Locale	getLocale() ロケールを返却します。
java.lang.Object	getObject(java.lang.String key) プロパティ名が示す値を返却します。
java.lang.Object	getObject(java.lang.String key, java.lang.Object defaultValue) 指定された文字列型のキーが示す値を返却します。
java.lang.String	getString(java.lang.String key) プロパティ名が示す値をString型で返却します。
java.util.Iterator	keyIterator() 全てのプロパティ名を含む反復子を返却します。

クラス java.lang.Object から継承したメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

メソッドの詳細

keyIterator

public java.util.Iterator keyIterator()

全てのプロパティ名を含む反復子を返却します。

定義:

インタフェース ConfigurationResources 内の keyIterator

戻り値:

プロパティ名を含む反復子

関連項目:

ConfigurationResources.keyIterator()

getString

public java.lang.String getString(java.lang.String key)

プロパティ名が示す値をString型で返却します。 指定されたキーが存在しない場合Nullを返却します。

パラメータ:

key - プロパティ名

戻り値:

プロパティ名が示すObject

例外:

java.lang.NullPointerException - key が null の場合発生する

java.lang.ClassCastException - 取得された値が java.long.String でない場合発生する

getObject

public java.lang.Object getObject(java.lang.String key)

プロパティ名が示す値を返却します。 指定されたキーが存在しない場合Nullを返却します。

定義:

インタフェース ConfigurationResources 内の getObject

パラメータ:

key - プロパティ名

戻り値:

プロパティ名が示すObject

例外:

java.lang.NullPointerException - key が null の場合発生する

関連項目:

ConfigurationResources.getObject(java.lang.String)

getObject

public java.lang.Object getObject(java.lang.String key,
                                  java.lang.Object defaultValue)

指定された文字列型のキーが示す値を返却します。 指定されたキーが存在しない場合 defaultValue を返却します。

定義:

インタフェース ConfigurationResources 内の getObject

パラメータ:

key - プロパティキー

defaultValue - プロパティキー

戻り値:

プロパティキーが示す値

例外:

java.lang.NullPointerException - key が null の場合発生する

関連項目:

ConfigurationResources.getObject(java.lang.String, java.lang.Object)

containsKey

public boolean containsKey(java.lang.String key)

親のXMLリソースバンドルも検索対象として、 指定されたキーがプロパティセットに含まれている場合に true を返す。

定義:

インタフェース ConfigurationResources 内の containsKey

パラメータ:

key - プロパティキー

戻り値:

指定されたキーが含まれている場合 true

例外:

java.lang.NullPointerException - key が null の場合発生する

関連項目:

ConfigurationResources.containsKey(java.lang.String)

containsKey

public boolean containsKey(java.lang.String key,
                           java.lang.Class type)

指定されたキーがプロパティセットに含まれていると同時に、 指定されたクラスとキャスト可能な関係に有る場合に true を返す。 値がNullの場合キャスト可能(True)を返却します。

定義:

インタフェース ConfigurationResources 内の containsKey

パラメータ:

key - プロパティキー

type - キャスト可能な関係に有るか検証するクラス

戻り値:

指定されたキーが含まれている場合 true

例外:

java.lang.NullPointerException - key または type が null の場合発生する

関連項目:

ConfigurationResources.containsKey(java.lang.String, java.lang.Class)

getLocale

public java.util.Locale getLocale()

ロケールを返却します。

戻り値:

ロケール

getBundle

public static XMLResourceBundle getBundle(java.lang.String baseName)

指定された基底名、デフォルトのロケール、および呼び出し側のクラスローダを使用して、 リソースバンドルを取得します。このメソッドを呼び出すことは、次を呼び出すことと同じです。 getBundle(baseName, Locale.getDefault(), XMLResourceBundle.class.getClassLoader()) getClassLoader() が、XMLResourceBundle のセキュリティ特権により実行されることのみが異なります。 検索とインスタンス生成方法の詳細については、getBundle を参照してください。

パラメータ:

baseName - 基底名

戻り値:

指定された基底名とデフォルトのロケールのXMLリソースバンドル

例外:

java.util.MissingResourceException - 指定された基底名のリソースバンドルが見つからない場合

getBundle

public static XMLResourceBundle getBundle(java.lang.String baseName,
                                          java.lang.ClassLoader loader)

指定された基底名、クラスローダ、およびデフォルトのロケールを使用して、 リソースバンドルを取得します。このメソッドを呼び出すことは、次を呼び出すことと同じです。 getBundle(baseName, Locale.getDefault(), loader) getClassLoader() が、 XMLResourceBundle のセキュリティ特権により実行されることのみが異なります。 検索とインスタンス生成方法の詳細については、getBundle を参照してください。

パラメータ:

baseName - 基底名

loader - リソースのロード元のクラスローダ

戻り値:

指定された基底名とロケールのXMLリソースバンドル

例外:

java.util.MissingResourceException - 指定された基底名のリソースバンドルが見つからない場合

getBundle

public static XMLResourceBundle getBundle(java.lang.String baseName,
                                          java.util.Locale locale)

指定された基底名、ロケール、および呼び出し側のクラスローダを使用して、 リソースバンドルを取得します。このメソッドを呼び出すことは、次を呼び出すことと同じです。 getBundle(baseName, locale, XMLResourceBundle.class.getClassLoader()) getClassLoader() が、XMLResourceBundle のセキュリティ特権により実行されることのみが異なります。 検索とインスタンス生成方法の詳細については、getBundle を参照してください。

パラメータ:

baseName - 基底名

locale - ロケール

戻り値:

指定された基底名とロケールのXMLリソースバンドル

例外:

java.util.MissingResourceException - 指定された基底名のリソースバンドルが見つからない場合

getBundle

public static XMLResourceBundle getBundle(java.lang.String baseName,
                                          java.util.Locale locale,
                                          java.lang.ClassLoader loader)

指定された基底名、ロケール、クラスローダを使用して、XMLリソースバンドルを取得します。

理論的には、 getBundle では次の方法を使用して、XMLリソースバンドルの検出および生成を行います。

getBundle は、基底名、指定されたロケール、 およびデフォルトのロケール (Locale.getDefault から取得したロケール) を使用して、 候補のバンドル名 のシーケンスを生成します。 指定されたロケールの言語、国、およびバリアントがすべて空の文字列の場合、基底名は候補のバンドル名のみになります。 それ以外の場合には、指定したロケール (language1、country1、variant1) およびデフォルトのロケール (language2、country2、variant2) の属性値から、次のシーケンスが生成されます。

• baseName + "_" + language1 + "_" + country1 + "_" + variant1
• baseName + "_" + language1 + "_" + country1
• baseName + "_" + language1
• baseName + "_" + language2 + "_" + country2 + "_" + variant2
• baseName + "_" + language2 + "_" + country2
• baseName + "_" + language2
• baseName

最終コンポーネントが空の文字列の場合、候補のバンドル名は省略されます。 たとえば、country1 が空の文字列の場合、2 番目の候補のバンドル名は省略されます。

getBundle は実際のXMLリソースバンドルを「インスタンス化」できる最初の名前を見つけるために、 候補のバンドル名を繰り返し処理します。各候補バンドル名ごとに、XMLリソースバンドルを次のように作成しようとします。

• まず、候補のバンドル名を使用して、クラスをロードしようとします。 指定したクラスローダを使用して、XMLプロパティリソースファイルを見つけようとします。 すべての「。」文字を「/」文字に置き換え、「。xml」文字列を追加して、候補のバンドル名からパス名を生成します。 ClassLoader.getResource を使用して、この名前の「リソース」を見つけようとします (getResource の「リソース」とは、XMLリソースバンドルのコンテンツとは無関係であり、 ファイルなどのデータのコンテナにすぎません). 「リソース」を見つけた場合、リソースのコンテンツから新しい XMLResourceBundle インスタンスを作成します。

XMLリソースバンドルが見つからない場合、 MissingResourceException がスローされます。

XMLリソースバンドルが見つかったときは、その親連鎖をインスタンス化します。 getBundle は候補のバンドル名を繰り返し処理します。 このバンドル名は、XMLリソースバンドルのバンドル名からバリアント、国、および言語を (前に「_」についたものに関して毎回) 連続して削除することによって、取得します。 上述のように、最終コンポーネントが空の文字列である場合、候補のバンドル名は省略されます。 各候補のバンドル名により、上述のように、XMLリソースバンドルをインスタンス化しようとします。 インスタンスに成功した場合は常に、前にインスタント化したXMLリソースバンドルに null 以外の親XMLリソースバンドルがない場合は、 前にインスタンス化したXMLリソースバンドルの setParent メソッドを新しいXMLリソースバンドルにより呼び出します。

getBundle の実装はインスタンス化したXMLリソースバンドルをキャッシュし、 同じXMLリソースバンドルのインスタンスを複数回返します。 こうした実装では、XMLリソースバンドルおよびその親連鎖の選択が上述のものと互換性がある限り、 XMLリソースバンドルをインスタンス化するシーケンスを変更する場合もあります。

baseName 引数は完全指定のクラス名である必要があります。

例: XMLプロパティファイル、MyResources.xml、MyResources_fr_CH.xml、MyResources_fr.xml、MyResources_en.xml、が提供されています。 すべてのファイルのコンテンツが有効です。 デフォルトのロケールは Locale("en", "UK") です。

表示されたロケール引数値を持つ getBundle の呼び出しは、次のソースからXMLリソースバンドルをインスタンス化します。

• Locale("fr", "CH"): result MyResources_fr_CH.xml, parent MyResources_fr.xml, parent MyResources.xml
• Locale("fr", "FR"): result MyResources_fr.xml, parent MyResources.xml
• Locale("de", "DE"): result MyResources_en.xml, parent MyResources.xml
• Locale("en", "US"): result MyResources_en.xml, parent MyResources.xml

パラメータ:

baseName - 基底名

locale - ロケール

loader - リソースのロード元のクラスローダ

戻り値:

指定された基底名とロケールのXMLリソースバンドル

例外:

java.util.MissingResourceException - 指定された基底名のリソースバンドルが見つからない場合

getDefaultComposeRule

public static shohaku.composer.CompositeRule getDefaultComposeRule()

デフォルトの構成ルールを返却します。

戻り値:

デフォルトの構成ルール