public static class ResourceBundle.Control extends Object
ResourceBundle.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 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() {
...
}
}
| Modifier and Type | Field and Description |
|---|---|
static List<String> |
FORMAT_CLASS
The class-only format
List containing
"java.class". |
static List<String> |
FORMAT_DEFAULT
The default format
List, which contains the strings
"java.class" and "java.properties", in
this order. |
static List<String> |
FORMAT_PROPERTIES
The properties-only format
List containing
"java.properties". |
static long |
TTL_DONT_CACHE
The time-to-live constant for not caching loaded resource bundle
instances.
|
static long |
TTL_NO_EXPIRATION_CONTROL
The time-to-live constant for disabling the expiration control
for loaded resource bundle instances in the cache.
|
| Modifier | Constructor and Description |
|---|---|
protected |
Control()
Sole constructor.
|
| Modifier and Type | Method and Description |
|---|---|
List<Locale> |
getCandidateLocales(String baseName,
Locale locale)
Returns a
List of Locales as candidate
locales for baseName and locale. |
static ResourceBundle.Control |
getControl(List<String> formats)
|
Locale |
getFallbackLocale(String baseName,
Locale locale)
Returns a
Locale to be used as a fallback locale for
further resource bundle searches by the
ResourceBundle.getBundle factory method. |
List<String> |
getFormats(String baseName)
Returns a
List of Strings containing
formats to be used to load resource bundles for the given
baseName. |
static ResourceBundle.Control |
getNoFallbackControl(List<String> formats)
Returns a
ResourceBundle.Control in which the getFormats method returns the specified
formats and the getFallbackLocale
method returns null. |
long |
getTimeToLive(String baseName,
Locale locale)
Returns the time-to-live (TTL) value for resource bundles that
are loaded under this
ResourceBundle.Control. |
boolean |
needsReload(String baseName,
Locale locale,
String format,
ClassLoader loader,
ResourceBundle bundle,
long loadTime)
Determines if the expired
bundle in the cache needs
to be reloaded based on the loading time given by
loadTime or some other criteria. |
ResourceBundle |
newBundle(String baseName,
Locale locale,
String format,
ClassLoader loader,
boolean reload)
Instantiates a resource bundle for the given bundle name of the
given format and locale, using the given class loader if
necessary.
|
String |
toBundleName(String baseName,
Locale locale)
Converts the given
baseName and locale
to the bundle name. |
String |
toResourceName(String bundleName,
String suffix)
Converts the given
bundleName 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. |
public static final List<String> FORMAT_DEFAULT
List, which contains the strings
"java.class" and "java.properties", in
this order. This List is unmodifiable.getFormats(String)public static final List<String> FORMAT_CLASS
getFormats(String)public static final List<String> FORMAT_PROPERTIES
getFormats(String)public static final long TTL_DONT_CACHE
public static final long TTL_NO_EXPIRATION_CONTROL
protected Control()
public static final ResourceBundle.Control getControl(List<String> formats)
ResourceBundle.Control in which the getFormats method returns the specified
formats. The formats must be equal to
one of FORMAT_PROPERTIES, FORMAT_CLASS or FORMAT_DEFAULT. ResourceBundle.Control
instances returned by this method are singletons and thread-safe.
Specifying FORMAT_DEFAULT is equivalent to
instantiating the ResourceBundle.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 formatsNullPointerException - if formats is nullIllegalArgumentException - if formats is unknownpublic static final ResourceBundle.Control getNoFallbackControl(List<String> formats)
ResourceBundle.Control in which the getFormats method returns the specified
formats and the getFallbackLocale
method returns null. The formats must
be equal to one of FORMAT_PROPERTIES, FORMAT_CLASS or FORMAT_DEFAULT.
ResourceBundle.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 supportNullPointerException - if formats is nullIllegalArgumentException - if formats is unknownpublic List<String> getFormats(String baseName)
List 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 properties-based 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_DEFAULT so
that the ResourceBundle.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.NullPointerException - if baseName is nullFORMAT_DEFAULT,
FORMAT_CLASS,
FORMAT_PROPERTIESpublic List<Locale> getCandidateLocales(String baseName, Locale locale)
List 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 using the rules described below. In the
description below, L, S, C and V
respectively represent non-empty language, script, country, and
variant. For example, [L, C] represents a
Locale that has non-empty values only for language and
country. The form L("xx") represents the (non-empty)
language value is "xx". For all cases, Locales whose
final component values are empty strings are omitted.
Locale with an empty script value,
append candidate Locales by omitting the final component
one by one as below:
Locale.ROOT Locale with a non-empty script value,
append candidate Locales by omitting the final component
up to language, then append candidates generated from the
Locale with country and variant restored:
Locale.ROOTLocale with a variant value consisting
of multiple subtags separated by underscore, generate candidate
Locales by omitting the variant subtags one by one, then
insert them after every occurrence of Locales with the
full variant value in the original list. For example, if the
the variant consists of two subtags V1 and V2:
Locale.ROOTLocale has the
language "zh" (Chinese) and an empty script value, either "Hans" (Simplified) or
"Hant" (Traditional) might be supplied, depending on the country.
When the country is "CN" (China) or "SG" (Singapore), "Hans" is supplied.
When the country is "HK" (Hong Kong SAR China), "MO" (Macau SAR China),
or "TW" (Taiwan), "Hant" is supplied. For all other countries or when the country
is empty, no script is supplied. For example, for Locale("zh", "CN")
, the candidate list will be:
Locale.ROOTLocale("zh", "TW"), the candidate list will be:
Locale.ROOTLocale("no", "NO",
"NY") and Locale("nn", "NO") represent Norwegian
Nynorsk. When a locale's language is "nn", the standard candidate
list is generated up to [L("nn")], and then the following
candidates are added:
Locale.ROOTLocale("no", "NO", "NY"), it is first
converted to Locale("nn", "NO") and then the above procedure is
followed.
Also, Java treats the language "no" as a synonym of Norwegian
Bokmål "nb". Except for the single case Locale("no",
"NO", "NY") (handled above), when an input Locale
has language "no" or "nb", candidate Locales with
language code "no" and "nb" are interleaved, first using the
requested language, then using its synonym. For example,
Locale("nb", "NO", "POSIX") generates the following
candidate list:
Locale.ROOTLocale("no", "NO", "POSIX") would generate the same list
except that locales with "no" would appear before the corresponding
locales with "nb".The default implementation uses an ArrayList that
overriding implementations may modify before returning it to the
caller. However, a subclass must not modify it after it has
been returned by getCandidateLocales.
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 localeNullPointerException - if baseName or locale is
nullpublic Locale getFallbackLocale(String baseName, Locale locale)
Locale 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 default Locale 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.NullPointerException - if baseName or locale
is nullpublic ResourceBundle newBundle(String baseName, Locale locale, String format, ClassLoader loader, boolean reload) throws IllegalAccessException, InstantiationException, IOException
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.
toBundleName(baseName,
locale).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.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.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.NullPointerException - if bundleName, locale,
format, or loader is
null, or if null is returned by
toBundleNameIllegalArgumentException - if format is unknown, or if the resource
found for the given parameters contains malformed data.ClassCastException - if the loaded class cannot be cast to ResourceBundleIllegalAccessException - if the class or its nullary constructor is not
accessible.InstantiationException - if the instantiation of a class fails for some other
reason.ExceptionInInitializerError - if the initialization provoked by this method fails.SecurityException - If a security manager is present and creation of new
instances is denied. See Class.newInstance()
for details.IOException - if an error occurred when reading resources using
any I/O operationspublic long getTimeToLive(String baseName, Locale locale)
ResourceBundle.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_CACHE specifies that loaded resource bundles are not
put in the cache. TTL_NO_EXPIRATION_CONTROL specifies
that loaded resource bundles are put in the cache with no
expiration control.
The 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 method to determine whether the resource
bundle needs to be reloaded. If 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_CONTROL to disable the
expiration control, or TTL_DONT_CACHE to disable
caching.NullPointerException - if baseName or locale is
nullpublic boolean needsReload(String baseName, Locale locale, String format, ClassLoader loader, ResourceBundle bundle, long loadTime)
bundle 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.NullPointerException - if baseName, locale,
format, loader, or
bundle is nullpublic String toBundleName(String baseName, Locale locale)
baseName 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 + "_" + script + "_" + country + "_" + variant
where language, script, country,
and variant are the language, script, country, and variant
values of locale, respectively. Final component values that
are empty Strings are omitted along with the preceding '_'. When the
script is empty, the script value is 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
loadedNullPointerException - if baseName or locale
is nullpublic final String toResourceName(String bundleName, String suffix)
bundleName 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 suffixNullPointerException - if bundleName or suffix
is null Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2025, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.