getBundle. Now you can get your object by calling
* getObject or getString on that bundle.
*
* When a bundle is demanded for a specific locale, the ResourceBundle
* is searched in following order (def. language stands for the
* two letter ISO language code of the default locale (see
* Locale.getDefault()).
*
baseName_language code_country code_variant
baseName_language code_country code
baseName_language code
baseName_def. language_def. country_def. variant
baseName_def. language_def. country
baseName_def. language
baseName
*
*
A bundle is backed up by less specific bundles (omitting variant, country * or language). But it is not backed up by the default language locale. * *
If you provide a bundle for a given locale, say
* Bundle_en_UK_POSIX, you must also provide a bundle for
* all sub locales, ie. Bundle_en_UK, Bundle_en, and
* Bundle.
*
*
When a bundle is searched, we look first for a class with the given
* name, then for a file with .properties extension in the
* classpath. The name must be a fully qualified classname (with dots as
* path separators).
*
*
(Note: This implementation always backs up the class with a properties
* file if that is existing, but you shouldn't rely on this, if you want to
* be compatible to the standard JDK.)
*
* @author Jochen Hoenicke
* @author Eric Blake (ebb9@email.byu.edu)
* @see Locale
* @see ListResourceBundle
* @see PropertyResourceBundle
* @since 1.1
* @status updated to 1.4
*/
public abstract class ResourceBundle
{
/**
* The parent bundle. This is consulted when you call getObject and there
* is no such resource in the current bundle. This field may be null.
*/
protected ResourceBundle parent;
/**
* The locale of this resource bundle. You can read this with
* getLocale and it is automatically set in
* getBundle.
*/
private Locale locale;
/**
* We override SecurityManager in order to access getClassContext().
*/
private static final class Security extends SecurityManager
{
/**
* Avoid accessor method of private constructor.
*/
Security()
{
}
/**
* Return the ClassLoader of the class which called into this
* ResourceBundle, or null if it cannot be determined.
*/
ClassLoader getCallingClassLoader()
{
Class[] stack = getClassContext();
for (int i = 0; i < stack.length; i++)
if (stack[i] != Security.class && stack[i] != ResourceBundle.class)
return stack[i].getClassLoader();
return null;
}
}
/** A security context for grabbing the correct class loader. */
private static final Security security
= (Security) AccessController.doPrivileged(new PrivilegedAction()
{
// This will always work since java.util classes have (all) system
// permissions.
public Object run()
{
return new Security();
}
}
);
/**
* The resource bundle cache. This is a two-level hash map: The key
* is the class loader, the value is a new HashMap. The key of this
* second hash map is the localized name, the value is a soft
* references to the resource bundle.
*/
private static final Map resourceBundleCache = new HashMap();
/**
* The `empty' locale is created once in order to optimize
* tryBundle().
*/
private static final Locale emptyLocale = new Locale("");
/**
* The constructor. It does nothing special.
*/
public ResourceBundle()
{
}
/**
* Get a String from this resource bundle. Since most localized Objects
* are Strings, this method provides a convenient way to get them without
* casting.
*
* @param key the name of the resource
* @throws MissingResourceException if the resource can't be found
* @throws NullPointerException if key is null
* @throws ClassCastException if resource is not a string
*/
public final String getString(String key)
{
return (String) getObject(key);
}
/**
* Get an array of Strings from this resource bundle. This method
* provides a convenient way to get it without casting.
*
* @param key the name of the resource
* @throws MissingResourceException if the resource can't be found
* @throws NullPointerException if key is null
* @throws ClassCastException if resource is not a string
*/
public final String[] getStringArray(String key)
{
return (String[]) getObject(key);
}
/**
* Get an object from this resource bundle. This will call
* handleGetObject for this resource and all of its parents,
* until it finds a non-null resource.
*
* @param key the name of the resource
* @throws MissingResourceException if the resource can't be found
* @throws NullPointerException if key is null
*/
public final Object getObject(String key)
{
for (ResourceBundle bundle = this; bundle != null; bundle = bundle.parent)
try
{
Object o = bundle.handleGetObject(key);
if (o != null)
return o;
}
catch (MissingResourceException ex)
{
}
throw new MissingResourceException("Key not found",
getClass().getName(), key);
}
/**
* Return the actual locale of this bundle. You can use it after calling
* getBundle, to know if the bundle for the desired locale was loaded or
* if the fall back was used.
*
* @return the bundle's locale
*/
public Locale getLocale()
{
return locale;
}
/**
* Set the parent of this bundle. The parent is consulted when you call
* getObject and there is no such resource in the current bundle.
*
* @param parent the parent of this bundle
*/
protected void setParent(ResourceBundle parent)
{
this.parent = parent;
}
/**
* Get the appropriate ResourceBundle for the default locale. This is like
* calling getBundle(baseName, Locale.getDefault(),
* getClass().getClassLoader(), except that any security check of
* getClassLoader won't fail.
*
* @param baseName the name of the ResourceBundle
* @return the desired resource bundle
* @throws MissingResourceException if the resource bundle can't be found
* @throws NullPointerException if baseName is null
*/
public static final ResourceBundle getBundle(String baseName)
{
return getBundle(baseName, Locale.getDefault(),
security.getCallingClassLoader());
}
/**
* Get the appropriate ResourceBundle for the given locale. This is like
* calling getBundle(baseName, locale,
* getClass().getClassLoader(), except that any security check of
* getClassLoader won't fail.
*
* @param baseName the name of the ResourceBundle
* @param locale A locale
* @return the desired resource bundle
* @throws MissingResourceException if the resource bundle can't be found
* @throws NullPointerException if baseName or locale is null
*/
public static final ResourceBundle getBundle(String baseName,
Locale locale)
{
return getBundle(baseName, locale, security.getCallingClassLoader());
}
/**
* Get the appropriate ResourceBundle for the given locale. The following
* strategy is used:
*
*
A sequence of candidate bundle names are generated, and tested in * this order, where the suffix 1 means the string from the specified * locale, and the suffix 2 means the string from the default locale:
In the sequence, entries with an empty string are ignored. Next,
* getBundle tries to instantiate the resource bundle:
Next, the parent chain is implemented. The remaining candidate names
* in the above sequence are tested in a similar manner, and if any results
* in a resource bundle, it is assigned as the parent of the first bundle
* using the setParent method (unless the first bundle already
* has a parent).
*
*
For example, suppose the following class and property files are * provided: MyResources.class, MyResources_fr_CH.properties, * MyResources_fr_CH.class, MyResources_fr.properties, * MyResources_en.properties, and MyResources_es_ES.class. The contents of * all files are valid (that is, public non-abstract subclasses of * ResourceBundle with public nullary constructors for the ".class" files, * syntactically correct ".properties" files). The default locale is * Locale("en", "UK"). * *
Calling getBundle with the shown locale argument values instantiates * resource bundles from the following sources:
getObject. If you don't have a resource
* for the given key, you should return null instead throwing a
* MissingResourceException. You don't have to ask the parent, getObject()
* already does this; nor should you throw a MissingResourceException.
*
* @param key the key of the resource
* @return the resource for the key, or null if not in bundle
* @throws NullPointerException if key is null
*/
protected abstract Object handleGetObject(String key);
/**
* This method should return all keys for which a resource exists; you
* should include the enumeration of any parent's keys, after filtering out
* duplicates.
*
* @return an enumeration of the keys
*/
public abstract Enumeration getKeys();
/**
* Tries to load a class or a property file with the specified name.
*
* @param localizedName the name
* @param locale the locale, that must be used exactly
* @param classloader the classloader
* @param bundle the backup (parent) bundle
* @return the resource bundle if it was loaded, otherwise the backup
*/
private static final ResourceBundle tryBundle(String localizedName,
Locale locale,
ClassLoader classloader,
ResourceBundle bundle,
HashMap cache)
{
// First look into the cache.
if (cache.containsKey(localizedName))
{
Reference ref = (Reference) cache.get(localizedName);
ResourceBundle result = null;
// If REF is null, that means that we added a `null' value to
// the hash map. That means we failed to find the bundle
// previously, and we cached that fact. The JDK does this, so
// it must be ok.
if (ref == null)
return null;
else
{
ResourceBundle rb = (ResourceBundle) ref.get();
if (rb != null)
{
// RB should already have the right parent, except if
// something very strange happened.
return rb;
}
// If RB is null, then we previously found it but it was
// collected. So we try again.
}
}
// foundBundle holds exact matches for the localizedName resource
// bundle, which may later be cached.
ResourceBundle foundBundle = null;
try
{
Class rbClass;
if (classloader == null)
rbClass = Class.forName(localizedName);
else
rbClass = classloader.loadClass(localizedName);
foundBundle = (ResourceBundle) rbClass.newInstance();
foundBundle.parent = bundle;
foundBundle.locale = locale;
}
catch (Exception ex)
{
// ignore them all
}
if (foundBundle == null)
{
try
{
InputStream is;
final String resourceName
= localizedName.replace('.', '/') + ".properties";
if (classloader == null)
is = ClassLoader.getSystemResourceAsStream(resourceName);
else
is = classloader.getResourceAsStream(resourceName);
if (is != null)
{
foundBundle = new PropertyResourceBundle(is);
foundBundle.parent = bundle;
foundBundle.locale = locale;
}
}
catch (IOException ex)
{
}
}
// Put the result into the hash table. If we didn't find anything
// here, we record our parent bundle. If we record `null' that means
// nothing, not even the base, was found.
if (foundBundle == null)
foundBundle = bundle;
if (foundBundle == null)
cache.put(localizedName, null);
else
cache.put(localizedName, new SoftReference(foundBundle));
return foundBundle;
}
/**
* Tries to load a the bundle for a given locale, also loads the backup
* locales with the same language.
*
* @param name the name
* @param locale the locale
* @param classloader the classloader
* @param bundle the backup (parent) bundle
* @return the resource bundle if it was loaded, otherwise the backup
*/
private static final ResourceBundle tryLocalBundle(String baseName,
Locale locale,
ClassLoader classloader,
ResourceBundle bundle,
HashMap cache)
{
final String language = locale.getLanguage();
final String country = locale.getCountry();
final String variant = locale.getVariant();
StringBuffer sb = new StringBuffer(60);
sb.append(baseName);
sb.append('_');
if (language.length() > 0)
{
sb.append(language);
bundle = tryBundle(sb.toString(), new Locale(language),
classloader, bundle, cache);
}
// If LANGUAGE was empty, we still need to try the other
// components, and the `_' is required.
sb.append('_');
if (country.length() > 0)
{
sb.append(country);
bundle = tryBundle(sb.toString(), new Locale(language, country),
classloader, bundle, cache);
}
sb.append('_');
if (variant.length() > 0)
{
sb.append(variant);
bundle = tryBundle(sb.toString(), locale,
classloader, bundle, cache);
}
return bundle;
}
}