java.util.ResourceBundle.Control
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
java.lang.Object
public static class ResourceBundle.Control
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() {
...
}
}
| フィールドの概要 | |
|---|---|
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)
baseName と locale に対する候補ロケールとして、Locale の List を返します。 |
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 のリソースバンドルをロードする際に使用すべき形式が格納された、String の List を返します。 |
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)
指定された baseName と locale をバンドル名に変換します。 |
String |
toResourceName(String bundleName,
String suffix)
指定された bundleName を、ClassLoader.getResource メソッドが要求する形式に変換します。 |
| クラス java.lang.Object から継承されたメソッド |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| フィールドの詳細 |
|---|
public static final List<String> FORMAT_DEFAULT
List。文字列「java.class」と「java.properties」をこの順番で含みます。この List は 変更不可能 です。
getFormats(String)public static final List<String> FORMAT_CLASS
List。「java.class」を含みます。この List は変更不可能です。
getFormats(String)public static final List<String> FORMAT_PROPERTIES
List。「java.properties」を含みます。この List は変更不可能です。
getFormats(String)public static final long TTL_DONT_CACHE
getTimeToLive(String, Locale),
定数フィールド値public static final long TTL_NO_EXPIRATION_CONTROL
getTimeToLive(String, Locale),
定数フィールド値| コンストラクタの詳細 |
|---|
protected ResourceBundle.Control()
| メソッドの詳細 |
|---|
public static final ResourceBundle.Control getControl(List<String> formats)
getFormats メソッドが指定された formats を返すような、ResourceBundle.Control を返します。formats は、FORMAT_PROPERTIES、FORMAT_CLASS、FORMAT_DEFAULT のいずれかと等しくなります。このメソッドが返す ResourceBundle.Control インスタンスは単独であり、スレッドに対して安全です。
FORMAT_DEFAULT を指定することは、ResourceBundle.Control クラスをインスタンス化することと等価です。ただし、このメソッドが単独オブジェクトを返す点だけは異なります。
formats - ResourceBundle.Control.getFormats メソッドから返されるべき形式
formats をサポートする ResourceBundle.Control
NullPointerException - formats が null の場合
IllegalArgumentException - formats が不明な場合public static final ResourceBundle.Control getNoFallbackControl(List<String> formats)
getFormats メソッドが指定された formats を返し、かつ getFallbackLocale メソッドが null を返すような、ResourceBundle.Control を返します。formats は、FORMAT_PROPERTIES、FORMAT_CLASS、FORMAT_DEFAULT のいずれかと等しくなります。このメソッドが返す ResourceBundle.Control インスタンスは単独であり、スレッドに対して安全です。
formats - ResourceBundle.Control.getFormats メソッドから返されるべき形式
formats をサポートし、フォールバック Locale をサポートしない ResourceBundle.Control
NullPointerException - formats が null の場合
IllegalArgumentException - formats が不明な場合public List<String> getFormats(String baseName)
baseName のリソースバンドルをロードする際に使用すべき形式が格納された、String の List を返します。ResourceBundle.getBundle ファクトリメソッドは、このリスト内の形式を持つリソースバンドルを、リスト内に指定された順番でロードしようとします。このメソッドから返されたリストには、少なくとも 1 つの String が含まれていなければいけません。定義済みの形式は、クラスベースのリソースバンドル用の「java.class」と、プロパティーベース のリソースバンドル用の「java.properties」です。「java.」で始まる文字列は、将来の拡張用として予約されているため、アプリケーション定義形式では使用しないでください。
不変の (変更不可能な) List を返す必要は、必ずしもありません。ただし、List が getFormats から返されたあとで、そのリストを変更してはいけません。
デフォルト実装は FORMAT_DEFAULT を返しますが、これは、ResourceBundle.getBundle ファクトリメソッドがまずクラスベースのリソースバンドルを検索し、次にプロパティーベースのバンドルを検索するようにするためです。
baseName - リソースバンドルの基底名。完全指定クラス名
String の List
NullPointerException - baseName が null の場合FORMAT_DEFAULT,
FORMAT_CLASS,
FORMAT_PROPERTIES
public List<Locale> getCandidateLocales(String baseName,
Locale locale)
baseName と locale に対する候補ロケールとして、Locale の List を返します。このメソッドは、ターゲット Locale のリソースバンドルの検索を ResourceBundle.getBundle ファクトリメソッドが試みるたびに、そのファクトリメソッドによって呼び出されます。
候補ロケールに対応するリソースバンドルが存在しており、それらのロード済みリソースバンドル自体には親が定義されていない場合、候補ロケールのシーケンスは、実行時リソース検索パス (「親連鎖」とも呼ばれる) にも対応します。基底バンドルを親連鎖の終端にする必要がある場合、このリストの最後の要素は ルートロケール でなければいけません。
指定されたロケールが Locale.ROOT (ルートロケール) に等しい場合、ルートの Locale だけを含む List が返されます。この場合、ResourceBundle.getBundle ファクトリメソッドは、結果として得られるリソースバンドルとして基底バンドルだけをロードします。
不変の (変更不可能な) List を返す必要は、必ずしもありません。ただし、List が getCandidateLocales から返されたあとで、そのリストを変更してはいけません。
デフォルト実装は、Locale が次の順番で格納された List を返します。
Locale(language, country, variant)
Locale(language, country)
Locale(language)
Locale.ROOT
ここで、language、country、variant はそれぞれ、指定された locale の言語、国、バリアントの値になります。最後の要素の値が空文字列であるようなロケールは、省略されます。
デフォルト実装は ArrayList を使用しますが、これは、オーバーライドした実装内で、呼び出し元に返される前に変更することができます。ただし、getCandidateLocales から返されたあとでサブクラス内で変更してはいけません。
たとえば、指定された baseName が「Messages」であり、指定された locale が Locale("ja", "", "XX") であった場合、返される Locale の List は、
Locale("ja", "", "XX")
Locale("ja")
Locale.ROOT
のようになります。そして、「ja」と「」の Locale に対するリソースバンドルが見つかった場合、実行時リソース検索パス (親連鎖) は次のようになります。
Messages_ja -> Messages
baseName - リソースバンドルの基底名。完全指定クラス名locale - リソースバンドルが必要なロケール
locale に対する候補 Locale の List
NullPointerException - baseName または locale が null の場合
public Locale getFallbackLocale(String baseName,
Locale locale)
ResourceBundle.getBundle ファクトリメソッドがリソースバンドルをさらに検索する際のフォールバックロケールとして使用すべき Locale を返します。このメソッドは、baseName と locale に対応する結果リソースバンドルが 1 つも見つからない状況が発生するたびに、ファクトリメソッドによって呼び出されます。ここで、そのロケールは、ResourceBundle.getBundle のパラメータ、このメソッドから以前に返されたフォールバックロケールのいずれかになります。
このメソッドは、さらなるフォールバック検索が必要ない場合に null を返します。
デフォルト実装は、指定された locale がデフォルトのロケールではない場合に デフォルトの Locale を返します。それ以外の場合は、null が返されます。
baseName - リソースバンドルの基底名。完全指定クラス名。ResourceBundle.getBundle はこの基底名に対して、基底バンドル以外のリソースバンドルを 1 つも見つけられなかったlocale - Locale。ResourceBundle.getBundle はこのロケールに対して、基底バンドル以外のリソースバンドルを 1 つも見つけられなかった
Locale。さらなるフォールバック検索が必要ない場合は null
NullPointerException - baseName または locale が null の場合
public ResourceBundle newBundle(String baseName,
Locale locale,
String format,
ClassLoader loader,
boolean reload)
throws IllegalAccessException,
InstantiationException,
IOException
null を返します。予想外のエラーが発生したためにリソースバンドルのインスタンス化が行えない場合には、単純に null を返す代わりに、Error または Exception をスローすることでエラーが報告されます。
reload フラグが true の場合、それは、以前にロードされたリソースバンドルの有効期限が切れたためにこのメソッドが呼び出されたことを示します。
デフォルト実装による ResourceBundle のインスタンス化手順は、次のとおりです。
toBundleName(baseName, locale) を呼び出すことでバンドル名が取得される。format が「java.class」の場合、バンドル名によって指定される Class が、ClassLoader.loadClass(String) を呼び出すことでロードされる。次に、Class.newInstance() を呼び出すことで ResourceBundle がインスタンス化される。なお、このデフォルト実装では、クラスベースのリソースバンドルをロードする際には reload フラグが無視される。format が「java.properties」の場合、toResourceName(bundlename, "properties") を呼び出すことでリソース名が取得される。reload が true の場合、load.getResource を呼び出すことで、URLConnection を作成するための URL が取得される。この URLConnection を使って、基盤となるリソースロード処理層の キャッシュの無効化 と、InputStream の取得 が行われる。それ以外の場合は loader.getResourceAsStream が呼び出され、InputStream が取得される。次に、その InputStream を使って PropertyResourceBundle が構築される。format が「java.class」、「java.properties」のいずれでもない場合は、IllegalArgumentException がスローされる。
baseName - リソースバンドルの基底バンドル名。完全指定クラス名locale - リソースバンドルのインスタンス化対象となるロケールformat - ロードされるリソースバンドルの形式loader - バンドルをロードするための ClassLoaderreload - バンドルの再ロードを示すフラグ。有効期限の切れたリソースバンドルを再ロードする場合は true、それ以外の場合は false
null
NullPointerException - bundleName、locale、format、または loader が null の場合、または toBundleName から null が返された場合
IllegalArgumentException - format が不明である場合、または指定されたパラメータに対して見つかったリソースに不正なデータが含まれている場合
ClassCastException - ロードされたクラスを ResourceBundle にキャストできない場合
IllegalAccessException - クラスまたはその null コンストラクタにアクセスできない場合
InstantiationException - クラスのインスタンス化が何かほかの理由で失敗する場合
ExceptionInInitializerError - このメソッドによる初期化が失敗した場合
SecurityException - セキュリティーマネージャーが存在し、新しいインスタンスの作成が拒否された場合。詳細は Class.newInstance() を参照
IOException - 何らかの入出力操作を使ってリソースを読み取る際にエラーが発生した場合
public long getTimeToLive(String baseName,
Locale locale)
ResourceBundle.Control の下でロードされたリソースバンドルの有効期間 (TTL) 値を返します。正の有効期間値は、バンドルがその構築元となるソースデータに基づいて検証されずにキャスト内にとどまることのできるミリ秒数を表します。値 0 は、バンドルがキャッシュから取得されるたびに検証されることを示します。TTL_DONT_CACHE は、ロードされたリソースバンドルがキャッシュに格納されないことを表します。TTL_NO_EXPIRATION_CONTROL は、ロードされたリソースバンドルが有効期限制御なしでキャッシュに格納されることを表します。
この有効期限の影響を受けるのは、ResourceBundle.getBundle ファクトリメソッドによるバンドルロード処理だけです。つまり、ファクトリメソッドは、キャッシュ内で有効期限の切れたリソースバンドルを検出すると、needsReload メソッドを呼び出し、そのリソースバンドルを再ロードする必要があるかどうかを判定します。needsReload が true を返した場合、そのキャッシュ内のリソースバンドルインスタンスがキャッシュから削除されます。それ以外の場合、そのインスタンスはキャッシュ内にとどまり、このメソッドから返された新しい TTL 値で更新されます。
キャッシュ内のリソースバンドルはすべて、実行環境のメモリー制限による、キャッシュからの削除対象となります。大きな正の値が返されても、それは、ロードされたリソースバンドルがキャッシュ内でロックされることを意味するわけではありません。
デフォルト実装は TTL_NO_EXPIRATION_CONTROL を返します。
baseName - 有効期限値が指定されているリソースバンドルの基底名locale - 有効期限値が指定されているリソースバンドルのロケール
TTL_NO_EXPIRATION_CONTROL、キャッシュを無効にする場合は TTL_DONT_CACHE
NullPointerException - baseName または locale が null の場合
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 - バンドルをロードするための ClassLoaderbundle - キャッシュ内で有効期限の切れたリソースバンドルインスタンスloadTime - bundle がロードされ、キャッシュ内に格納された時刻
true、それ以外の場合は false
NullPointerException - baseName、locale、format、loader、または bundle が null の場合
public String toBundleName(String baseName,
Locale locale)
baseName と locale をバンドル名に変換します。このメソッドは、newBundle および needsReload メソッドのデフォルト実装から呼び出されます。
この実装は次の値を返します。
baseName + "_" + language + "_" + country + "_" + variant
ここで、language、country、variant はそれぞれ、locale の言語、国、バリアントの値になります。最後の要素の値が空の String である場合、その値と直前の「_」は省略されます。すべての値が空の文字列である場合には、baseName が返されます。
たとえば、baseName が「baseName」、locale が Locale("ja", "", "XX") の場合は、「baseName_ja_ _XX」」が返されます。指定されたロケールが Locale("en") の場合は、「baseName_en」が返されます。
このメソッドをオーバーライドすれば、ローカライズ済みリソースの構成やパッケージ化に関する異なる規約をアプリケーションで使用できます。
baseName - リソースバンドルの基底名。完全指定クラス名locale - リソースバンドルのロード対象となるロケール
NullPointerException - baseName または locale が null の場合
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 または suffix が null の場合
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。