The specification for java.util.ResourceBundle.getBundle is inadequate,
resulting in differing implementation behavior in various releases of the
JRE/J2RE and numerous bug reports. Here's a summary of the problems:

- The method specifications themselves specify nothing beyond parameter
types and some thrown exceptions. All relevant information is scattered
throughout the class description and even the descriptions of related
classes such as PropertyResourceBundle.

- The documentation doesn't fully specify when and under which conditions
getBundle looks for .properties files. The implemented behavior has
changed between releases, giving rise to several bug reports.

- The specification doesn't explain where and how getBundle looks for
.properties files; and how class loaders and the class path affect the search.

- Parts of the documentation sound like there must be one subclass per
locale; that's not true when .properties files are used.

- The documentation may (and should) be interpreted to say that the base
name passed into getBundle must be a fully qualified class name.
However, it is fuzzy enough that developers have interpreted it to allow
for the path name of a properties file (e.g., "myPackage/MyBundle"). The
implementations did not reject such strings and have, to varying
degrees, been successful at loading properties resource bundles given
such strings.

- The documentation doesn't specify the lookup for requested locales where some of the components (language, country, variant) are empty strings. For example, for Locale("", "", "EURO"), some implementations would look for a bundle with the extension "___EURO", others wouldn't; some would, as a fallback, look for the extension "_", other's wouldn't.

- The documentation does not specify at all how the resource bundle parent
chain is set up, and implementations have varied over time. The
documentation in version 1.2, however, added a note warning that
complete sets of bundles must be provided "or the resource bundle lookup
won't work right". This warning doesn't actually apply to all versions
of the class.

- The documentation is self-contradictory with respect to the
accessibility requirements on resource bundle classes: "[the base class]
must also be accessable by your code; it cannot be a class that is
private to the package where ResourceBundle.getBundle is called.". The
implementation depends on the class being accessible from
java.util.ResourceBundle, that is, public. Developers have complained
about this requirement, but there's no known way for ResourceBundle to
create an instance of a package-private class outside java.util.

- Two of the three getBundle variants declare an unchecked exception using
the throws clause. This is unnecessary and considered poor programming
practice.

- The documentation doesn't mention that results may be cached and the
same resource bundle instances returned repeatedly.

- The class description includes the forward-looking statement "Once
serialization is fully integrated, we will provide another way". Such
statements, even if they did reflect our true intentions, have no place
in a specification.

- The class description includes information about the use of this class
in the implementation of some other classes. Such information has no place
in a specification.