java.util.ResourceBundle.Control

Contained within: ResourceBundle

ResourceBundle.Control defines a set of callback methods that are invoked by the Locale, ClassLoader, Control) ResourceBundle.getBundle factory methods during the bundle loading process. In other words, a ResourceBundle.Control collaborates with the factory methods for loading resource bundles. The default implementation of the callback methods provides the information necessary for the factory methods to perform the default behavior.

In addition to the callback methods, the toBundleName and toResourceName methods are defined primarily for convenience in implementing the callback methods. However, the toBundleName method could be overridden to provide different conventions in the organization and packaging of localized resources. The toResourceName method is final to avoid use of wrong resource and class name separators.

Two factory methods, #getControl(List) and #getNoFallbackControl(List), provide ResourceBundle.Control instances that implement common variations of the default bundle loading process.

The formats returned by the getFormats method and candidate locales returned by the getCandidateLocales method must be consistent in all ResourceBundle.getBundle invocations for the same base bundle. Otherwise, the ResourceBundle.getBundle methods may return unintended bundles. For example, if only "java.class" is returned by the getFormats method for the first call to ResourceBundle.getBundle and only "java.properties" for the second call, then the second call will return the class-based one that has been cached during the first call.

A ResourceBundle.Control instance must be thread-safe if it's simultaneously used by multiple threads. ResourceBundle.getBundle does not synchronize to call the ResourceBundle.Control methods. The default implementations of the methods are thread-safe.

Applications can specify ResourceBundle.Control instances returned by the getControl factory methods or created from a subclass of ResourceBundle.Control to customize the bundle loading process. The following are examples of changing the default bundle loading process.

Example 1

The following code lets ResourceBundle.getBundle look up only properties-based resources.

 import java.util.*;
 import static java.util.ResourceBundle.Control.*;
 ...
 ResourceBundle bundle =
   ResourceBundle.getBundle("MyResources", new Locale("fr", "CH"),
                            ResourceBundle.Control.getControl(FORMAT_PROPERTIES));

Given the resource bundles in the example in the ResourceBundle.getBundle description, this ResourceBundle.getBundle call loads MyResources_fr_CH.properties whose parent is MyResources_fr.properties whose parent is MyResources.properties. (MyResources_fr_CH.properties is not hidden, but MyResources_fr_CH.class is.)

Example 2

The following is an example of loading XML-based bundles using Properties.loadFromXML.

 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() {
         ...
     }
 }

since

1.6

Instantiates a resource bundle for the given bundle name of the given format and locale, using the given class loader if necessary. This method returns null if there is no resource bundle available for the given parameters. If a resource bundle can't be instantiated due to an unexpected error, the error must be reported by throwing an Error or Exception rather than simply returning null.

If the reload flag is true, it indicates that this method is being called because the previously loaded resource bundle has expired.

The default implementation instantiates a ResourceBundle as follows.

The bundle name is obtained by calling toBundleName(baseName, locale).
If format is "java.class", the Class specified by the bundle name is loaded by calling ClassLoader#loadClass(String). Then, a ResourceBundle is instantiated by calling Class#newInstance(). Note that the reload flag is ignored for loading class-based resource bundles in this default implementation.
If format is "java.properties", toResourceName(bundlename, "properties") is called to get the resource name. If reload is true, load.getResource is called to get a URL for creating a URLConnection. This URLConnection is used to disable the caches of the underlying resource loading layers, and to get an InputStream. Otherwise, loader.getResourceAsStream is called to get an InputStream. Then, a PropertyResourceBundle is constructed with the InputStream.
If format is neither "java.class" nor "java.properties", an IllegalArgumentException is thrown.

baseName	the base bundle name of the resource bundle, a fully qualified class name
locale	the locale for which the resource bundle should be instantiated
format	the resource bundle format to be loaded
loader	the `ClassLoader` to use to load the bundle
reload	the flag to indicate bundle reloading; `true` if reloading an expired resource bundle, `false` otherwise
return	the resource bundle instance, or `null` if none could be found.
Throws	NullPointerException: if `bundleName`, `locale`, `format`, or `loader` is `null`, or if `null` is returned by `toBundleName`
Throws	IllegalArgumentException: if `format` is unknown, or if the resource found for the given parameters contains malformed data.
Throws	ClassCastException: if the loaded class cannot be cast to `ResourceBundle`
Throws	IllegalAccessException: if the class or its nullary constructor is not accessible.
Throws	InstantiationException: if the instantiation of a class fails for some other reason.
Throws	ExceptionInInitializerError: if the initialization provoked by this method fails.
Throws	SecurityException: If a security manager is present and creation of new instances is denied. See `Class#newInstance()` for details.
Throws	IOException: if an error occurred when reading resources using any I/O operations