Customizing Resource Bundle Loading

Earlier in this lesson you have learned how to create and access objects of the ResourceBundle class. This section extents your knowledge and explains how to take an advantage from the ResourceBundle.Control class capabilities.

The ResourceBundle.Control was created to specify how to locate and instantiate resource bundles. It defines a set of callback methods that are invoked by the ResourceBundle.getBundle factory methods during the bundle loading process.

Unlike a ResourceBundle.getBundle method described earlier, this ResourceBundle.getBundle method defines a resource bundle using the specified base name, the default locale and the specified control.

public static final ResourceBundle getBundle(
    String baseName,
    ResourceBundle.Control cont
    // ...

The specified control provide information for the resource bundle loading process.

The following sample program called RBControl.java illustrates how to define your own search paths for Chinese locales.

1. Create the properties Files.

As it was described before you can load your resources either from classes or from properties files. These files contain descriptions for the following locales:

• RBControl.properties – Global
• RBControl_zh.properties – Language only: Simplified Chinese
• RBControl_zh_cn.properties – Region only: China
• RBControl_zh_hk.properties – Region only: Hong Kong
• RBControl_zh_tw.properties – Taiwan

In this example an application creates a new locale for the Hong Kong region.

2. Create a ResourceBundle instance.

As in the example in the previous section, this application creates a ResourceBundle instance by invoking the getBundle method:

private static void test(Locale locale) {
    ResourceBundle rb =
        ResourceBundle.getBundle(
            "RBControl",
            locale,
            new ResourceBundle.Control() {
                // ...

The getBundle method searches for properties files with the RBControl prefix. However, this method contains a Control parameter, which drives the process of searching the Chineese locales.

3. Invoke the getCandidateLocales method

The getCandidateLocales method returns a list of the Locales objects as candidate locales for the base name and locale.

new ResourceBundle.Control() {
    @Override
    public List<Locale>
        getCandidateLocales(
            String baseName,
            Locale locale) {
                // ...                                        

The default implementation returns a list of the Locale objects as follows: Locale(language, country).

However, this method is overriden to implement the following specific behavior:

if (baseName == null)
    throw new NullPointerException();
if (locale.equals(new Locale("zh", "HK"))) {
    return Arrays.asList(
        locale,
        Locale.TAIWAN,
        // no Locale.CHINESE here
        Locale.ROOT);
} else if (locale.equals(Locale.TAIWAN)) {
    return Arrays.asList(
        locale,
        // no Locale.CHINESE here
        Locale.ROOT);
}

Note, that the last element of the sequence of candidate locales must be a root locale.

4. Call the test class

Call the test class for the following four different locales:

public static void main(String[] args) {
    test(Locale.CHINA);
    test(new Locale("zh", "HK"));
    test(Locale.TAIWAN);
    test(Locale.CANADA);
}

5. Run the Sample Program

You will see the program output as follows:

locale: zh_CN
        region: China
        language: Simplified Chinese
locale: zh_HK
        region: Hong Kong
        language: Traditional Chinese
locale: zh_TW
        region: Taiwan
        language: Traditional Chinese
locale: en_CA
        region: global
        language: English

Note that the newly created was assigned the Hong Kong region, because it was specified in an appropriate properties file. Traditional Chinese was assigned as the language for the Taiwan locale.

Two other interesting methods of the ResourceBundle.Control class were not used in the RBControl example, but they deserved to be mentioned. The getTimeToLive method is used to determine how long the resource bundle can exist in the cache. If the time limit for a resource bundle in the cache has expired, the needsReload method is invoked to determine whether the resource bundle needs to be reloaded.