ResourceBundle

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM 2 Platform
Standard Ed. 5.0

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

java.util
类 ResourceBundle

java.lang.Object
  java.util.ResourceBundle

直接已知子类：: ListResourceBundle, PropertyResourceBundle

public abstract class ResourceBundle
extends Object
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);

资源包包含键/值对。键惟一地标识了包中的特定于语言环境的对象。下面是一个 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"。在上面的示例中，值也是 String 类型，即 "OK" 和 "Cancel"，但并非必须如此。值可以是任意对象类型。

可以使用适当的 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 的子类，即 ListResourceBundle 和 PropertyResourceBundle，这为创建资源提供了一种相当简单的方式。正如在前面示例中所看到的，ListResourceBundle 以键/值对的列表方式管理其资源。PropertyResourceBundle 则使用一个属性文件来管理其资源。

如果 ListResourceBundle 或 PropertyResourceBundle 无法满足您的需求，那么可以编写自己的 ResourceBundle 子类。子类必须重写这两个方法：handleGetObject 和 getKeys()。

下面是一个极其简单的 ResourceBundle 子类示例——MyResources，它管理两个资源（对于大量的资源，可能应该使用 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 等）和窗口小部件 WidgetResource 的包集合（WidgetResources_fr、WidgetResources_de 等）；可以按自己喜欢的方式分解资源。

从以下版本开始：: 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()` 返回此资源包的语言环境。
`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()

返回此资源包的语言环境。调用 getBundle() 后可使用此方法来确定返回的资源包是否真正对应于所请求的语言环境，或者只是一个回退。

返回：: 此资源包的语言环境。

setParent

protected void setParent(ResourceBundle parent)

设置此包的父包。当此包不包含特定的资源时，通过 getObject 来搜索父包。

参数：: parent - 此包的父包。

getBundle

public static final ResourceBundle getBundle(String baseName)

使用指定的基本名称、默认的语言环境和调用方的类加载器获取资源包。调用此方法等效于调用：

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

除了要使用 ResourceBundle 的安全特权来运行 getClassLoader()。有关搜索和实例化策略的信息，请参阅 getBundle。

参数：: baseName - 资源包的基本名称，是一个完全限定类名。
返回：: 具有给定基本名称和默认语言环境的资源包。
抛出：: NullPointerException - 如果 baseName 为 null。; MissingResourceException - 如果未找到指定基本名称的资源包。

getBundle

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 - 如果未找到指定基本名称的资源包。

getBundle

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

使用指定的基本名称、语言环境和类加载器获取资源包。

从概念上讲，getBundle 使用下列策略来搜索并实例化资源包：

getBundle 使用基本名称、指定的语言环境和默认语言环境（从 Locale.getDefault 获得）来生成候选包名称 序列。如果指定语言环境的语言、国家/地区和变量都是空字符串，则基本名称就是惟一的候选包名称。否则，从指定语言环境 (language1, country1, and variant1) 和默认语言环境 (language2, country2, and variant2) 的属性值生成下列序列：

baseName + "_" + language1 + "_" + country1 + "_" + variant1
baseName + "_" + language1 + "_" + country1
baseName + "_" + language1
baseName + "_" + language2 + "_" + country2 + "_" + variant2
baseName + "_" + language2 + "_" + country2
baseName + "_" + language2
baseName

省略最后部分为空的候选包名称。例如，如果 country1 是一个空字符串，则省略第二个候选包名称。

getBundle 然后在候选包名称上进行迭代，找到第一个可实例化 为实际资源包的候选包名称。对于每个候选包名称，它都试图创建资源包：

首先，它试图使用候选包名称加载一个类。如果可以找到这样的类并使用指定的类加载器将其加载，并且如果此类的分配与 ResourceBundle 兼容并可从 ResourceBundle 访问它，还可以将其实例化，则 getBundle 创建此类的一个新实例，并使用它作为结果资源包。
否则，getBundle 会试图搜索属性资源文件。它从候选包名称生成一个路径名，方法是用 "/" 替换所有的 "." 字符并追加字符串 ".properties"。然后试图用 ClassLoader.getResource 找到一个具有此名称的“资源”（注意，getResource 中的“资源”与资源包中的内容没有任何关系，它只是一个数据的容器，如文件）。如果它找到一个“资源”，则会试图用其内容创建一个新的 PropertyResourceBundle。如果成功，那么此实例就成为结果资源包。

如果未找到结果资源包，则抛出 MissingResourceException。

一旦找到了结果资源包，那么它的父链就是已实例化的。getBundle 在可以获得的候选包名称中进行迭代，获得名称的方法是从结果资源包的包名称中连续移除变量、国家/地区和语言（每次都用前缀 "_"）。正如上面所述，省略最后组件是空字符串的候选包名称。对于每个候选包名称，它都会试图实例化一个资源包，如上所述。只要能够成功，它就用新的资源包调用先前已实例化资源包的 setParent 方法，除非先前已实例化的资源包已经有非 null 的父包。

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"):结果 MyResources_fr_CH.class，父 MyResources_fr.properties，父 MyResources.class
Locale("fr", "FR"):结果 MyResources_fr.properties，父 MyResources.class
Locale("de", "DE"):结果 MyResources_en.properties，父 MyResources.class
Locale("en", "US"):结果 MyResources_en.properties，父 MyResources.class
Locale("es", "ES"):结果 MyResources_es_ES.class，父 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()

返回键的枚举。

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM 2 Platform
Standard Ed. 5.0

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。