鸿蒙OS ResourceBundle

ResourceBundle

java.lang.Object

|—java.util.ResourceBundle

public abstract class ResourceBundle
extends Object

资源包包含特定于语言环境的对象。 当您的程序需要特定于语言环境的资源（例如字符串）时，您的程序可以从适合当前用户语言环境的资源包中加载它。 通过这种方式，您可以编写在很大程度上独立于用户语言环境的程序代码，从而将资源包中的大多数（如果不是全部）特定于语言环境的信息隔离开来。

这使您可以编写能够：

• 易于本地化或翻译成不同的语言
• 一次处理多个语言环境
• 稍后可以轻松修改以支持更多语言环境

资源包属于其成员共享一个通用基本名称的系列，但其名称还具有标识其语言环境的附加组件。 例如，资源包系列的基本名称可能是“MyResources”。 该系列应该有一个默认资源包，它与它的系列具有相同的名称 – “MyResources” – 如果不支持特定的语言环境，它将被用作最后的资源包。 然后，该家族可以根据需要提供尽可能多的特定于语言环境的成员，例如名为“MyResources_de”的德国成员。

一个系列中的每个资源包都包含相同的项目，但这些项目已针对该资源包所代表的语言环境进行了翻译。 例如，“MyResources”和“MyResources_de”都可能有一个用于取消操作的按钮的字符串。 在“MyResources”中，字符串可能包含“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
        };
     }
 }

键始终是字符串。 在本例中，键是“OkKey”和“CancelKey”。 在上面的例子中，值也是字符串——“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 平台提供了 ResourceBundle 的两个子类，ListResourceBundle 和 PropertyResourceBundle，它们提供了一种相当简单的方法来创建资源。 正如您在前面的示例中简要看到的，ListResourceBundle 将其资源作为键/值对列表进行管理。 PropertyResourceBundle 使用属性文件来管理其资源。

如果 List ResourceBundle 或 PropertyResourceBundle 不适合您的需要，您可以编写自己的 ResourceBundle 子类。 您的子类必须覆盖两个方法：处理 GetObject 和获取 Keys()。

如果 ResourceBundle 子类同时被多个线程使用，则它的实现必须是线程安全的。 该类中非抽象方法的默认实现，以及直接已知的具体子类 ListResourceBundle 和 PropertyResourceBundle 中的方法都是线程安全的。

ResourceBundle.Control ResourceBundle.Control 类提供了通过采用 ResourceBundle.Control 实例的 getBundle 工厂方法执行包加载过程所需的信息。 您可以实现自己的子类以启用非标准资源包格式、更改搜索策略或定义缓存参数。

对于不采用 Control 实例的 getBundle 工厂方法，可以使用已安装的 ResourceBundleControlProvider 实现来修改它们加载资源包的默认行为。 在 ResourceBundle 类加载时检测到任何已安装的提供程序。 如果任何提供程序为给定的基本名称提供了 Control，则将使用该 Control 而不是默认 Control。 如果安装了多个服务提供者来支持相同的基本名称，则将使用从 ServiceLoader 返回的第一个。

缓存管理 getBundle 工厂方法创建的资源包实例默认被缓存，如果已经缓存，工厂方法会多次返回同一个资源包实例。 getBundle 客户端可以清除缓存，使用生存时间值管理缓存的资源包实例的生命周期，或者指定不缓存资源包实例。下面是 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, …)； 随心所欲地分解资源。

嵌套类摘要

字段摘要

构造函数摘要

方法总结

字段详细信息

parent

protected ResourceBundle parent

此捆绑包的父捆绑包。 当此捆绑包不包含特定资源时，getObject 将搜索父捆绑包。

构造函数详细信息

ResourceBundle

public ResourceBundle()

唯一的构造函数。 （用于子类构造函数的调用，通常是隐式的。）

方法详情

getBaseBundleName

public String getBaseBundleName()

如果已知，则返回此捆绑包的基本名称，如果未知，则返回 null。 如果不为 null，则这是加载资源包时传递给 ResourceBundle.getBundle(…) 方法的 baseName 参数的值。

返回:

资源包的基本名称，由 ResourceBundle.getBundle(…) 方法提供和预期。

getString

public final String getString(String key)

从此资源包或其父资源包中获取给定键的字符串。 调用该方法相当于调用

(String) getObject(key).

参数:

返回:

给定键的字符串

Throws:

getStringArray

public final String[] getStringArray(String key)

从此资源包或其父资源包中获取给定键的字符串数组。 调用该方法相当于调用

(String[]) getObject(key).

参数:

返回:

给定键的字符串数组

Throws:

getObject

public final Object getObject(String key)

从此资源包或其父资源包中获取给定键的对象。 此方法首先尝试使用 handleGetObject 从此资源包中获取对象。 如果不成功，并且父资源包不为空，则调用父资源的 getObject 方法。 如果仍然不成功，则抛出 MissingResourceException。

参数：

返回:

给定键的对象

Throws:

getLocale

public Locale getLocale()

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

返回:

此资源包的语言环境

setParent

protected void setParent(ResourceBundle parent)

设置此捆绑包的父捆绑包。 当此捆绑包不包含特定资源时，getObject 将搜索父捆绑包。

参数：

getBundle

public static final ResourceBundle getBundle(String baseName)

使用指定的基本名称、默认语言环境和调用者的类加载器获取资源包。 调用该方法相当于调用

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

除了 getClassLoader() 以 ResourceBundle 的安全权限运行。

参数：

返回:

给定基本名称和默认语言环境的资源包

Throws:

getBundle

public static final ResourceBundle getBundle(String baseName, ResourceBundle.Control control)

使用指定的基本名称、默认语言环境和指定的控件返回资源包。 调用该方法相当于调用

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

除了 getClassLoader() 以 ResourceBundle 的安全权限运行。

参数：

返回:

给定基本名称和默认语言环境的资源包

Throws:

getBundle

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

使用指定的基本名称和语言环境以及调用者的类加载器获取资源包。 调用该方法相当于调用

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

除了 getClassLoader() 以 ResourceBundle 的安全权限运行。

参数：

返回:

给定基本名称和语言环境的资源包

Throws:

getBundle

public static final ResourceBundle getBundle(String baseName, Locale targetLocale, ResourceBundle.Control control)

使用指定的基本名称、目标语言环境和控件以及调用者的类加载器返回资源包。 调用该方法相当于调用

 getBundle(baseName, targetLocale, this.getClass().getClassLoader(),
           control),

除了 getClassLoader() 以 ResourceBundle 的安全权限运行。

参数：

返回:

给定基本名称的资源包和语言环境中的语言环境

Throws:

getBundle

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

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

此方法的行为与调用 getBundle(java.lang.String,java.util.Locale,java.lang.ClassLoader,java.util.ResourceBundle.Control) 并传递 Control 的默认实例相同，除非 ResourceBundleControlProvider SPI 提供了另一个 Control . 参考修改默认行为的说明。

下面描述了默认行为。

getBundle 使用基本名称、指定的语言环境和默认语言环境（从 Locale.getDefault 获得）来生成一系列候选包名称。 如果指定语言环境的语言、脚本、国家和变体都是空字符串，则基本名称是唯一的候选包名称。 否则，将根据指定区域设置（语言、脚本、国家和变体）的属性值生成候选区域设置列表，并将其附加到基本名称。 通常，这将如下所示：

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

最后一个组件为空字符串的候选包名称以及下划线将被省略。 例如，如果 country 是一个空字符串，则上面的第二个和第五个候选捆绑包名称将被省略。 此外，如果 script 为空字符串，则省略包括 script 在内的候选名称。 例如，语言为“de”且变体为“JAVA”的语言环境将生成以下基本名称为“MyResource”的候选名称。

     MyResource_de__JAVA
     MyResource_de

在变体包含一个或多个下划线 (‘_’) 的情况下，通过截断最后一个下划线及其后面的部分生成的包名称序列将插入到具有原始变体的候选包名称之后。 例如，对于语言为“en”、脚本“Latn”、国家/地区“US”和变体“WINDOWS_VISTA”以及捆绑包基本名称“MyResource”的语言环境，将生成以下候选捆绑包名称列表：

 MyResource_en_Latn_US_WINDOWS_VISTA
 MyResource_en_Latn_US_WINDOWS
 MyResource_en_Latn_US
 MyResource_en_Latn
 MyResource_en_US_WINDOWS_VISTA
 MyResource_en_US_WINDOWS
 MyResource_en_US
 MyResource_en

注意：对于某些语言环境，候选捆绑包名称列表包含额外的名称，或者捆绑包名称的顺序略有修改。

getBundle 然后遍历候选包名称以找到第一个可以实例化实际资源包的名称。 它使用默认控件的 Control#getFormats 方法，该方法为每个生成的名称生成两个包名称，第一个是类名，第二个是属性文件名。 对于每个候选包名称，它会尝试创建一个资源包：

• 首先，它尝试使用生成的类名加载一个类。 如果可以使用指定的类加载器找到并加载这样的类，与 ResourceBundle 的分配兼容，可以从 ResourceBundle 访问，并且可以实例化，则 getBundle 创建此类的新实例并将其用作结果资源包。
• 否则，getBundle 会尝试使用生成的属性文件名来定位属性资源文件。 它通过替换所有“。”从候选包名称生成路径名称。 带有“/”的字符并附加字符串“.properties”。 它尝试使用 ClassLoader.getResource 查找具有此名称的“资源”。 （请注意，getResource 意义上的“资源”与资源包的内容无关，它只是数据的容器，例如文件。）如果找到“资源”，它会尝试创建 从其内容中创建一个新的 PropertyResourceBundle 实例。 如果成功，此实例将成为结果资源包。

这一直持续到结果资源包被实例化或候选包名称列表用完为止。 如果没有找到匹配的资源包，则调用默认控件的 Control#getFallbackLocale 方法，该方法返回当前的默认语言环境。 使用此语言环境生成一个新的候选语言环境名称序列，并再次搜索，如上所述。

如果仍然没有找到结果包，则仅查找基本名称。 如果这仍然失败，则会引发 MissingResourceException。

一旦找到结果资源包，就会实例化其父链。 如果结果包已经有一个父级（可能是因为它是从缓存中返回的），则链是完整的。

否则，getBundle 会检查在生成结果资源包的过程中使用的候选语言环境列表的其余部分。 （和以前一样，最终组件为空字符串的候选包名称被省略。）当涉及到候选列表的末尾时，它会尝试纯包名称。 对于每个候选包名称，它都会尝试实例化一个资源包（首先查找一个类，然后查找一个属性文件，如上所述）。

无论何时成功，它都会使用新的资源包调用先前实例化的资源包的 setParent 方法。 这一直持续到名称列表用完或当前捆绑包已经有一个非空父级。

父链完成后，将返回捆绑包。

注意：getBundle 缓存实例化的资源包，并可能多次返回相同的资源包实例。

注意：baseName 参数应该是一个完全限定的类名。 但是，为了与早期版本兼容，Sun 的 Java SE 运行时环境不会验证这一点，因此可以通过指定路径名（使用“/”）而不是完全限定的类名（使用“.”）来访问 PropertyResourceBundles .

例子：

提供了以下类和属性文件：

     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 将实例化资源包，如下所示：

文件 MyResources_fr_CH.properties 从未使用过，因为它被 MyResources_fr_CH.class 隐藏。 同样，MyResources.properties 也被 MyResources.class 隐藏。

参数：

返回:

给定基本名称和语言环境的资源包

Throws:

getBundle

public static ResourceBundle getBundle(String baseName, Locale targetLocale, ClassLoader loader, ResourceBundle.Control control)

使用指定的基本名称、目标语言环境、类加载器和控件返回资源包。 与没有 controlargument 的 getBundlefactory 方法不同，给定的控件指定如何定位和实例化资源包。 从概念上讲，具有给定控件的包加载过程在以下步骤中执行。

1. 此工厂方法在缓存中查找指定 baseName、targetLocale 和 loader 的资源包。 如果在缓存中找到所请求的资源包实例，并且该实例及其所有父实例的生存时间都未到期，则将该实例返回给调用者。 否则，这个工厂方法会继续下面的加载过程。
2. 调用 ResourceBundle.Control#getFormats(String) 方法来获取资源包格式以生成包或资源名称。 字符串“java.class”和“java.properties”分别指定基于类和基于PropertyResourceBundle 的资源包。 其他以“java”开头的字符串。 保留用于将来的扩展，不得用于应用程序定义的格式。 其他字符串指定应用程序定义的格式。
3. 使用目标语言环境调用 ResourceBundle.Control#getCandidateLocales(String, Locale) 方法以获取搜索资源包的候选语言环境列表。
4. 调用 ResourceBundle.Control#newBundle(String, Locale, String, ClassLoader, boolean) 方法来为基本包名称、候选区域设置和格式实例化 ResourceBundle。 （请参阅下面有关缓存查找的注释。）此步骤迭代候选语言环境和格式的所有组合，直到 newBundle 方法返回 ResourceBundle 实例或迭代已用完所有组合。 例如，如果候选语言环境是 Locale(“de”, “DE”)、Locale(“de”) 和 Locale(“”) 并且格式是 “java.class” 和 “java.properties”，则以下 是用于调用 control.newBundle 的区域设置格式组合序列。
5. 如果上一步没有找到资源包，则继续步骤 6。如果找到的包是基本包（Locale(“”) 的包），并且候选语言环境列表仅包含 Locale(“”)， 将捆绑包返回给调用者。 如果发现一个捆绑包是基本捆绑包，但候选语言环境列表包含 Locale(“”) 以外的语言环境，则暂停捆绑包并继续执行步骤 6。如果发现一个捆绑包不是基础捆绑包 ，继续执行步骤 7。
6. 调用 ResourceBundle.Control#getFallbackLocale(String, Locale) 方法来获取备用语言环境（替代当前目标语言环境）以尝试进一步查找资源包。 如果该方法返回一个非空语言环境，它将成为下一个目标语言环境，并且加载过程从第 3 步开始。否则，如果在前面的第 5 步中找到并搁置了一个基本包，则将其返回给调用者 现在。 否则，将引发 MissingResourceException。
7. 至此，我们找到了一个不是基本包的资源包。 如果此捆绑包在其实例化期间设置了其父级，则将其返回给调用者。 否则，它的父链会根据它所在的候选区域列表进行实例化。 最后，捆绑包返回给调用者。

在上面的资源包加载过程中，这个工厂方法会在调用 Control#newBundle(String, Locale, String, ClassLoader, boolean) 方法之前查找缓存。 如果缓存中找到的资源包的生存期已经过期，工厂方法调用ResourceBundle.Control#needsReload(String, Locale, String, ClassLoader, ResourceBundle, long)方法判断资源包是否需要 要重新加载。 如果需要重新加载，工厂方法调用 control.newBundle 来重新加载资源包。 如果 control.newBundle 返回 null，工厂方法会将一个虚拟资源包放入缓存中，作为不存在资源包的标记，以避免后续请求的查找开销。 此类虚拟资源束处于与 control 指定的相同的过期控制之下。

默认情况下，所有加载的资源包都被缓存。

以下是使用默认 ResourceBundle.Control 实现的包加载过程的示例。

条件：

• 基本包名称：foo.bar.Messages
• 请求的语言环境：Locale#ITALY
• 默认语言环境：语言环境#FRENCH
• 可用资源包：foo/bar/Messages_fr.properties 和 foo/bar/Messages.properties

首先，getBundle 尝试按以下顺序加载资源包。

• 类 foo.bar.Messages_it_IT
• 文件 foo/bar/Messages_it_IT.properties
• 类 foo.bar.Messages_it
• 文件 foo/bar/Messages_it.properties
• 类 foo.bar.Messages
• 文件 foo/bar/Messages.properties

此时，getBundle 找到 foo/bar/Messages.properties，因为它是基本包，所以将其搁置。 getBundle 调用返回 Locale.FRENCH 的 Control#getFallbackLocale(String, Locale)。 接下来，getBundle 尝试按以下顺序加载包。

• 类 foo.bar.Messages_fr
• 文件 foo/bar/Messages_fr.properties
• 类 foo.bar.Messages
• 文件 foo/bar/Messages.properties

getBundle 找到 foo/bar/Messages_fr.properties 并创建一个 ResourceBundle 实例。 然后，getBundle 从候选语言环境列表中设置其父链。 在列表中仅找到 foo/bar/Messages.properties，getBundle 创建一个 ResourceBundle 实例，该实例成为 foo/bar/Messages_fr.properties 实例的父级。

参数：

返回:

给定基本名称和语言环境的资源包

Throws:

clearCache

public static final void clearCache()

从缓存中删除所有已使用调用者的类加载器加载的资源包。

clearCache

public static final void clearCache(ClassLoader loader)

从缓存中删除所有使用给定类加载器加载的资源包。

参数：

Throws:

handleGetObject

protected abstract Object handleGetObject(String key)

从此资源包中获取给定键的对象。 如果此资源包不包含给定键的对象，则返回 null。

参数：

返回:

给定键的对象，或 null

Throws:

getKeys

public abstract EnumerationString getKeys()

返回键的枚举。

返回:

此 ResourceBundle 及其父捆绑包中包含的键的枚举。

containsKey

public boolean containsKey(String key)

确定给定键是否包含在此 ResourceBundle 或其父捆绑包中。

参数：

返回:

如果给定键包含在此 ResourceBundle 或其父包中，则为 true； 否则为 false。

Throws:

keySet

public SetString keySet()

返回包含在此 ResourceBundle 及其父捆绑包中的所有键的 Set。

返回:

此 ResourceBundle 及其父捆绑包中包含的所有键的集合。

handleKeySet

protected SetString handleKeySet()

返回仅包含在此 ResourceBundle 中的一组键。

默认实现返回由 getKeys 方法返回的一组键，除了 handleGetObject 方法返回 null 的键。 创建 Set 后，该值将保存在此 ResourceBundle 中，以避免在后续调用中生成相同的 Set。 子类可以重写此方法以加快处理速度。

返回:

仅包含在此 ResourceBundle 中的一组键