String for example, your program can load it
from the resource bundle that is appropriate for the
current user's locale. In this way, you can write
program code that is largely independent of the user's
locale isolating most, if not all, of the locale-specific
information in resource bundles.
This allows you to write programs that can:
Resource bundles belong to families whose members share a common base name, but whose names also have additional components that identify their locales. For example, the base name of a family of resource bundles might be "MyResources". The family should have a default resource bundle which simply has the same name as its family - "MyResources" - and will be used as the bundle of last resort if a specific locale is not supported. The family can then provide as many locale-specific members as needed, for example a German one named "MyResources_de".
Each resource bundle in a family contains the same items, but the items have
been translated for the locale represented by that resource bundle.
For example, both "MyResources" and "MyResources_de" may have a
String that's used on a button for canceling operations.
In "MyResources" the String may contain "Cancel" and in
"MyResources_de" it may contain "Abbrechen".
If there are different resources for different countries, you can make specializations: for example, "MyResources_de_CH" contains objects for the German language (de) in Switzerland (CH). If you want to only modify some of the resources in the specialization, you can do so.
When your program needs a locale-specific object, it loads
the ResourceBundle class using the
getBundle
method:
ResourceBundle myResources =
ResourceBundle.getBundle("MyResources", currentLocale);
Resource bundles contain key/value pairs. The keys uniquely
identify a locale-specific object in the bundle. Here's an
example of a ListResourceBundle that contains
two key/value pairs:
public class MyResources extends ListResourceBundle {
protected Object[][] getContents() {
return new Object[][] {
// LOCALIZE THE SECOND STRING OF EACH ARRAY (e.g., "OK")
{"OkKey", "OK"},
{"CancelKey", "Cancel"},
// END OF MATERIAL TO LOCALIZE
};
}
}
Keys are always Strings.
In this example, the keys are "OkKey" and "CancelKey".
In the above example, the values
are also Strings--"OK" and "Cancel"--but
they don't have to be. The values can be any type of object.
You retrieve an object from resource bundle using the appropriate
getter method. Because "OkKey" and "CancelKey"
are both strings, you would use getString to retrieve them:
button1 = new Button(myResources.getString("OkKey"));
button2 = new Button(myResources.getString("CancelKey"));
The getter methods all require the key as an argument and return
the object if found. If the object is not found, the getter method
throws a MissingResourceException.
Besides getString, ResourceBundle also provides
a method for getting string arrays, getStringArray,
as well as a generic getObject method for any other
type of object. When using getObject, you'll
have to cast the result to the appropriate type. For example:
int[] myIntegers = (int[]) myResources.getObject("intList");
The Java Platform provides two subclasses of ResourceBundle,
ListResourceBundle and PropertyResourceBundle,
that provide a fairly simple way to create resources.
As you saw briefly in a previous example, ListResourceBundle
manages its resource as a list of key/value pairs.
PropertyResourceBundle uses a properties file to manage
its resources.
If ListResourceBundle or PropertyResourceBundle
do not suit your needs, you can write your own ResourceBundle
subclass. Your subclasses must override two methods: handleGetObject
and getKeys().
ResourceBundle.ControlgetBundle
factory methods that take a ResourceBundle.Control
instance. You can implement your own subclass in order to enable
non-standard resource bundle formats, change the search strategy, or
define caching parameters. Refer to the descriptions of the class and the
getBundle
factory method for details.
getBundle factory
methods are cached by default, and the factory methods return the same
resource bundle instance multiple times if it has been
cached. getBundle clients may clear the cache, manage the
lifetime of cached resource bundle instances using time-to-live values,
or specify not to cache resource bundle instances. Refer to the
descriptions of the getBundle factory method, clearCache(java.lang.ClassLoader)ResourceBundle.Control.getTimeToLive(java.lang.String,java.util.Locale)ResourceBundle.Control.needsReload(java.lang.String,java.util.Locale,java.lang.String,java.lang.ClassLoader,java.util.ResourceBundle,long)ResourceBundle
subclass, MyResources, that manages two resources (for a larger number of
resources you would probably use a Map).
Notice that you don't need to supply a value if
a "parent-level" ResourceBundle handles the same
key with the same value (as for the okKey below).
// default (English language, United States)
public class MyResources extends ResourceBundle {
public Object handleGetObject(String key) {
if (key.equals("okKey")) return "Ok";
if (key.equals("cancelKey")) return "Cancel";
return null;
}
public Enumeration<String> getKeys() {
return Collections.enumeration(keySet());
}
// Overrides handleKeySet() so that the getKeys() implementation
// can rely on the keySet() value.
protected Set<String> handleKeySet() {
return new HashSet<String>(Arrays.asList("okKey", "cancelKey"));
}
}
// German language
public class MyResources_de extends MyResources {
public Object handleGetObject(String key) {
// don't need okKey, since parent level handles it.
if (key.equals("cancelKey")) return "Abbrechen";
return null;
}
protected Set<String> handleKeySet() {
return new HashSet<String>(Arrays.asList("cancelKey"));
}
}
You do not have to restrict yourself to using a single family of
ResourceBundles. For example, you could have a set of bundles for
exception messages, ExceptionResources
(ExceptionResources_fr, ExceptionResources_de, ...),
and one for widgets, WidgetResource (WidgetResources_fr,
WidgetResources_de, ...); breaking up the resources however you like.
ListResourceBundlePropertyResourceBundleMissingResourceException
(String) getObject(key).
key the key for the desired stringjava.lang.NullPointerException if key is nullMissingResourceException if no object for the given key can be foundjava.lang.ClassCastException if the object found for the given key is not a string
(String[]) getObject(key).
key the key for the desired string arrayjava.lang.NullPointerException if key is nullMissingResourceException if no object for the given key can be foundjava.lang.ClassCastException if the object found for the given key is not a string arrayhandleGetObject.
If not successful, and the parent resource bundle is not null,
it calls the parent's getObject method.
If still not successful, it throws a MissingResourceException.
key the key for the desired objectjava.lang.NullPointerException if key is nullMissingResourceException if no object for the given key can be found
getBundle(baseName, Locale.getDefault(), this.getClass().getClassLoader()),
except that getClassLoader() is run with the security
privileges of ResourceBundle.
See getBundle
for a complete description of the search and instantiation strategy.
baseName the base name of the resource bundle, a fully qualified class namejava.lang.NullPointerException
if baseName is nullMissingResourceException
if no resource bundle for the specified base name can be found
getBundle(baseName, Locale.getDefault(),
this.getClass().getClassLoader(), control),
except that getClassLoader() is run with the security
privileges of ResourceBundle. See getBundle(java.lang.String,java.util.Locale,java.lang.ClassLoader,java.util.ResourceBundle.Control)ResourceBundle.Control.
baseName
the base name of the resource bundle, a fully qualified class
namecontrol
the control which gives information for the resource bundle
loading processjava.lang.NullPointerException
if baseName or control is
nullMissingResourceException
if no resource bundle for the specified base name can be foundjava.lang.IllegalArgumentException
if the given control doesn't perform properly
(e.g., control.getCandidateLocales returns null.)
Note that validation of control is performed as
needed.
getBundle(baseName, locale, this.getClass().getClassLoader()),
except that getClassLoader() is run with the security
privileges of ResourceBundle.
See getBundle
for a complete description of the search and instantiation strategy.
baseName
the base name of the resource bundle, a fully qualified class namelocale
the locale for which a resource bundle is desiredjava.lang.NullPointerException
if baseName or locale is nullMissingResourceException
if no resource bundle for the specified base name can be found
getBundle(baseName, targetLocale, this.getClass().getClassLoader(),
control),
except that getClassLoader() is run with the security
privileges of ResourceBundle. See getBundle(java.lang.String,java.util.Locale,java.lang.ClassLoader,java.util.ResourceBundle.Control)ResourceBundle.Control.
baseName
the base name of the resource bundle, a fully qualified
class nametargetLocale
the locale for which a resource bundle is desiredcontrol
the control which gives information for the resource
bundle loading processLocale in localesjava.lang.NullPointerException
if baseName, locales or
control is nullMissingResourceException
if no resource bundle for the specified base name in any
of the locales can be found.java.lang.IllegalArgumentException
if the given control doesn't perform properly
(e.g., control.getCandidateLocales returns null.)
Note that validation of control is performed as
needed.
Conceptually,
Candidate bundle names where the final component is an empty string are omitted.
For example, if country1 is an empty string, the second candidate bundle name is omitted.
If no result resource bundle has been found, a
Once a result resource bundle has been found, its parent chain is instantiated.
The
Example:
Calling The file MyResources_fr_CH.properties is never used because it is hidden by
MyResources_fr_CH.class. Likewise, MyResources.properties is also hidden by
MyResources.class.
getBundle uses the following strategy for locating and instantiating
resource bundles:
getBundle uses the base name, the specified locale, and the default
locale (obtained from Locale.getDefault)
to generate a sequence of candidate bundle names.
If the specified locale's language, country, and variant are all empty
strings, then the base name is the only candidate bundle name.
Otherwise, the following sequence is generated from the attribute
values of the specified locale (language1, country1, and variant1)
and of the default locale (language2, country2, and variant2):
getBundle then iterates over the candidate bundle names to find the first
one for which it can instantiate an actual resource bundle. For each candidate
bundle name, it attempts to create a resource bundle:
getBundle creates a new instance of this class and uses it as the result
resource bundle.
getBundle attempts to locate a property resource file.
It generates a path name from the candidate bundle name by replacing all "." characters
with "/" and appending the string ".properties".
It attempts to find a "resource" with this name using
ClassLoader.getResource.
(Note that a "resource" in the sense of getResource has nothing to do with
the contents of a resource bundle, it is just a container of data, such as a file.)
If it finds a "resource", it attempts to create a new
PropertyResourceBundleMissingResourceException
is thrown.
getBundle iterates over the candidate bundle names that can be
obtained by successively removing variant, country, and language
(each time with the preceding "_") from the bundle name of the result resource bundle.
As above, candidate bundle names where the final component is an empty string are omitted.
With each of the candidate bundle names it attempts to instantiate a resource bundle, as
described above.
Whenever it succeeds, it calls the previously instantiated resource
bundle's setParent method
with the new resource bundle, unless the previously instantiated resource
bundle already has a non-null parent.
getBundle caches instantiated resource bundles and
may return the same resource bundle instance multiple
times.
baseName argument should be a fully qualified class name. However, for
compatibility with earlier versions, Sun's Java SE Runtime Environments do not verify this,
and so it is possible to access PropertyResourceBundles by specifying a
path name (using "/") instead of a fully qualified class name (using ".").
The following class and property files are provided:
MyResources.class
MyResources.properties
MyResources_fr.properties
MyResources_fr_CH.class
MyResources_fr_CH.properties
MyResources_en.properties
MyResources_es_ES.class
The contents of all files are valid (that is, public non-abstract subclasses of ResourceBundle for
the ".class" files, syntactically correct ".properties" files).
The default locale is Locale("en", "GB").
getBundle with the shown locale argument values instantiates
resource bundles from the following sources:
baseName the base name of the resource bundle, a fully qualified class namelocale the locale for which a resource bundle is desiredloader the class loader from which to load the resource bundlejava.lang.NullPointerException
if baseName, locale, or loader is nullMissingResourceException
if no resource bundle for the specified base name can be found
getBundle(java.lang.String,java.util.Locale,java.lang.ClassLoader), the given
control specifies how to locate and instantiate resource
bundles. Conceptually, the bundle loading process with the given
control is performed in the following steps.
baseName, targetLocale and
loader. If the requested resource bundle instance is
found in the cache and the time-to-live periods of the instance and
all of its parent instances have not expired, the instance is returned
to the caller. Otherwise, this factory method proceeds with the
loading process below. control.getFormats method is called to get resource bundle formats
to produce bundle or resource names. The strings
"java.class" and "java.properties"
designate class-based and property-based resource bundles, respectively. Other strings
starting with "java." are reserved for future extensions
and must not be used for application-defined formats. Other strings
designate application-defined formats.control.getCandidateLocales method is called with the target
locale to get a list of candidate Locales for
which resource bundles are searched.control.newBundle method is called to
instantiate a ResourceBundle for the base bundle name, a
candidate locale, and a format. (Refer to the note on the cache
lookup below.) This step is iterated over all combinations of the
candidate locales and formats until the newBundle method
returns a ResourceBundle instance or the iteration has
used up all the combinations. For example, if the candidate locales
are Locale("de", "DE"), Locale("de") and
Locale("") and the formats are "java.class"
and "java.properties", then the following is the
sequence of locale-format combinations to be used to call
control.newBundle.
| Locale | format |
| Locale("de", "DE") | java.class |
| Locale("de", "DE") | java.properties |
| Locale("de") | java.class |
| Locale("de") | java.properties |
| Locale("") | java.class |
| Locale("") | java.properties |
Locale("")), and the candidate locale list only contained
Locale(""), return the bundle to the caller. If a bundle
has been found that is a base bundle, but the candidate locale list
contained locales other than Locale(""), put the bundle on hold and
proceed to Step 6. If a bundle has been found that is not a base
bundle, proceed to Step 7.control.getFallbackLocale method is called to get a fallback
locale (alternative to the current target locale) to try further
finding a resource bundle. If the method returns a non-null locale,
it becomes the next target locale and the loading process starts over
from Step 3. Otherwise, if a base bundle was found and put on hold in
a previous Step 5, it is returned to the caller now. Otherwise, a
MissingResourceException is thrown.During the resource bundle loading process above, this factory
method looks up the cache before calling the ResourceBundle.Control.newBundle(java.lang.String,java.util.Locale,java.lang.String,java.lang.ClassLoader,boolean)control.needsReload
method to determine whether the resource bundle needs to be reloaded.
If reloading is required, the factory method calls
control.newBundle to reload the resource bundle. If
control.newBundle returns null, the factory
method puts a dummy resource bundle in the cache as a mark of
nonexistent resource bundles in order to avoid lookup overhead for
subsequent requests. Such dummy resource bundles are under the same
expiration control as specified by control.
All resource bundles loaded are cached by default. Refer to
control.getTimeToLive for details.
The following is an example of the bundle loading process with the
default ResourceBundle.Control implementation.
Conditions:
foo.bar.Messages
Locale: Locale.ITALYLocale: Locale.FRENCHfoo/bar/Messages_fr.properties and
foo/bar/Messages.propertiesFirst, getBundle tries loading a resource bundle in
the following sequence.
foo.bar.Messages_it_IT
foo/bar/Messages_it_IT.properties
foo.bar.Messages_itfoo/bar/Messages_it.propertiesfoo.bar.Messagesfoo/bar/Messages.propertiesAt this point, getBundle finds
foo/bar/Messages.properties, which is put on hold
because it's the base bundle. getBundle calls ResourceBundle.Control.getFallbackLocale(java.lang.String,java.util.Locale)Locale.FRENCH. Next, getBundle
tries loading a bundle in the following sequence.
foo.bar.Messages_frfoo/bar/Messages_fr.propertiesfoo.bar.Messagesfoo/bar/Messages.propertiesgetBundle finds
foo/bar/Messages_fr.properties and creates a
ResourceBundle instance. Then, getBundle
sets up its parent chain from the list of the candiate locales. Only
foo/bar/Messages.properties is found in the list and
getBundle creates a ResourceBundle instance
that becomes the parent of the instance for
foo/bar/Messages_fr.properties.
baseName
the base name of the resource bundle, a fully qualified
class nametargetLocale
the locale for which a resource bundle is desiredloader
the class loader from which to load the resource bundlecontrol
the control which gives information for the resource
bundle loading processjava.lang.NullPointerException
if baseName, targetLocale,
loader, or control is
nullMissingResourceException
if no resource bundle for the specified base name can be foundjava.lang.IllegalArgumentException
if the given control doesn't perform properly
(e.g., control.getCandidateLocales returns null.)
Note that validation of control is performed as
needed.cacheKey the key to look up the cachecontrol the Control to be used for the expiration controlbundle.expire is true
upon return if the bundle in the cache has expired.ResourceBundle.Control.getTimeToLive(java.lang.String,java.util.Locale)loader the class loaderjava.lang.NullPointerException if loader is nullResourceBundle.Control.getTimeToLive(java.lang.String,java.util.Locale)key the key for the desired objectjava.lang.NullPointerException if key is nullkey is contained in
this ResourceBundle or its parent bundles.
key
the resource keytrue if the given key is
contained in this ResourceBundle or its
parent bundles; false otherwise.java.lang.NullPointerException
if key is nullSet of the keys contained only
in this ResourceBundle.
The default implementation returns a Set of the
keys returned by the getKeys method except
for the ones for which the handleGetObject method returns null. Once the
Set has been created, the value is kept in this
ResourceBundle in order to avoid producing the
same Set in the next calls. Override this method
in subclass implementations for faster handling.
Set of the keys contained only in this
ResourceBundleResourceBundle.Control defines a set of callback methods
that are invoked by the 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(java.lang.String,java.util.Locale)toResourceName(java.lang.String,java.lang.String)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(java.util.List)getNoFallbackControl(java.util.List)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(java.lang.String,java.util.Locale)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() {
...
}
}
List, which contains the strings
"java.class" and "java.properties", in
this order. This List is Collections.unmodifiableList(java.util.List).
getFormats(java.lang.String)List containing
"java.class". This List is Collections.unmodifiableList(java.util.List).
getFormats(java.lang.String)List containing
"java.properties". This List is
unmodifiable.
getFormats(java.lang.String)ResourceBundle.Control in which the getFormats(java.lang.String)formats. The formats must be equal to
one of FORMAT_PROPERTIESFORMAT_CLASSFORMAT_DEFAULTResourceBundle.Control
instances returned by this method are singletons and thread-safe.
Specifying FORMAT_DEFAULTResourceBundle.Control class,
except that this method returns a singleton.
formats
the formats to be returned by the
ResourceBundle.Control.getFormats methodResourceBundle.Control supporting the
specified formatsjava.lang.NullPointerException
if formats is nulljava.lang.IllegalArgumentException
if formats is unknownResourceBundle.Control in which the getFormats(java.lang.String)formats and the getFallbackLocale(java.lang.String,java.util.Locale)null. The formats must
be equal to one of FORMAT_PROPERTIESFORMAT_CLASSFORMAT_DEFAULTResourceBundle.Control instances returned by this
method are singletons and thread-safe.
formats
the formats to be returned by the
ResourceBundle.Control.getFormats methodResourceBundle.Control supporting the
specified formats with no fallback
Locale supportjava.lang.NullPointerException
if formats is nulljava.lang.IllegalArgumentException
if formats is unknownList of Strings containing
formats to be used to load resource bundles for the given
baseName. The ResourceBundle.getBundle
factory method tries to load resource bundles with formats in the
order specified by the list. The list returned by this method
must have at least one String. The predefined
formats are "java.class" for class-based resource
bundles and "java.properties" for PropertyResourceBundle ones. Strings starting
with "java." are reserved for future extensions and
must not be used by application-defined formats.
It is not a requirement to return an immutable (unmodifiable)
List. However, the returned List must
not be mutated after it has been returned by
getFormats.
The default implementation returns FORMAT_DEFAULTResourceBundle.getBundle factory method
looks up first class-based resource bundles, then
properties-based ones.
baseName
the base name of the resource bundle, a fully qualified class
nameList of Strings containing
formats for loading resource bundles.java.lang.NullPointerException
if baseName is nullFORMAT_DEFAULTFORMAT_CLASSFORMAT_PROPERTIESList of Locales as candidate
locales for baseName and locale. This
method is called by the ResourceBundle.getBundle
factory method each time the factory method tries finding a
resource bundle for a target Locale.
The sequence of the candidate locales also corresponds to the runtime resource lookup path (also known as the parent chain), if the corresponding resource bundles for the candidate locales exist and their parents are not defined by loaded resource bundles themselves. The last element of the list must be a root locale if it is desired to have the base bundle as the terminal of the parent chain.
If the given locale is equal to Locale.ROOT (the
root locale), a List containing only the root
Locale must be returned. In this case, the
ResourceBundle.getBundle factory method loads only
the base bundle as the resulting resource bundle.
It is not a requirement to return an immutable
(unmodifiable) List. However, the returned
List must not be mutated after it has been
returned by getCandidateLocales.
The default implementation returns a List containing
Locales in the following sequence:
Locale(language, country, variant)
Locale(language, country)
Locale(language)
Locale.ROOT
where language, country and
variant are the language, country and variant values
of the given locale, respectively. Locales where the
final component values are empty strings are omitted.
The default implementation uses an ArrayListgetCandidateLocales.
For example, if the given baseName is "Messages"
and the given locale is
Locale("ja", "", "XX"), then a
List of Locales:
Locale("ja", "", "XX")
Locale("ja")
Locale.ROOT
is returned. And if the resource bundles for the "ja" and
"" Locales are found, then the runtime resource
lookup path (parent chain) is:
Messages_ja -> Messages
baseName
the base name of the resource bundle, a fully
qualified class namelocale
the locale for which a resource bundle is desiredList of candidate
Locales for the given localejava.lang.NullPointerException
if baseName or locale is
nullLocale to be used as a fallback locale for
further resource bundle searches by the
ResourceBundle.getBundle factory method. This method
is called from the factory method every time when no resulting
resource bundle has been found for baseName and
locale, where locale is either the parameter for
ResourceBundle.getBundle or the previous fallback
locale returned by this method.
The method returns null if no further fallback
search is desired.
The default implementation returns the Locale.getDefault() if the given
locale isn't the default one. Otherwise,
null is returned.
baseName
the base name of the resource bundle, a fully
qualified class name for which
ResourceBundle.getBundle has been
unable to find any resource bundles (except for the
base bundle)locale
the Locale for which
ResourceBundle.getBundle has been
unable to find any resource bundles (except for the
base bundle)Locale for the fallback search,
or null if no further fallback search
is desired.java.lang.NullPointerException
if baseName or locale
is nullnull 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.
toBundleName(java.lang.String,java.util.Locale)format is "java.class", the
java.lang.Classjava.lang.ClassLoader.loadClass(java.lang.String)ResourceBundle is instantiated by calling java.lang.Class.newInstance()reload flag is
ignored for loading class-based resource bundles in this default
implementation.format is "java.properties",
toResourceName(bundlename,
"properties") is called to get the resource name.
If reload is true, java.lang.ClassLoader.getResource(java.lang.String)java.net.URLjava.net.URLConnectionURLConnection 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 java.io.InputStreamPropertyResourceBundleInputStream.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 namelocale
the locale for which the resource bundle should be
instantiatedformat
the resource bundle format to be loadedloader
the ClassLoader to use to load the bundlereload
the flag to indicate bundle reloading; true
if reloading an expired resource bundle,
false otherwisenull if none could be found.java.lang.NullPointerException
if bundleName, locale,
format, or loader is
null, or if null is returned by
toBundleNamejava.lang.IllegalArgumentException
if format is unknown, or if the resource
found for the given parameters contains malformed data.java.lang.ClassCastException
if the loaded class cannot be cast to ResourceBundlejava.lang.IllegalAccessException
if the class or its nullary constructor is not
accessible.java.lang.InstantiationException
if the instantiation of a class fails for some other
reason.java.lang.ExceptionInInitializerError
if the initialization provoked by this method fails.java.lang.SecurityException
If a security manager is present and creation of new
instances is denied. See java.lang.Class.newInstance()java.io.IOException
if an error occurred when reading resources using
any I/O operationsResourceBundle.Control. Positive time-to-live values
specify the number of milliseconds a bundle can remain in the
cache without being validated against the source data from which
it was constructed. The value 0 indicates that a bundle must be
validated each time it is retrieved from the cache. TTL_DONT_CACHETTL_NO_EXPIRATION_CONTROLThe expiration affects only the bundle loading process by the
ResourceBundle.getBundle factory method. That is,
if the factory method finds a resource bundle in the cache that
has expired, the factory method calls the needsReload(java.lang.String,java.util.Locale,java.lang.String,java.lang.ClassLoader,java.util.ResourceBundle,long)needsReload returns
true, the cached resource bundle instance is removed
from the cache. Otherwise, the instance stays in the cache,
updated with the new TTL value returned by this method.
All cached resource bundles are subject to removal from the cache due to memory constraints of the runtime environment. Returning a large positive value doesn't mean to lock loaded resource bundles in the cache.
The default implementation returns TTL_NO_EXPIRATION_CONTROL
baseName
the base name of the resource bundle for which the
expiration value is specified.locale
the locale of the resource bundle for which the
expiration value is specified.TTL_NO_EXPIRATION_CONTROLTTL_DONT_CACHEjava.lang.NullPointerException
if baseName or locale is
nullbundle in the cache needs
to be reloaded based on the loading time given by
loadTime or some other criteria. The method returns
true if reloading is required; false
otherwise. loadTime is a millisecond offset since
the Calendar
Epoch.
The calling ResourceBundle.getBundle factory method
calls this method on the ResourceBundle.Control
instance used for its current invocation, not on the instance
used in the invocation that originally loaded the resource
bundle.
The default implementation compares loadTime and
the last modified time of the source data of the resource
bundle. If it's determined that the source data has been modified
since loadTime, true is
returned. Otherwise, false is returned. This
implementation assumes that the given format is the
same string as its file suffix if it's not one of the default
formats, "java.class" or
"java.properties".
baseName
the base bundle name of the resource bundle, a
fully qualified class namelocale
the locale for which the resource bundle
should be instantiatedformat
the resource bundle format to be loadedloader
the ClassLoader to use to load the bundlebundle
the resource bundle instance that has been expired
in the cacheloadTime
the time when bundle was loaded and put
in the cachetrue if the expired bundle needs to be
reloaded; false otherwise.java.lang.NullPointerException
if baseName, locale,
format, loader, or
bundle is nullbaseName and locale
to the bundle name. This method is called from the default
implementation of the newBundle and needsReload
methods.
This implementation returns the following value:
baseName + "_" + language + "_" + country + "_" + variant
where language, country and
variant are the language, country and variant values
of locale, respectively. Final component values that
are empty Strings are omitted along with the preceding '_'. If
all of the values are empty strings, then baseName
is returned.
For example, if baseName is
"baseName" and locale is
Locale("ja", "", "XX"), then
"baseName_ja_ _XX" is returned. If the given
locale is Locale("en"), then
"baseName_en" is returned.
Overriding this method allows applications to use different conventions in the organization and packaging of localized resources.
baseName
the base name of the resource bundle, a fully
qualified class namelocale
the locale for which a resource bundle should be
loadedjava.lang.NullPointerException
if baseName or locale
is nullbundleName to the form required
by the ClassLoader.getResource
method by replacing all occurrences of '.' in
bundleName with '/' and appending a
'.' and the given file suffix. For
example, if bundleName is
"foo.bar.MyResources_ja_JP" and suffix
is "properties", then
"foo/bar/MyResources_ja_JP.properties" is returned.
bundleName
the bundle namesuffix
the file type suffixjava.lang.NullPointerException
if bundleName or suffix
is null