JavaTM Platform
Standard Ed. 6

java.util
クラス ResourceBundle.Control

java.lang.Object
  上位を拡張 java.util.ResourceBundle.Control
含まれているクラス:
ResourceBundle

public static class ResourceBundle.Control
extends Object

ResourceBundle.Control は、バンドルロード処理中に ResourceBundle.getBundle ファクトリメソッドによって呼び出される一連のコールバックメソッドを定義します。つまり、ResourceBundle.Control は、リソースバンドルのロード時にファクトリメソッドと連携して動作します。コールバックメソッドのデフォルト実装は、ファクトリメソッドがデフォルト動作を実行するために必要な情報を提供します。

コールバックメソッドのほかに、toBundleName および toResourceName メソッドも定義されています。これらの主な目的は、コールバックメソッドの実装を支援することです。ただし、toBundleName メソッドをオーバーライドすれば、ローカライズ済みリソースの構成やパッケージ化に関する異なる規約を提供できます。toResourceName メソッドが final になっているのは、リソース名やクラス名の区切り文字の誤用を回避するためです。

2 つのファクトリメソッド getControl(List)getNoFallbackControl(List) は、デフォルトのバンドルロード処理の一般的なバリエーションを実装した ResourceBundle.Control インスタンスを提供します。

getFormats メソッドから返される形式と getCandidateLocales メソッドから返される候補ロケールは、同じ基底バンドルに対するすべての ResourceBundle.getBundle 呼び出しで一貫性のあるものでなければいけません。そうでないと、ResourceBundle.getBundle メソッドが想定外のバンドルを返す可能性があります。たとえば、ResourceBundle.getBundle の初回呼び出し時に getFormats メソッドから「java.class」のみが返され、2 回目の呼び出し時に「java.properties」のみが返された場合、その 2 回目の呼び出しでは、初回呼び出し時にキャッシュに格納されたクラスベースのバンドルが返されます。

複数のスレッドが同時に使用する ResourceBundle.Control インスタンスは、スレッドに対して安全でなければいけません。ResourceBundle.getBundle は、ResourceBundle.Control のメソッドを呼び出す際に同期処理を行いません。これらのメソッドのデフォルト実装は、スレッドに対して安全です。

アプリケーションは、getControl ファクトリメソッドから返された ResourceBundle.Control インスタンスを指定することもできますし、ResourceBundle.Control のサブクラスから作成されたインスタンスを指定してバンドルロード処理をカスタマイズすることもできます。デフォルトのバンドルロード処理を変更する例を、次に示します。

プログラム例 1

次のコードの場合、ResourceBundle.getBundle はプロパティーベースのリソースのみを検索します。

 import java.util.*;
 import static java.util.ResourceBundle.Control.*;
 ...
 ResourceBundle bundle =
   ResourceBundle.getBundle("MyResources", new Locale("fr", "CH"),
                            ResourceBundle.Control.getControl(FORMAT_PROPERTIES));
 
ResourceBundle.getBundle の説明のに含まれるリソースバンドルが与えられた場合、この ResourceBundle.getBundle 呼び出しによって MyResources_fr_CH.properties がロードされます。そして、その親は MyResources_fr.properties になり、さらにその親は MyResources.properties になります。(MyResources_fr_CH.properties は隠されないが、MyResources_fr_CH.class は隠される。)

プログラム例 2

Properties.loadFromXML を使って XML ベースのバンドルをロードする例を、次に示します。

 ResourceBundle rb = ResourceBundle.getBundle("Messages",
     new ResourceBundle.Control() {
         public List<String> getFormats(String baseName) {
             if (baseName == null)
                 throw new NullPointerException();
             return Arrays.asList("xml");
         }
         public ResourceBundle newBundle(String baseName,
                                         Locale locale,
                                         String format,
                                         ClassLoader loader,
                                         boolean reload)
                          throws IllegalAccessException,
                                 InstantiationException,
                                 IOException {
             if (baseName == null || locale == null
                   || format == null || loader == null)
                 throw new NullPointerException();
             ResourceBundle bundle = null;
             if (format.equals("xml")) {
                 String bundleName = toBundleName(baseName, locale);
                 String resourceName = toResourceName(bundleName, format);
                 InputStream stream = null;
                 if (reload) {
                     URL url = loader.getResource(resourceName);
                     if (url != null) {
                         URLConnection connection = url.openConnection();
                         if (connection != null) {
                             // キャッシュを無効にすることで、再ロード用の最新データを
                             // 取得できるようにします。
                             connection.setUseCaches(false);
                             stream = connection.getInputStream();
                         }
                     }
                 } else {
                     stream = loader.getResourceAsStream(resourceName);
                 }
                 if (stream != null) {
                     BufferedInputStream bis = new BufferedInputStream(stream);
                     bundle = new XMLResourceBundle(bis);
                     bis.close();
                 }
             }
             return bundle;
         }
     });

 ...

 private static class XMLResourceBundle extends ResourceBundle {
     private Properties props;
     XMLResourceBundle(InputStream stream) throws IOException {
         props = new Properties();
         props.loadFromXML(stream);
     }
     protected Object handleGetObject(String key) {
         return props.getProperty(key);
     }
     public Enumeration<String> getKeys() {
         ...
     }
 }
 

導入されたバージョン:
1.6

フィールドの概要
static List<String> FORMAT_CLASS
          クラスのみの形式の List
static List<String> FORMAT_DEFAULT
          デフォルトの形式の List
static List<String> FORMAT_PROPERTIES
          プロパティーのみの形式の List
static long TTL_DONT_CACHE
          ロードされたリソースバンドルインスタンスをキャッシュしないための有効期間定数。
static long TTL_NO_EXPIRATION_CONTROL
          キャッシュ内のロード済みリソースバンドルインスタンスの有効期限制御を無効にするための有効期間定数。
 
コンストラクタの概要
protected ResourceBundle.Control()
          唯一のコンストラクタです。
 
メソッドの概要
 List<Locale> getCandidateLocales(String baseName, Locale locale)
          baseNamelocale に対する候補ロケールとして、LocaleList を返します。
static ResourceBundle.Control getControl(List<String> formats)
          getFormats メソッドが指定された formats を返すような、ResourceBundle.Control を返します。
 Locale getFallbackLocale(String baseName, Locale locale)
          ResourceBundle.getBundle ファクトリメソッドがリソースバンドルをさらに検索する際のフォールバックロケールとして使用すべき Locale を返します。
 List<String> getFormats(String baseName)
          指定された baseName のリソースバンドルをロードする際に使用すべき形式が格納された、StringList を返します。
static ResourceBundle.Control getNoFallbackControl(List<String> formats)
          getFormats メソッドが指定された formats を返し、かつ getFallbackLocale メソッドが null を返すような、ResourceBundle.Control を返します。
 long getTimeToLive(String baseName, Locale locale)
          この ResourceBundle.Control の下でロードされたリソースバンドルの有効期間 (TTL) 値を返します。
 boolean needsReload(String baseName, Locale locale, String format, ClassLoader loader, ResourceBundle bundle, long loadTime)
          キャッシュ内で有効期限の切れた bundle を再ロードする必要があるかどうかを、loadTime に指定されたロード時刻やその他のいくつかの条件に基づいて判定します。
 ResourceBundle newBundle(String baseName, Locale locale, String format, ClassLoader loader, boolean reload)
          指定された形式とロケールを持つ指定されたバンドル名のリソースバンドルを、指定されたクラスローダーを必要に応じて使用してインスタンス化します。
 String toBundleName(String baseName, Locale locale)
          指定された baseNamelocale をバンドル名に変換します。
 String toResourceName(String bundleName, String suffix)
          指定された bundleName を、ClassLoader.getResource メソッドが要求する形式に変換します。
 
クラス java.lang.Object から継承されたメソッド
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

フィールドの詳細

FORMAT_DEFAULT

public static final List<String> FORMAT_DEFAULT
デフォルトの形式の List。文字列「java.class」「java.properties」をこの順番で含みます。この List変更不可能 です。

関連項目:
getFormats(String)

FORMAT_CLASS

public static final List<String> FORMAT_CLASS
クラスのみの形式の List「java.class」を含みます。この List変更不可能です。

関連項目:
getFormats(String)

FORMAT_PROPERTIES

public static final List<String> FORMAT_PROPERTIES
プロパティーのみの形式の List「java.properties」を含みます。この List変更不可能です。

関連項目:
getFormats(String)

TTL_DONT_CACHE

public static final long TTL_DONT_CACHE
ロードされたリソースバンドルインスタンスをキャッシュしないための有効期間定数。

関連項目:
getTimeToLive(String, Locale), 定数フィールド値

TTL_NO_EXPIRATION_CONTROL

public static final long TTL_NO_EXPIRATION_CONTROL
キャッシュ内のロード済みリソースバンドルインスタンスの有効期限制御を無効にするための有効期間定数。

関連項目:
getTimeToLive(String, Locale), 定数フィールド値
コンストラクタの詳細

ResourceBundle.Control

protected ResourceBundle.Control()
唯一のコンストラクタです。サブクラスのコンストラクタによる呼び出し用で、通常は暗黙的に呼び出されます。

メソッドの詳細

getControl

public static final ResourceBundle.Control getControl(List<String> formats)
getFormats メソッドが指定された formats を返すような、ResourceBundle.Control を返します。formats は、FORMAT_PROPERTIESFORMAT_CLASSFORMAT_DEFAULT のいずれかと等しくなります。このメソッドが返す ResourceBundle.Control インスタンスは単独であり、スレッドに対して安全です。

FORMAT_DEFAULT を指定することは、ResourceBundle.Control クラスをインスタンス化することと等価です。ただし、このメソッドが単独オブジェクトを返す点だけは異なります。

パラメータ:
formats - ResourceBundle.Control.getFormats メソッドから返されるべき形式
戻り値:
指定された formats をサポートする ResourceBundle.Control
例外:
NullPointerException - formatsnull の場合
IllegalArgumentException - formats が不明な場合

getNoFallbackControl

public static final ResourceBundle.Control getNoFallbackControl(List<String> formats)
getFormats メソッドが指定された formats を返し、かつ getFallbackLocale メソッドが null を返すような、ResourceBundle.Control を返します。formats は、FORMAT_PROPERTIESFORMAT_CLASSFORMAT_DEFAULT のいずれかと等しくなります。このメソッドが返す ResourceBundle.Control インスタンスは単独であり、スレッドに対して安全です。

パラメータ:
formats - ResourceBundle.Control.getFormats メソッドから返されるべき形式
戻り値:
指定された formats をサポートし、フォールバック Locale をサポートしない ResourceBundle.Control
例外:
NullPointerException - formatsnull の場合
IllegalArgumentException - formats が不明な場合

getFormats

public List<String> getFormats(String baseName)
指定された baseName のリソースバンドルをロードする際に使用すべき形式が格納された、StringList を返します。ResourceBundle.getBundle ファクトリメソッドは、このリスト内の形式を持つリソースバンドルを、リスト内に指定された順番でロードしようとします。このメソッドから返されたリストには、少なくとも 1 つの String が含まれていなければいけません。定義済みの形式は、クラスベースのリソースバンドル用の「java.class」と、プロパティーベース のリソースバンドル用の「java.properties」です。「java.」で始まる文字列は、将来の拡張用として予約されているため、アプリケーション定義形式では使用しないでください。

不変の (変更不可能な) List を返す必要は、必ずしもありません。ただし、ListgetFormats から返されたあとで、そのリストを変更してはいけません。

デフォルト実装は FORMAT_DEFAULT を返しますが、これは、ResourceBundle.getBundle ファクトリメソッドがまずクラスベースのリソースバンドルを検索し、次にプロパティーベースのバンドルを検索するようにするためです。

パラメータ:
baseName - リソースバンドルの基底名。完全指定クラス名
戻り値:
リソースバンドルをロードするための形式が格納された、StringList
例外:
NullPointerException - baseName が null の場合
関連項目:
FORMAT_DEFAULT, FORMAT_CLASS, FORMAT_PROPERTIES

getCandidateLocales

public List<Locale> getCandidateLocales(String baseName,
                                        Locale locale)
baseNamelocale に対する候補ロケールとして、LocaleList を返します。このメソッドは、ターゲット Locale のリソースバンドルの検索を ResourceBundle.getBundle ファクトリメソッドが試みるたびに、そのファクトリメソッドによって呼び出されます。

候補ロケールに対応するリソースバンドルが存在しており、それらのロード済みリソースバンドル自体には親が定義されていない場合、候補ロケールのシーケンスは、実行時リソース検索パス (「親連鎖」とも呼ばれる) にも対応します。基底バンドルを親連鎖の終端にする必要がある場合、このリストの最後の要素は ルートロケール でなければいけません。

指定されたロケールが Locale.ROOT (ルートロケール) に等しい場合、ルートの Locale だけを含む List が返されます。この場合、ResourceBundle.getBundle ファクトリメソッドは、結果として得られるリソースバンドルとして基底バンドルだけをロードします。

不変の (変更不可能な) List を返す必要は、必ずしもありません。ただし、ListgetCandidateLocales から返されたあとで、そのリストを変更してはいけません。

デフォルト実装は、Locale が次の順番で格納された List を返します。

     Locale(language, country, variant)
     Locale(language, country)
     Locale(language)
     Locale.ROOT
 
ここで、languagecountryvariant はそれぞれ、指定された locale の言語、国、バリアントの値になります。最後の要素の値が空文字列であるようなロケールは、省略されます。

デフォルト実装は ArrayList を使用しますが、これは、オーバーライドした実装内で、呼び出し元に返される前に変更することができます。ただし、getCandidateLocales から返されたあとでサブクラス内で変更してはいけません。

たとえば、指定された baseName が「Messages」であり、指定された localeLocale("ja", "", "XX") であった場合、返される LocaleList は、

     Locale("ja", "", "XX")
     Locale("ja")
     Locale.ROOT
 
のようになります。そして、「ja」と「」の Locale に対するリソースバンドルが見つかった場合、実行時リソース検索パス (親連鎖) は次のようになります。
     Messages_ja -> Messages
 

パラメータ:
baseName - リソースバンドルの基底名。完全指定クラス名
locale - リソースバンドルが必要なロケール
戻り値:
指定された locale に対する候補 LocaleList
例外:
NullPointerException - baseName または localenull の場合

getFallbackLocale

public Locale getFallbackLocale(String baseName,
                                Locale locale)
ResourceBundle.getBundle ファクトリメソッドがリソースバンドルをさらに検索する際のフォールバックロケールとして使用すべき Locale を返します。このメソッドは、baseNamelocale に対応する結果リソースバンドルが 1 つも見つからない状況が発生するたびに、ファクトリメソッドによって呼び出されます。ここで、そのロケールは、ResourceBundle.getBundle のパラメータ、このメソッドから以前に返されたフォールバックロケールのいずれかになります。

このメソッドは、さらなるフォールバック検索が必要ない場合に null を返します。

デフォルト実装は、指定された locale がデフォルトのロケールではない場合に デフォルトの Locale を返します。それ以外の場合は、null が返されます。

パラメータ:
baseName - リソースバンドルの基底名。完全指定クラス名。ResourceBundle.getBundle はこの基底名に対して、基底バンドル以外のリソースバンドルを 1 つも見つけられなかった
locale - LocaleResourceBundle.getBundle はこのロケールに対して、基底バンドル以外のリソースバンドルを 1 つも見つけられなかった
戻り値:
フォールバック検索用の Locale。さらなるフォールバック検索が必要ない場合は null
例外:
NullPointerException - baseName または localenull の場合

newBundle

public ResourceBundle newBundle(String baseName,
                                Locale locale,
                                String format,
                                ClassLoader loader,
                                boolean reload)
                         throws IllegalAccessException,
                                InstantiationException,
                                IOException
指定された形式とロケールを持つ指定されたバンドル名のリソースバンドルを、指定されたクラスローダーを必要に応じて使用してインスタンス化します。指定されたパラメータに対応する使用可能なリソースバンドルが存在しない場合、このメソッドは null を返します。予想外のエラーが発生したためにリソースバンドルのインスタンス化が行えない場合には、単純に null を返す代わりに、Error または Exception をスローすることでエラーが報告されます。

reload フラグが true の場合、それは、以前にロードされたリソースバンドルの有効期限が切れたためにこのメソッドが呼び出されたことを示します。

デフォルト実装による ResourceBundle のインスタンス化手順は、次のとおりです。

パラメータ:
baseName - リソースバンドルの基底バンドル名。完全指定クラス名
locale - リソースバンドルのインスタンス化対象となるロケール
format - ロードされるリソースバンドルの形式
loader - バンドルをロードするための ClassLoader
reload - バンドルの再ロードを示すフラグ。有効期限の切れたリソースバンドルを再ロードする場合は true、それ以外の場合は false
戻り値:
リソースバンドルインスタンス。インスタンスが見つからなかった場合は null
例外:
NullPointerException - bundleNamelocaleformat、または loadernull の場合、または toBundleName から null が返された場合
IllegalArgumentException - format が不明である場合、または指定されたパラメータに対して見つかったリソースに不正なデータが含まれている場合
ClassCastException - ロードされたクラスを ResourceBundle にキャストできない場合
IllegalAccessException - クラスまたはその null コンストラクタにアクセスできない場合
InstantiationException - クラスのインスタンス化が何かほかの理由で失敗する場合
ExceptionInInitializerError - このメソッドによる初期化が失敗した場合
SecurityException - セキュリティーマネージャーが存在し、新しいインスタンスの作成が拒否された場合。詳細は Class.newInstance() を参照
IOException - 何らかの入出力操作を使ってリソースを読み取る際にエラーが発生した場合

getTimeToLive

public long getTimeToLive(String baseName,
                          Locale locale)
この ResourceBundle.Control の下でロードされたリソースバンドルの有効期間 (TTL) 値を返します。正の有効期間値は、バンドルがその構築元となるソースデータに基づいて検証されずにキャスト内にとどまることのできるミリ秒数を表します。値 0 は、バンドルがキャッシュから取得されるたびに検証されることを示します。TTL_DONT_CACHE は、ロードされたリソースバンドルがキャッシュに格納されないことを表します。TTL_NO_EXPIRATION_CONTROL は、ロードされたリソースバンドルが有効期限制御なしでキャッシュに格納されることを表します。

この有効期限の影響を受けるのは、ResourceBundle.getBundle ファクトリメソッドによるバンドルロード処理だけです。つまり、ファクトリメソッドは、キャッシュ内で有効期限の切れたリソースバンドルを検出すると、needsReload メソッドを呼び出し、そのリソースバンドルを再ロードする必要があるかどうかを判定します。needsReloadtrue を返した場合、そのキャッシュ内のリソースバンドルインスタンスがキャッシュから削除されます。それ以外の場合、そのインスタンスはキャッシュ内にとどまり、このメソッドから返された新しい TTL 値で更新されます。

キャッシュ内のリソースバンドルはすべて、実行環境のメモリー制限による、キャッシュからの削除対象となります。大きな正の値が返されても、それは、ロードされたリソースバンドルがキャッシュ内でロックされることを意味するわけではありません。

デフォルト実装は TTL_NO_EXPIRATION_CONTROL を返します。

パラメータ:
baseName - 有効期限値が指定されているリソースバンドルの基底名
locale - 有効期限値が指定されているリソースバンドルのロケール
戻り値:
キャッシュ内のロード済みバンドルに有効期限を設ける場合はその時間 (0 またはキャッシュ格納時刻からの正のミリ秒オフセット)、有効期限制御を無効にする場合は TTL_NO_EXPIRATION_CONTROL、キャッシュを無効にする場合は TTL_DONT_CACHE
例外:
NullPointerException - baseName または localenull の場合

needsReload

public boolean needsReload(String baseName,
                           Locale locale,
                           String format,
                           ClassLoader loader,
                           ResourceBundle bundle,
                           long loadTime)
キャッシュ内で有効期限の切れた bundle を再ロードする必要があるかどうかを、loadTime に指定されたロード時刻やその他のいくつかの条件に基づいて判定します。このメソッドは、再ロードが必要な場合は true を返し、それ以外の場合は false を返します。loadTime は、Calendar のエポックからのミリ秒オフセットです。 呼び出し元の ResourceBundle.getBundle ファクトリメソッドは、このリソースバンドルを最初にロードした呼び出しで使用されていた ResourceBundle.Control インスタンスではなく、現在の呼び出しで使用されているインスタンス上で、このメソッドを呼び出します。

デフォルト実装は、リソースバンドルの loadTime と、そのソースデータが最後に変更された時刻とを比較します。loadTime 以降にソースデータが変更されたことが判明した場合には、true が返されます。それ以外の場合は false が返されます。この実装は、指定された format がデフォルトの形式 「java.class」「java.properties」のいずれでもない場合、その形式がファイル接尾辞と同じ文字列であると仮定します。

パラメータ:
baseName - リソースバンドルの基底バンドル名。完全指定クラス名
locale - リソースバンドルのインスタンス化対象となるロケール
format - ロードされるリソースバンドルの形式
loader - バンドルをロードするための ClassLoader
bundle - キャッシュ内で有効期限の切れたリソースバンドルインスタンス
loadTime - bundle がロードされ、キャッシュ内に格納された時刻
戻り値:
有効期限の切れたバンドルを再ロードする必要がある場合は true、それ以外の場合は false
例外:
NullPointerException - baseNamelocaleformatloader、または bundlenull の場合

toBundleName

public String toBundleName(String baseName,
                           Locale locale)
指定された baseNamelocale をバンドル名に変換します。このメソッドは、newBundle および needsReload メソッドのデフォルト実装から呼び出されます。

この実装は次の値を返します。

     baseName + "_" + language + "_" + country + "_" + variant
 
ここで、languagecountryvariant はそれぞれ、locale の言語、国、バリアントの値になります。最後の要素の値が空の String である場合、その値と直前の「_」は省略されます。すべての値が空の文字列である場合には、baseName が返されます。

たとえば、baseName「baseName」localeLocale("ja", "", "XX") の場合は、「baseName_ja_ _XX」」が返されます。指定されたロケールが Locale("en") の場合は、「baseName_en」が返されます。

このメソッドをオーバーライドすれば、ローカライズ済みリソースの構成やパッケージ化に関する異なる規約をアプリケーションで使用できます。

パラメータ:
baseName - リソースバンドルの基底名。完全指定クラス名
locale - リソースバンドルのロード対象となるロケール
戻り値:
リソースバンドルのバンドル名
例外:
NullPointerException - baseName または localenull の場合

toResourceName

public final String toResourceName(String bundleName,
                                   String suffix)
指定された bundleName を、ClassLoader.getResource メソッドが要求する形式に変換します。具体的には、bundleName 内のすべての「.」「/」に置き換え、その末尾に「.」と指定されたファイル suffix を追加します。たとえば、bundleName「foo.bar.MyResources_ja_JP」suffix「properties」の場合、「foo/bar/MyResources_ja_JP.properties」が返されます。

パラメータ:
bundleName - バンドル名
suffix - ファイルタイプ接尾辞
戻り値:
変換後のリソース名
例外:
NullPointerException - bundleName または suffixnull の場合

JavaTM Platform
Standard Ed. 6

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。