java.util
クラス ResourceBundle

java.lang.Object
  java.util.ResourceBundle

直系の既知のサブクラス:

ListResourceBundle, PropertyResourceBundle

public abstract class ResourceBundle
extends Object

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

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

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

リソースバンドルはファミリに属しています。そのファミリでは、メンバは共通の基底名を共有していますが、ファミリ名にはロケールを識別する追加コンポーネントも含まれています。たとえば、リソースバンドルのファミリの基底名は「MyResources」です。ファミリは、ファミリと同じ名前 (MyResources) で、特定のロケールがサポートされない場合は、最後の手段のバンドルとして使用される、デフォルトのリソースバントルを持つ必要があります。また、ファミリは、必要なだけの数のロケール固有のメンバを提供することができます。たとえば、「MyResources_de」と名付けられたドイツのメンバなどです。

ファミリの各リソースバンドルには同じ項目がありますが、こうした項目は当該リソースバンドルにより表されるロケールに合わせて翻訳されています。たとえば、「MyResources」と「MyResources_de」の両方に操作取り消し用のボタンに使用される String が含まれている場合は、「MyResources」には String に「Cancel」が、「MyResources_de」には「Abbrechen」が含まれています。

同じ言語を使用するロケールでも国によってリソースが異なるときは、特殊化が可能です。たとえば、MyResources_de_CH には、スイス (CH) 系のドイツ語 (de) のオブジェクトが含まれています。リソースの一部だけを修正することもできます。

プログラムでロケール固有のオブジェクトが必要なときは、getBundle メソッドを使用して、ResourceBundle クラスを次のようにロードします。

 ResourceBundle myResources =
      ResourceBundle.getBundle("MyResources", currentLocale);
 

リソースバンドルは、キーと値のペアになっています。キーは、バンドルのロケール固有のオブジェクトを一意に識別します。キーと値の 2 つのペアが含まれている ListResourceBundle の例を示します。

 public class MyResources extends ListResourceBundle {
      public Object[][] getContents() {
              return contents;
      }
      static final Object[][] contents = {
      // LOCALIZE THIS
              {"OkKey", "OK"},
              {"CancelKey", "Cancel"},
      // END OF MATERIAL TO LOCALIZE
      };
 }
 

キーは常に String です。この例では、キーは OkKey と CancelKey です。前述した例では、値 「OK」と「Cancel」も String ですが、必ずしもそうである必要はありません。値は、どの型のオブジェクトでも可能です。

リソースバンドルから適切な getter メソッドを使用してオブジェクトを検索します。「OkKey」と「CancelKey」はどちらも文字列なので、検索には getString を使用します。

 button1 = new Button(myResources.getString("OkKey"));
 button2 = new Button(myResources.getString("CancelKey"));
 

getter メソッドは、すべて引数としてキーを要求し、検出したオブジェクトを返します。オブジェクトが見つからない場合、getter メソッドは MissingResourceException をスローします。

getString 以外に、ResourceBundle では、文字列配列を取得する getStringArray メソッドも提供します。同様に、ほかの型のオブジェクトを取得する汎用 getObject メソッドも提供します。getObject を使用する場合、結果を適切な型にキャストする必要があります。次に例を示します。

 int[] myIntegers = (int[]) myResources.getObject("intList");
 

Java 2 プラットフォームでは、ResourceBundle の 2 つのサブクラス ListResourceBundle および PropertyResourceBundle が用意されています。これらはリソースを作成するかなり簡単な方法を提供します。前の例で簡単に示したように、ListResourceBundle は、そのリソースをキーと値のペアのリストとして管理します。PropertyResourceBundle は、プロパティファイルを使用してそのリソースを管理します。

ListResourceBundle または PropertyResourceBundle では不十分なときは、独自の ResourceBundle サブクラスを書くことができます。それらのサブクラスでは、handleGetObject メソッドおよび getKeys() メソッドの 2 つをオーバーライドする必要があります。

次にあるのは ResourceBundle のサブクラス MyResources の非常に簡単な例です。このサブクラスは 2 つのリソースを管理します (サブクラスが多数のリソースを管理する場合は、Hashtable を使用する)。「親レベル」の ResourceBundle が、(下記の okKey のように)　同じ値を持つ同じキーを扱う場合は、値を提供する必要はありません。

例:

 // default (English language, United States)
 public class MyResources extends ResourceBundle {
     public Object handleGetObject(String key) {
         if (key.equals("okKey")) return "Ok";
         if (key.equals("cancelKey")) return "Cancel";
         return null;
     }
 }

 // German language
 public class MyResources_de extends MyResources {
     public Object handleGetObject(String key) {
         // don't need okKey, since parent level handles it.
         if (key.equals("cancelKey")) return "Abbrechen";
         return null;
     }
 }
 

ResourceBundle のシングルファミリの使用を制限する必要はありません。たとえば、例外メッセージ ExceptionResources (ExceptionResources_fr、ExceptionResources_de など) で 1 つのリソース、ウィジェット WidgetResource (WidgetResources_fr、WidgetResources_de など) で 1 つのリソースというように、好きなようにリソースを分割してバンドルのセットを持つこともできます。

導入されたバージョン:

JDK1.1

関連項目:

ListResourceBundle, PropertyResourceBundle, MissingResourceException

フィールドの概要

protected ResourceBundle

parent このバンドルの親バンドル。

コンストラクタの概要

ResourceBundle()
唯一のコンストラクタです。

メソッドの概要

static ResourceBundle	getBundle(String baseName) 指定された基底名、デフォルトのロケール、および呼び出し側のクラスローダを使用して、リソースバンドルを取得します。
static ResourceBundle	getBundle(String baseName, Locale locale) 指定された基底名、ロケール、および呼び出し側のクラスローダを使用して、リソースバンドルを取得します。
static ResourceBundle	getBundle(String baseName, Locale locale, ClassLoader loader) 指定された基底名、ロケール、クラスローダを使用して、リソースバンドルを取得します。
abstract Enumeration<String>	getKeys() キーのリストを返します。
Locale	getLocale() リソースバンドルの Locale を返します。
Object	getObject(String key) このリソースバンドルまたはその親リソースバンドルのいずれかから指定されたキーのオブジェクトを取得します。
String	getString(String key) このリソースバンドルまたはその親リソースバンドルのいずれかから指定されたキーの文字列を取得します。
String[]	getStringArray(String key) このリソースバンドルまたはその親リソースバンドルのいずれかから指定されたキーの文字列配列を取得します。
protected abstract Object	handleGetObject(String key) このリソースバンドルから指定されたキーのオブジェクトを取得します。
protected void	setParent(ResourceBundle parent) このバンドルの親バンドルを設定します。

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

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

フィールドの詳細

parent

protected ResourceBundle parent

このバンドルの親バンドル。親バンドルに特定のリソースが含まれていないときは getObject を使用して親バンドルを検索します。

コンストラクタの詳細

ResourceBundle

public ResourceBundle()

唯一のコンストラクタです。サブクラスのコンストラクタによる呼び出しは、通常は暗黙的な呼び出しです。

メソッドの詳細

getString

public final String getString(String key)

このリソースバンドルまたはその親リソースバンドルのいずれかから指定されたキーの文字列を取得します。このメソッドを呼び出すことは、次を呼び出すことと同じです。

(String) getObject(key)

パラメータ:

key - 望ましい文字列のキー

戻り値:

指定されたキーの文字列

例外:

NullPointerException - key が null の場合

MissingResourceException - 指定されたキーのオブジェクトが見つからない場合

ClassCastException - 指定されたキーの見つかったオブジェクトが文字列でない場合

getStringArray

public final String[] getStringArray(String key)

このリソースバンドルまたはその親リソースバンドルのいずれかから指定されたキーの文字列配列を取得します。このメソッドを呼び出すことは、次を呼び出すことと同じです。

(String[]) getObject(key)

パラメータ:

key - 望ましい文字列配列のキー

戻り値:

指定されたキーの文字列配列

例外:

NullPointerException - key が null の場合

MissingResourceException - 指定されたキーのオブジェクトが見つからない場合

ClassCastException - 指定されたキーの見つかったオブジェクトが文字列配列でない場合

getObject

public final Object getObject(String key)

このリソースバンドルまたはその親リソースバンドルのいずれかから指定されたキーのオブジェクトを取得します。このメソッドは、最初に handleGetObject を使用して、このリソースバンドルからオブジェクトを取得しようとします。オブジェクトを取得できず、親リソースバンドルが null でない場合、親の getObject メソッドを呼び出します。それでも取得できない場合は、MissingResourceException をスローします。

パラメータ:

key - 望ましいオブジェクトのキー

戻り値:

指定されたキーのオブジェクト

例外:

NullPointerException - key が null の場合

MissingResourceException - 指定されたキーのオブジェクトが見つからない場合

getLocale

public Locale getLocale()

リソースバンドルの Locale を返します。このメソッドは、返されたリソースバンドルが本当に要求されたロケールに対応しているか、またはフォールバックであるかを判定するために、getBundle() を呼び出したあとで使用できます。

戻り値:

このリソースバンドルのロケール

setParent

protected void setParent(ResourceBundle parent)

このバンドルの親バンドルを設定します。親バンドルは、このバンドルに特定のリソースが含まれていないときに getObject によって参照されます。

パラメータ:

parent - このバンドルの親バンドル

getBundle

public static final ResourceBundle getBundle(String baseName)

指定された基底名、デフォルトのロケール、および呼び出し側のクラスローダを使用して、リソースバンドルを取得します。このメソッドを呼び出すことは、次を呼び出すことと同じです。

getBundle(baseName, Locale.getDefault(), this.getClass().getClassLoader())

getClassLoader() が、ResourceBundle のセキュリティ特権により実行されることだけが異なります。検索とインスタンス生成方法の詳細については、getBundle を参照してください。

パラメータ:

baseName - リソースバンドル、完全指定されたクラス名の基底名

戻り値:

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

例外:

NullPointerException - baseName が null の場合

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

getBundle

public static final ResourceBundle getBundle(String baseName,
                                             Locale locale)

指定された基底名、ロケール、および呼び出し側のクラスローダを使用して、リソースバンドルを取得します。このメソッドを呼び出すことは、次を呼び出すことと同じです。

getBundle(baseName, locale, this.getClass().getClassLoader())

getClassLoader() が、ResourceBundle のセキュリティ特権により実行されることだけが異なります。検索とインスタンス生成方法の詳細については、getBundle を参照してください。

パラメータ:

baseName - リソースバンドル、完全指定されたクラス名の基底名

locale - リソースバンドルが必要なロケール

戻り値:

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

例外:

NullPointerException - baseName または locale が null の場合

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

getBundle

public static ResourceBundle getBundle(String baseName,
                                       Locale locale,
                                       ClassLoader loader)

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

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

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

• まず、候補のバンドル名を使用して、クラスをロードしようとします。指定したクラスローダを使用して、検索してロードしたクラスが ResourceBundle と互換性を持つ割り当てで、ResourceBundle からのアクセスが可能であり、インスタンス化できる場合は、getBundle はこのクラスの新しいインスタンスを作成して、「結果リソースバンドル」としてそのインスタンスを使用します。
• それ以外の場合は、getBundle はプロパティリソースファイルを見つけようとします。すべての「.」文字を「/」文字に置き換え、「.properties」文字列を追加して、候補のバンドル名からパス名を生成します。ClassLoader.getResource を使用して、この名前の「リソース」を見つけようとします (getResource の「リソース」とは、リソースバンドルのコンテンツとは無関係であり、ファイルなどのデータのコンテナにすぎない)。「リソース」を見つけた場合、リソースのコンテンツから新しい PropertyResourceBundle インスタンスを作成しようとします。作成が成功した場合は、このインスタンスは、「結果リソースバンドル」になります。

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

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

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

baseName 引数は完全指定されたクラス名である必要があります。ただし、前バージョンとの互換性に関しては、Sun の Java 2 ランタイム環境はそのことを検証しません。そのため、完全指定されたクラス名 (「.」を使用) の代わりにパス名 (「/」を使用) を指定して、PropertyResourceBundle にアクセスできるようになります。

例: クラスとプロパティファイル、MyResources.class、MyResources_fr_CH.properties、MyResources_fr_CH.class、MyResources_fr.properties、MyResources_en.properties、MyResources_es_ES.class が提供されています。すべてのファイルのコンテンツが有効です (つまり、「.class」ファイルの ResourceBundle のパブリックで非抽象的なサブクラスが「.properties」ファイルの構文を修正する)。デフォルトのロケールは Locale("en", "GB") です。

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

• Locale("fr", "CH"): result MyResources_fr_CH.class, parent MyResources_fr.properties, parent MyResources.class
• Locale("fr", "FR"): result MyResources_fr.properties, parent MyResources.class
• Locale("de", "DE"): result MyResources_en.properties, parent MyResources.class
• Locale("en", "US"): result MyResources_en.properties, parent MyResources.class
• Locale("es", "ES"): result MyResources_es_ES.class, parent MyResources.class

MyResources_fr_CH.properties ファイルは、MyResources_fr_CH.class によって隠されているので、使用されることはありません。

パラメータ:

baseName - リソースバンドル、完全指定されたクラス名の基底名

locale - リソースバンドルが必要なロケール

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

戻り値:

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

例外:

NullPointerException - baseName、locale または loaderが null の場合

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

導入されたバージョン:

1.2

handleGetObject

protected abstract Object handleGetObject(String key)

このリソースバンドルから指定されたキーのオブジェクトを取得します。このリソースバンドルが、指定されたキーのオブジェクトを含まない場合は、null を返します。

パラメータ:

key - 望ましいオブジェクトのキー

戻り値:

指定されたキーのオブジェクト、または null

例外:

NullPointerException - key が null の場合

getKeys

public abstract Enumeration<String> getKeys()

キーのリストを返します。