|
FlexDoc/Javadoc 2.0 Demo Java Doc |
ResourceBundle.Control is designed for an application deployed in an unnamed module, for example to support resource bundles in non-standard formats or package localized resources in a non-traditional convention. ResourceBundleProvider is the replacement for ResourceBundle.Control when migrating to modules. UnsupportedOperationException will be thrown when a factory method that takes the ResourceBundle.Control parameter is called.
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() { ... } }
Field Summary |
||
The class-only format List containing
"java.class".
|
||
The default format List, which contains the strings
"java.class" and "java.properties", in
this order.
|
||
The properties-only format List containing
"java.properties".
|
||
static final long |
The time-to-live constant for not caching loaded resource bundle
instances.
|
|
static final long |
The time-to-live constant for disabling the expiration control
for loaded resource bundle instances in the cache.
|
Constructor Summary |
||
protected |
Control()
Sole constructor.
|
Method Summary |
||
Returns a List of Locales as candidate
locales for baseName and locale.
|
||
static final ResourceBundle.Control |
||
Returns a Locale to be used as a fallback locale for
further resource bundle searches by the
ResourceBundle.getBundle factory method.
|
||
getFormats(String baseName)
Returns a List of Strings containing
formats to be used to load resource bundles for the given
baseName.
|
||
static final ResourceBundle.Control |
Returns a ResourceBundle.Control in which the getFormats method returns the specified
formats and the getFallbackLocale
method returns null.
|
|
long |
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.
|
|
Instantiates a resource bundle for the given bundle name of the
given format and locale, using the given class loader if
necessary.
|
||
Converts the given baseName and locale
to the bundle name.
|
||
final String |
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.
|
Methods inherited from class java.lang.Object |
protected Control |
() |
public static final ResourceBundle.Control getControl |
Specifying FORMAT_DEFAULT is equivalent to instantiating the ResourceBundle.Control class, except that this method returns a singleton.
public static final ResourceBundle.Control getNoFallbackControl |
(String baseName) |
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.
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("zh", "CN")
, the candidate list will be:
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:
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.ROOTis 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
public Locale getFallbackLocale |
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.
public ResourceBundle newBundle |
|
throws |
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.
public long getTimeToLive |
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.
public boolean needsReload |
(String baseName, Locale locale, String format, ClassLoader loader, ResourceBundle bundle, long loadTime) |
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".
public String toBundleName |
This implementation returns the following value:
baseName + "_" + language + "_" + script + "_" + country + "_" + variantwhere 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.
public final String toResourceName |
|
FlexDoc/Javadoc 2.0 Demo Java Doc |