java.util.ResourceBundle
|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
| 上一個類別 下一個類別 | 框架 無框架 | |||||||||
| 摘要： 巢狀 | 欄位 | 建構子 | 方法 | 詳細資訊： 欄位 | 建構子 | 方法 | |||||||||
java.lang.Object
public abstract class ResourceBundle
資源包包含特定於語言環境的物件。當程序需要一個特定於語言環境的資源時（如 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);
資源包包含鍵/值對。鍵唯一地標識了包中特定於語言環境的物件。下面是一個 ListResourceBundle 範例，它包含兩個鍵/值對：
public class MyResources extends ListResourceBundle {
protected Object[][] getContents() {
return new Object[][] {
// LOCALIZE THE SECOND STRING OF EACH ARRAY (e.g., "OK")
{"OkKey", "OK"},
{"CancelKey", "Cancel"},
// END OF MATERIAL TO LOCALIZE
};
}
}
鍵始終為 String 型別。在此範例中，兩個鍵是 "OkKey" 和 "CancelKey"。在上面的範例中，值也是 String 型別，即 "OK" 和 "Cancel"，但並非必須如此。值可以是任意物件型別。
可以使用適當的獲取方法從資源包中獲取某個物件。因為 "OkKey" 和 "CancelKey" 都是字元串，所以應該使用 getString 獲取它們：
button1 = new Button(myResources.getString("OkKey"));
button2 = new Button(myResources.getString("CancelKey"));
所有獲取方法都需要將鍵作為參數並返回物件（如果找到的話）。如果未找到物件，則獲取方法將拋出 MissingResourceException。
除了 getString 之外，ResourceBundle 還提供了獲取字元串陣列的方法 getStringArray，以及用於其他任意物件型別的 getObject 方法。使用 getObject 時，必須將結果強制轉換為適當的型別。例如：
int[] myIntegers = (int[]) myResources.getObject("intList");
Java 平臺提供了兩個 ResourceBundle 的子類別，即 ListResourceBundle 和 PropertyResourceBundle，這為創建資源提供了一種相當簡單的方式。正如在前面範例中所看到的，ListResourceBundle 以鍵/值對的列表方式管理其資源。PropertyResourceBundle 則使用一個屬性檔案來管理其資源。
如果 ListResourceBundle 或 PropertyResourceBundle 無法滿足需求，那麼可以編寫自己的 ResourceBundle 子類別。子類別必須覆寫兩個方法：handleGetObject 和 getKeys()。
ResourceBundle.Control 類別提供通過帶 ResourceBundle.Control 實例的 getBundle 處理器方法執行包載入進程所需的資訊。為了啟用非標準資源包格式、更改搜尋策略或定義快取記憶體參數，可以實作自己的子類別。有關細節請參考類別和 getBundle 處理器方法的描述。
getBundle 處理器方法創建的資源包實例是預設快取記憶體的，如果資源包實例已經快取記憶體，那麼這些處理器方法將多次返回相同的資源包實例。getBundle 客戶端可以清除快取記憶體、使用生存時間值管理已快取記憶體資源包實例的生命週期，或者指定不快取記憶體資源包實例。有關細節請參考getBundle 處理器方法、clearCache、ResourceBundle.Control.getTimeToLive 和 ResourceBundle.Control.needsReload 的描述。
ResourceBundle 子類別範例 MyResources，它管理兩個資源（對於大量的資源，應該使用 Map）。注意，如果某個「父級」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;
}
public Enumeration<String> getKeys() {
return Collections.enumeration(keySet());
}
// Overrides handleKeySet() so that the getKeys() implementation
// can rely on the keySet() value.
protected Set<String> handleKeySet() {
return new HashSet<String>(Arrays.asList("okKey", "cancelKey"));
}
}
// 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;
}
protected Set<String> handleKeySet() {
return new HashSet<String>(Arrays.asList("cancelKey"));
}
}
不必限制只使用 ResourceBundle 的單個系列。例如，可以有異常訊息 ExceptionResources 的套件集（ExceptionResources_fr、ExceptionResources_de 等）和視窗小部件 WidgetResource 的套件集（WidgetResources_fr、WidgetResources_de 等）；可以按自己喜歡的方式分解資源。
ListResourceBundle,
PropertyResourceBundle,
MissingResourceException| 巢狀類別摘要 | |
|---|---|
static class |
ResourceBundle.Control
ResourceBundle.Control 定義一個回調方法集，它在包載入進程中由 ResourceBundle.getBundle 處理器方法調用。 |
| 欄位摘要 | |
|---|---|
protected ResourceBundle |
parent
此套件的父套件。 |
| 建構子摘要 | |
|---|---|
ResourceBundle()
唯一的建構子（由子類別建構子調用，通常是隱式的）。 |
|
| 方法摘要 | |
|---|---|
static void |
clearCache()
從已經使用調用者的類別載入器載入的快取記憶體中移除所有資源套件。 |
static void |
clearCache(ClassLoader loader)
從已經使用給定類別載入器載入的快取記憶體中移除所有資源套件。 |
boolean |
containsKey(String key)
確定給定 key 是否包含在此 ResourceBundle 及其父包中。 |
static ResourceBundle |
getBundle(String baseName)
使用指定的基本名稱、預設的語言環境和調用者的類別載入器獲取資源套件。 |
static ResourceBundle |
getBundle(String baseName,
Locale locale)
使用指定的基本名稱、語言環境和調用者的類別載入器獲取資源套件。 |
static ResourceBundle |
getBundle(String baseName,
Locale locale,
ClassLoader loader)
使用指定的基本名稱、語言環境和類別載入器獲取資源套件。 |
static ResourceBundle |
getBundle(String baseName,
Locale targetLocale,
ClassLoader loader,
ResourceBundle.Control control)
使用指定基本名稱、目標語言環境、類別載入器和控制元件返回資源套件。 |
static ResourceBundle |
getBundle(String baseName,
Locale targetLocale,
ResourceBundle.Control control)
使用指定基本名稱、目標語言環境和控制元件、調用者的類別載入器返回一個資源套件。 |
static ResourceBundle |
getBundle(String baseName,
ResourceBundle.Control control)
使用指定基本名稱、預設語言環境和指定控制元件返回一個資源套件。 |
abstract Enumeration<String> |
getKeys()
返回鍵的列舉。 |
Locale |
getLocale()
返回此資源套件的語言環境。 |
Object |
getObject(String key)
從此資源包或它的某個父包中獲取給定鍵的物件。 |
String |
getString(String key)
從此資源包或它的某個父包中獲取給定鍵的字元串。 |
String[] |
getStringArray(String key)
從此資源包或它的某個父包中獲取給定鍵的字元串陣列。 |
protected abstract Object |
handleGetObject(String key)
從此資源包中獲取給定鍵的物件。 |
protected Set<String> |
handleKeySet()
返回只 套件含在此 ResourceBundle 中的鍵的 Set。 |
Set<String> |
keySet()
返回此 ResourceBundle 及其父包中包含的所有鍵的 Set。 |
protected void |
setParent(ResourceBundle parent)
設置此套件的父套件。 |
| 從類別 java.lang.Object 繼承的方法 |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| 欄位詳細資訊 |
|---|
protected ResourceBundle parent
getObject 搜尋父套件。
| 建構子詳細資訊 |
|---|
public ResourceBundle()
| 方法詳細資訊 |
|---|
public final String getString(String key)
(String) getObject(key)。
key - 所需字元串的鍵
NullPointerException - 如果 key 為 null
MissingResourceException - 如果未找到給定鍵的物件
ClassCastException - 如果為給定鍵找到的物件是不是字元串public final String[] getStringArray(String key)
(String[]) getObject(key)。
key - 所需字元串陣列的鍵
NullPointerException - 如果 key 為 null
MissingResourceException - 如果未找到給定鍵的物件
ClassCastException - 如果為給定鍵找到的物件不是字元串陣列public final Object getObject(String key)
handleGetObject 從此資源包中獲取物件。如果不成功，並且父資源包不為 null，則調用父套件的 getObject 方法。如果仍不成功，則拋出 MissingResourceException。
key - 所需物件的鍵
NullPointerException - 如果 key 為 null
MissingResourceException - 如果未找到給定鍵的物件public Locale getLocale()
protected void setParent(ResourceBundle parent)
getObject 來搜尋父套件。
parent - 此套件的父套件。public static final ResourceBundle getBundle(String baseName)
getBundle(baseName, Locale.getDefault(), this.getClass().getClassLoader())，
不同之處在於要使用 ResourceBundle 的安全特權來運行 getClassLoader()。有關搜尋和實例化策略的資訊，請參閱 getBundle。
baseName - 資源套件的基本名稱，是一個完全限定類別名
NullPointerException - 如果 baseName 為 null
MissingResourceException - 如果未找到指定基本名稱的資源包
public static final ResourceBundle getBundle(String baseName,
ResourceBundle.Control control)
getBundle(baseName, Locale.getDefault(),
this.getClass().getClassLoader(), control)，
不同之處在於要使用 ResourceBundle 的安全特權來運行 getClassLoader()。有關帶 ResourceBundle.Control 的資源包載入進程的完整描述，請參閱 getBundle。
baseName - 資源套件的基本名稱，一個完全限定類別名control - 為資源包載入進程提供資訊的控制元件
NullPointerException - 如果 baseName 或 control 為 null
MissingResourceException - 如果沒有找到用於指定基本名稱的資源包
IllegalArgumentException - 如果給定 control 沒有正確執行（例如，control.getCandidateLocales 返回 null。）注意，control 的驗證是根據需要執行的。
public static final ResourceBundle getBundle(String baseName,
Locale locale)
getBundle(baseName, locale, this.getClass().getClassLoader())，
不同之處在於要使用 ResourceBundle 的安全特權來運行 getClassLoader()。有關搜尋和實例化策略的資訊，請參閱 getBundle。
baseName - 資源套件的基本名稱，是一個完全限定類別名locale - 資源包所需的語言環境
NullPointerException - 如果 baseName 或 locale 為 null
MissingResourceException - 如果未找到指定基本名稱的資源包
public static final ResourceBundle getBundle(String baseName,
Locale targetLocale,
ResourceBundle.Control control)
getBundle(baseName, targetLocale, this.getClass().getClassLoader(),
control)，
不同之處在於要使用 ResourceBundle 的安全特權來運行 getClassLoader()。有關帶 ResourceBundle.Control 的資源包載入進程的完整描述，請參閱 getBundle。
baseName - 資源套件的基本名稱，一個完全限定類別名targetLocale - 資源包所需的語言環境control - 為資源包載入進程提供資訊的控制元件
locales 中某個 Locale 的資源包
NullPointerException - 如果 baseName、locales 或 control 為 null
MissingResourceException - 如果在任何 locales 中都無法找到用於指定基本名稱的資源套件。
IllegalArgumentException - 如果給定 control 沒有正確執行（例如，control.getCandidateLocales 返回 null。）注意，control 的驗證是根據需要執行的。
public static ResourceBundle getBundle(String baseName,
Locale locale,
ClassLoader loader)
從概念上講，getBundle 使用下列策略來搜尋並實例化資源包：
省略最後部分為空字元串的候選套件名稱。例如，如果 country1 是一個空字元串，則省略第二個候選套件名稱。
然後
如果未找到結果資源包，則拋出
找到了結果資源包後，它的父鏈 將被實例化。
範例：
使用給出的語言環境參數值調用 不使用 MyResources_fr_CH.properties 檔案，因為它被 MyResources_fr_CH.class 隱藏了。類似地，MyResources.properties 也被 MyResources.class 隱藏了。
getBundle 使用基本名稱、指定的語言環境和預設語言環境（從 Locale.getDefault 獲得）來產生候選套件名稱 序列。如果指定語言環境的語言、國家/地區和變數都是空字元串，則基本名稱就是唯一的候選套件名稱。否則，從指定語言環境（language1、country1 和 variant1）和預設語言環境（language2、country2 和 variant2）的屬性值產生下列序列：
getBundle 在候選套件名稱上進行迭代，找到第一個可實例化 為實際資源套件的候選套件名稱。對於每個候選套件名稱，它都試圖創建資源包：
getBundle 將創建此類別的一個新實例，並使用它作為結果資源包。
getBundle 嘗試搜尋屬性資源檔案。它從候選套件名稱產生一個路徑名，用 "/" 替換所有的 "." 字元，並添加字元串 ".properties"。然後嘗試用 ClassLoader.getResource 找到一個具有此名稱的「資源」（注意，getResource 獲得的「資源」與資源包中的內容沒有任何關係，它只是一個資料的容器，如檔案）。如果它找到一個「資源」，則會嘗試用其內容創建一個新的 PropertyResourceBundle。如果成功，那麼此實例就成為結果資源包。
MissingResourceException。
getBundle 在可以獲得的候選套件名稱中進行迭代，獲得名稱的方法是從結果資源套件的套件名稱中連續移除變數、國家/地區和語言（每次都用前綴 "_"）。如上所述，省略最後部分為空字元串的候選套件名稱。對於每個候選套件名稱，都嘗試實例化一個資源包，如上所述。只要能夠成功，就用新的資源包調用先前已實例化資源套件的 setParent 方法，除非先前已實例化的資源包已經有非 null 的父套件。
getBundle 可以快取記憶體已實例化的資源包，並且可以多次返回相同的資源包實例。
baseName 參數應該是一個完全限定類別名。但是，為了與早期的版本相容，Sun 的 Java SE Runtime Environment 並不對此進行檢查，所以可通過指定路徑名（使用 "/"）而不是完全限定類別名（使用 "."）來存取 PropertyResourceBundle。
提供了下面的類別和屬性檔案：
MyResources.class
MyResources.properties
MyResources_fr.properties
MyResources_fr_CH.class
MyResources_fr_CH.properties
MyResources_en.properties
MyResources_es_ES.class
所有檔案的內容都是有效的（也就是說 ".class" 檔案是 ResourceBundle 的公共非抽象子類別，".properties" 檔案的語法正確）。預設的語言環境是 Locale("en", "GB")。
getBundle 將實例化取自以下源的資源包：
baseName - 資源套件的基本名稱，是一個完全限定類別名locale - 資源包所需的語言環境loader - 載入資源套件的類別載入器
NullPointerException - 如果 baseName、locale 或 loader 為 null
MissingResourceException - 如果未找到指定基本名稱的資源包
public static ResourceBundle getBundle(String baseName,
Locale targetLocale,
ClassLoader loader,
ResourceBundle.Control control)
control 參數的 getBundle 處理器方法不同，給定 control 指定尋找和實例化資源套件的方式。從概念上說，具有給定 control 的套件載入進程是按以下步驟執行的。
baseName、targetLocale 和 loader 尋找資源套件。如果在快取記憶體中找到所請求的資源包實例，並且該實例及其所有父實例的生存時間都已經到期，則向調用者返回該實例。否則，此處理器方法繼續進行以下載入進程。control.getFormats 方法獲取產生套件名稱或資源名稱的資源包格式。字元串 "java.class" 和 "java.properties" 分別指定基於類別和基於屬性的資源套件。其他以 "java." 開頭的字元串被保留，供以後擴展使用，不必將它們用於應用程序定義的格式。其他字元串指定應用程序定義的格式。control.getCandidateLocales 方法獲取用於已搜尋到的資源套件的候選 Locale 列表。control.newBundle 方法實例化針對基本套件名稱、候選語言環境和某種格式的 ResourceBundle。（參考下方關於快取記憶體尋找的註釋。）此步驟在所有候選語言環境和格式上進行迭代，直到 newBundle 方法返回一個 ResourceBundle 實例，或者該迭代已經用完了所有的組合。例如，如果候選語言環境是 Locale("de", "DE")、Locale("de") 和 Locale("")，而格式是 "java.class" 和 "java.properties"，那麼以下是用來調用 control.newBundle 的語言環境和格式組合的序列。
| 語言環境 |
格式 |
| Locale("de", "DE") |
java.class |
| Locale("de", "DE") | java.properties |
| Locale("de") | java.class |
| Locale("de") | java.properties |
| Locale("") |
java.class |
| Locale("") | java.properties |
Locale("") 的套件），以及只包含 Locale("") 的候選語言環境列表，則向調用者返回該套件。如果已經找到作為基本套件的包，但候選語言環境列表包含 Locale("") 之外的語言環境，則暫時擱置該套件並前進到步驟 6。如果找到一個不是基本套件的包，則前進到步驟 7。control.getFallbackLocale 方法獲取一個回退語言環境（當前目標語言環境的替代），以嘗試進一步尋找資源套件。如果該方法返回一個非 null 語言環境，那麼該語言環境將變成下一個目標語言環境，並且載入進程將從步驟 3 開始。否則，如果找到一個基本包並在前面的步驟 5 中暫時被擱置，那麼現在要將該語言環境返回給調用者。否則拋出 MissingResourceException。在進行上述資源包載入進程期間，此處理器方法將在調用 control.newBundle 方法之前尋找快取記憶體。如果在該快取記憶體中找到的資源套件的生存時間已到期，則該處理器方法將調用 control.needsReload 方法確定是否需要重載資源套件。如果需要重載，則該處理器方法將調用 control.newBundle 重載資源套件。如果 control.newBundle 返回 null，則該處理器方法將在快取記憶體中放一個偽資源包，以此作為不存在資源套件的標記，從而避免後續請求所帶來的尋找開銷。這類別偽資源包同樣受到 control 所指定的到期時間控制。
所有已載入的資源包都是在預設情況下被快取記憶體的。有關細節請參閱 control.getTimeToLive。
以下是帶有預設 ResourceBundle.Control 實作的套件載入進程的範例。
條件：
foo.bar.Messages
Locale：Locale.ITALYLocale：Locale.FRENCHfoo/bar/Messages_fr.properties 和 foo/bar/Messages.properties首先，getBundle 試圖按以下順序載入資源套件。
foo.bar.Messages_it_IT
foo/bar/Messages_it_IT.properties
foo.bar.Messages_itfoo/bar/Messages_it.propertiesfoo.bar.Messagesfoo/bar/Messages.properties此時，getBundle 找到一個 foo/bar/Messages.properties，該套件被擱置，因為它不是一個基本套件。getBundle 調用返回 Locale.FRENCH 的 control.getFallbackLocale("foo.bar.Messages", Locale.ITALY)。接著，getBundle 試圖按以下順序載入一個套件。
foo.bar.Messages_frfoo/bar/Messages_fr.propertiesfoo.bar.Messagesfoo/bar/Messages.propertiesgetBundle 尋找 foo/bar/Messages_fr.properties 並創建一個 ResourceBundle 實例。然後，getBundle 根據候選語言環境列表設置其父鏈。在該列表中只有 foo/bar/Messages.properties，並且 getBundle 創建一個 ResourceBundle 實例，該實例成為用於 foo/bar/Messages_fr.properties 的實例的父實例。
baseName - 資源套件的基本名稱，一個完全限定類別名targetLocale - 資源包所需的語言環境loader - 載入資源套件的類別載入器control - 為資源包載入進程提供資訊的控制元件
NullPointerException - 如果 baseName、targetLocale、loader 或 control 為 null
MissingResourceException - 如果沒有找到用於指定基本名稱的資源包
IllegalArgumentException - 如果給定 control 沒有正確執行（例如，control.getCandidateLocales 返回 null。）注意，control 的驗證是根據需要執行的。public static final void clearCache()
ResourceBundle.Control.getTimeToLive(String,Locale)public static final void clearCache(ClassLoader loader)
loader - 類別載入器
NullPointerException - 如果 loader 為 nullResourceBundle.Control.getTimeToLive(String,Locale)protected abstract Object handleGetObject(String key)
key - 所需物件的鍵
NullPointerException - 如果 key 為 nullpublic abstract Enumeration<String> getKeys()
ResourceBundle 及其父包中所包含鍵的 Enumeration。public boolean containsKey(String key)
key 是否包含在此 ResourceBundle 及其父包中。
key - 資源 key
key 套件含在此 ResourceBundle 或其父包中，則返回 true；否則返回 false。
NullPointerException - 如果 key 為 nullpublic Set<String> keySet()
ResourceBundle 及其父包中包含的所有鍵的 Set。
Set 及其父包中包含的所有鍵的 Set。protected Set<String> handleKeySet()
ResourceBundle 中的鍵的 Set。
預設實作返回 getKeys 方法返回的鍵的 Set，那些 handleGetObject 方法返回 null 的鍵除外。創建 Set 後，該值就被保存在此 ResourceBundle 中，以避免在下次調用中產生相同的 Set。可在子類別實作中覆寫此方法，以便更快地進行處理。
ResourceBundle 中的鍵的 Set
|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
| 上一個類別 下一個類別 | 框架 無框架 | |||||||||
| 摘要： 巢狀 | 欄位 | 建構子 | 方法 | 詳細資訊： 欄位 | 建構子 | 方法 | |||||||||
版權所有 2008 Sun Microsystems, Inc. 保留所有權利。請遵守GNU General Public License, version 2 only。