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 方法，以避免使用錯誤的資源和類別名稱分隔符。

兩個處理器方法 getControl(List) 和 getNoFallbackControl(List) 都提供 ResourceBundle.Control 實例，這些實例實作預設包載入進程的常見變數。

在相同基本套件的所有 ResourceBundle.getBundle 調用中，getFormats 方法返回的格式和 getCandidateLocales 方法返回的候選語言環境必須一致。否則，ResourceBundle.getBundle 方法返回意料之外的套件。例如，如果 getFormats 方法在第一次調用 ResourceBundle.getBundle 時只返回 "java.class"，第二次調用時只返回 "java.properties"，那麼第二次調用返回的基於類別的套件將是在第一次調用過程中快取記憶體的那個套件。

如果 ResourceBundle.Control 實例被多個執行緒同時使用，則它必須是執行緒安全的。ResourceBundle.getBundle 不會同時調用 ResourceBundle.Control 方法。方法的預設實作是執行緒安全的。

應用程序可以指定 getControl 處理器方法返回的 ResourceBundle.Control 實例，也可以指定從 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) {
// Disable caches to get fresh data for
// reloading.
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 包含 "java.class" 的純類別 (class-only) 格式 List。
static List<String>	FORMAT_DEFAULT 預設的格式 List，它包含字元串 "java.class" 和 "java.properties"（按此順序）。
static List<String>	FORMAT_PROPERTIES 包含 "java.properties" 的純屬性 (properties-only) 格式 List。
static long	TTL_DONT_CACHE 不快取記憶體已載入資源包實例的生存時間常數。
static long	TTL_NO_EXPIRATION_CONTROL 對快取記憶體中已載入資源包實例禁用到期控制的生存時間常數。

建構子摘要

protected

ResourceBundle.Control() 唯一的建構子。

方法摘要

List<Locale>	getCandidateLocales(String baseName, Locale locale) 返回 Locale 的 List，作為 baseName 和 locale 的候選語言環境。
static ResourceBundle.Control	getControl(List<String> formats) 返回 ResourceBundle.Control，getFormats 方法在其中返回指定的 formats。
Locale	getFallbackLocale(String baseName, Locale locale) 返回一個要用作回退語言環境的 Locale，用於 ResourceBundle.getBundle 處理器方法進行進一步資源包搜尋。
List<String>	getFormats(String baseName) 返回 String 的 List，它包含要用於載入給定 baseName 的資源套件的格式。
static ResourceBundle.Control	getNoFallbackControl(List<String> formats) 返回一個 ResourceBundle.Control，getFormats 方法在其中返回指定的 formats，getFallbackLocale 方法在其中返回 null。
long	getTimeToLive(String baseName, Locale locale) 返回在此 ResourceBundle.Control 下載入的資源包生存時間 (TTL) 值。
boolean	needsReload(String baseName, Locale locale, String format, ClassLoader loader, ResourceBundle bundle, long loadTime) 確定是否需要根據 loadTime 或其他標準給出的載入時間重載快取記憶體中已到期的 bundle。
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 方法要求的形式：用 '/' 替換 bundleName 中出現的所有 '.'，並添加一個 '.' 和給定的檔案 suffix。

從類別 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

包含 "java.class" 的純類別 (class-only) 格式 List。此 List 不可修改。

另請參見：

getFormats(String)

FORMAT_PROPERTIES

public static final List<String> FORMAT_PROPERTIES

包含 "java.properties" 的純屬性 (properties-only) 格式 List。此 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)

返回 ResourceBundle.Control，getFormats 方法在其中返回指定的 formats。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 未知

getNoFallbackControl

public static final ResourceBundle.Control getNoFallbackControl(List<String> formats)

返回一個 ResourceBundle.Control，getFormats 方法在其中返回指定的 formats，getFallbackLocale 方法在其中返回 null。formats 必須等於 FORMAT_PROPERTIES、FORMAT_CLASS 或 FORMAT_DEFAULT 之一。此方法返回的 ResourceBundle.Control 實例是單獨且執行緒安全的。

參數：

formats - ResourceBundle.Control.getFormats 方法要返回的格式

返回：

支持指定 formats 的 ResourceBundle.Control，不支持任何回退 Locale

拋出：

NullPointerException - 如果 formats 為 null

IllegalArgumentException - 如果 formats 未知

getFormats

public List<String> getFormats(String baseName)

返回 String 的 List，它包含要用於載入給定 baseName 的資源套件的格式。ResourceBundle.getBundle 處理器方法嘗試使用按列表指定順序的格式載入資源套件。此方法返回的列表必須至少有一個 String。對於基於類別的資源包，預定義的格式是 "java.class"，對於 properties-based 資源包，預定義的格式是 "java.properties"。以 "java." 開頭的字元串是為將來擴展而保留的，不得被應用程序定義的格式使用。

不必返回一個不可變的（不可修改的） List。但是，返回的 List 在由 getFormats 返回後不得改變。

預設實作返回 FORMAT_DEFAULT，以便 ResourceBundle.getBundle 處理器方法首先尋找基於類別的資源包，然後尋找基於屬性的資源套件。

參數：

baseName - 資源套件的基本名稱，是一個完全限定類別名

返回：

String 的 List，它包含載入資源套件的格式。

拋出：

NullPointerException - 如果 baseName 為 null

另請參見：

FORMAT_DEFAULT, FORMAT_CLASS, FORMAT_PROPERTIES

getCandidateLocales

public List<Locale> getCandidateLocales(String baseName,
                                        Locale locale)

返回 Locale 的 List，作為 baseName 和 locale 的候選語言環境。在處理器方法每次嘗試為目標 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

getFallbackLocale

public Locale getFallbackLocale(String baseName,
                                Locale locale)

返回一個要用作回退語言環境的 Locale，用於 ResourceBundle.getBundle 處理器方法進行進一步資源包搜尋。每次找不到任何對應於 baseName 和 locale 的所得資源包時（其中 locale 是 ResourceBundle.getBundle 的參數，或者此方法以前返回的回退語言環境），從處理器方法調用此方法。

如果不需要進一步的回退搜尋，那麼該方法返回 null。

如果給定 locale 不是預設的，那麼預設實作返回預設 Locale。否則，返回 null。

參數：

baseName - 資源套件的基本名稱，是一個完全限定類別名，ResourceBundle.getBundle 無法為其找到任何資源包（基本包除外）

locale - ResourceBundle.getBundle 無法為其找到任何資源包（基本包除外）的 Locale

返回：

回退搜尋的 Locale；如果不需要進一步的搜尋，則返回 null。

拋出：

NullPointerException - 如果 baseName 或 locale 為 null

newBundle

public ResourceBundle newBundle(String baseName,
                                Locale locale,
                                String format,
                                ClassLoader loader,
                                boolean reload)
                         throws IllegalAccessException,
                                InstantiationException,
                                IOException

針對給定格式和語言環境的給定套件名稱，實例化一個資源包，如有必要，可使用給定的類別載入器。如果對於給定參數沒有任何可用的資源包，則此方法返回 null。如果資源包由於無法預料的錯誤而不能被實例化，則必須通過拋出 Error 或 Exception 來報告錯誤，而不是簡單地返回 null。

如果 reload 標誌為 true，則它表示由於以前載入的資源包已到期而調用此方法。

預設實作按如下方法實例化 ResourceBundle。

• 通過調用 toBundleName(baseName, locale) 獲取套件名稱。
• 如果 format 為 "java.class"，則通過調用 ClassLoader.loadClass(String) 載入由套件名稱指定的 Class。然後，通過調用 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 - 要用於載入套件的 ClassLoader

reload - 用於表示重新載入套件的標誌；如果重新載入到期的資源包，則為 true，否則為 false

返回：

資源包實例；如果未找到任何實例，則返回 null。

拋出：

NullPointerException - 如果 bundleName、locale、format 或 loader 為 null，或者 toBundleName 返回 null

IllegalArgumentException - 如果 format 未知，或者為給定參數找到的資源包含錯誤資料。

ClassCastException - 如果已載入類別無法被強制轉換為 ResourceBundle

IllegalAccessException - 如果類別或其 null 建構子無法存取。

InstantiationException - 如果類別的實例化由於某些其他原因而失敗。

ExceptionInInitializerError - 如果此方法引起的初始化失敗。

SecurityException - 如果安全管理器存在並且拒絕創建新實例。有關詳細資訊，請參閱 Class.newInstance()。

IOException - 如果在使用任意 I/O 操作讀取資源時發生錯誤

getTimeToLive

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 - 為其指定到期值的資源包語言環境。

返回：

時間（0 或從快取記憶體時間到現在的正毫秒數），表示獲取快取記憶體中已載入資源套件的到期時間；TTL_NO_EXPIRATION_CONTROL 表示禁用到期控制；TTL_DONT_CACHE 表示禁用快取記憶體。

拋出：

NullPointerException - 如果 baseName 或 locale 為 null

needsReload

public boolean needsReload(String baseName,
                           Locale locale,
                           String format,
                           ClassLoader loader,
                           ResourceBundle bundle,
                           long loadTime)

確定是否需要根據 loadTime 或其他標準給出的載入時間重載快取記憶體中已到期的 bundle。如果需要重載，那麼此方法返回 true，否則返回 false。loadTime 是從 Calendar Epoch 到現在的毫秒數。 調用 ResourceBundle.getBundle 處理器方法在用於其當前調用的 ResourceBundle.Control 實例上調用此方法，而不是在最初載入資源套件的調用中所使用的實例上調用此方法。

預設實作將 loadTime 和資源包源資料上一次的修改時間進行比較。如果確定自 loadTime 以來修改過源資料，則返回 true。否則，返回 false。如果給定 format 不是預設格式 "java.class" 或 "java.properties" 之一，此實作假定它是與其檔案後綴相同的字元串。

參數：

baseName - 資源套件的基本名稱，是一個完全限定類別名

locale - 應為其實例化資源套件的語言環境

format - 要載入的資源包格式

loader - 要用來載入套件的 ClassLoader

bundle - 快取記憶體中已到期的資源包實例

loadTime - bundle 被載入並放入快取記憶體的時間

返回：

如果到期的套件需要重新載入，則返回 true；否則返回 false。

拋出：

NullPointerException - 如果 baseName、locale、format、loader 或 bundle 為 null

toBundleName

public String toBundleName(String baseName,
                           Locale locale)

將給定 baseName 和 locale 轉換為套件名稱。此方法從 newBundle 和 needsReload 方法的預設實作調用。

此實作返回以下值：

baseName + "_" + language + "_" + country + "_" + variant
 

其中 language、country 和 variant 分別是語言、國家/地區和 locale 的變數值。為空字元串的最後部分的值與 '_' 之前的部分一起被忽略。如果所有值都為空字元串，則返回 baseName。

例如，如果 baseName 為 "baseName"、locale 為 Locale("ja", "", "XX")，則返回 "baseName_ja_ _XX"。如果給定語言環境為 Locale("en")，則返回 "baseName_en"。

覆寫此方法允許應用程序在本地化資源的組織和打包中使用不同的約定。

參數：

baseName - 資源套件的基本名稱，是一個完全限定類別名

locale - 應當為其載入資源套件的語言環境

返回：

資源套件的套件名稱

拋出：

NullPointerException - 如果 baseName 或 locale 為 null

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 或 suffix 為 null