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));
 

示例 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

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