5.5.  Call a resource bundle from an application

[Note]

The first argument to ResourceBundle.getBundle(String s, Locale l) is the bundle name. This argument must be the fully qualified name of the base resource bundle class. Thus, it must include the full package name as well as the classname: myPackage.MyResources.

Loading a resource bundle via ResourceBundle.getBundle(String s, Locale l) is a locale-sensitive operation. Thus, the second argument to getBundle(...) is a Locale. The getBundle(...) uses this locale object to identify which version of the resource bundle to load.

To find the correct, locale-specific, resource bundle, getBundle(...) builds variations of the bundle name until it finds the name of a class that can be loaded.

When you call getBundle(...), you specify the base name of the desired ResourceBundle and a desired Locale (if you do not want to rely on the default locale). Recall that a Locale is specified with a two-letter language code, an optional two-letter country code, and an optional variant string. getBundle(...) looks for an appropriate ResourceBundle class for the locale by appending this locale information to the base name for the bundle. The method looks for an appropriate class with the following order:

  1. bundleName + "_" + localeLanguage + "_" + localeCountry + "_" + localeVariant

  2. bundleName + "_" + localeLanguage + "_" + localeCountry (example: MyResources_be_BY.class)

  3. bundleName + "_" + localeLanguage

  4. bundleName + "_" + defaultLanguage + "_" + defaultCountry + "_" + defaultVariant

  5. bundleName + "_" + defaultLanguage + "_" + defaultCountry (example: MyResources_en_US.class)

  6. bundleName + "_" + defaultLanguage

  7. bundleName (example: MyResources.class)

where localeLanguage, localeCountry and localeVariant are taken from the locale specified in the getBundle(...) call. The defaultLanguage, defaultCountry and defaultVariant are taken from the default locale. As you can see, the resource bundle named bundleName is the bundle of last resort and contains the values to be used if a version of the bundle is not available for a specific locale. If no ResourceBundle subclass can be found, getBundle(...) throws a MissingResourceException.

Typically, a program provides a default bundle for each of its resource bundles. The default bundle contains the full set of key-value pairs in the bundle. Thus, people performing the localization on the bundle have all the information required.

If the bundle in question is a properties bundle, ResourceBundle.getBundle(...) creates a PropertyResourceBundle and initializes it with the information from a properties file. ResourceBundle.getBundle(...) derives the name of the properties file in the same manner as it derives resource bundle class names.

At each step in search process above, getBundle(...) checks first for a class file with the given name. If no class file is found, it uses the getResourceAsStream(...) method of ClassLoader to look for a properties file with the same name as the class and a .properties extension. If such a properties file is found, its contents are used to create a Properties object, and getBundle(...) instantiates and returns a PropertyResourceBundle that exports the properties in the Properties file through the ResourceBundle API.

If getBundle(...) cannot find a class or properties file for the specified locale in any of the search steps, it repeats the search using the default locale instead of the specified locale. If no appropriate ResourceBundle is found in this search either, getBundle(...) throws a MissingResourceException.

The method looks for an appropriate properties file with the following order:

  1. bundleName + "_" + localeLanguage + "_" + localeCountry + "_" + localeVariant

  2. bundleName + "_" + localeLanguage + "_" + localeCountry (example: MyApp_be_BY.properties)

  3. bundleName + "_" + localeLanguage

  4. bundleName + "_" + defaultLanguage + "_" + defaultCountry + "_" + defaultVariant

  5. bundleName + "_" + defaultLanguage + "_" + defaultCountry (example: MyApp_en_US.properties)

  6. bundleName + "_" + defaultLanguage

  7. bundleName (example: MyApp.properties)

The properties file has a .properties extension.

Professional hosting         Free 'Oracle Certified Expert Web Services Developer 6' Guide     Free SCDJWS 5.0 Guide