3966N/A * Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved 0N/A * (C) Copyright IBM Corp. 1996 - 1999 - All Rights Reserved 0N/A * The original version of this source code and documentation 0N/A * is copyrighted and owned by Taligent, Inc., a wholly-owned 0N/A * subsidiary of IBM. These materials are provided under terms 0N/A * of a License Agreement between Taligent and Sun. This technology 0N/A * is protected by multiple US and International patents. 0N/A * This notice and attribution to Taligent may not be removed. 0N/A * Taligent is a registered trademark of Taligent, Inc. 2712N/A * Resource bundles contain locale-specific objects. When your program needs a 2712N/A * locale-specific resource, a <code>String</code> for example, your program can 2712N/A * load it from the resource bundle that is appropriate for the current user's 2712N/A * locale. In this way, you can write program code that is largely independent 2712N/A * of the user's locale isolating most, if not all, of the locale-specific 0N/A * information in resource bundles. 0N/A * This allows you to write programs that can: 0N/A * <LI> be easily localized, or translated, into different languages 0N/A * <LI> handle multiple locales at once 0N/A * <LI> be easily modified later to support even more locales 0N/A * Resource bundles belong to families whose members share a common base 0N/A * name, but whose names also have additional components that identify 0N/A * their locales. For example, the base name of a family of resource 0N/A * bundles might be "MyResources". The family should have a default 0N/A * resource bundle which simply has the same name as its family - 0N/A * "MyResources" - and will be used as the bundle of last resort if a 0N/A * specific locale is not supported. The family can then provide as 0N/A * many locale-specific members as needed, for example a German one 0N/A * named "MyResources_de". 0N/A * Each resource bundle in a family contains the same items, but the items have 0N/A * been translated for the locale represented by that resource bundle. 0N/A * For example, both "MyResources" and "MyResources_de" may have a 0N/A * <code>String</code> that's used on a button for canceling operations. 0N/A * In "MyResources" the <code>String</code> may contain "Cancel" and in 0N/A * "MyResources_de" it may contain "Abbrechen". 0N/A * If there are different resources for different countries, you 0N/A * can make specializations: for example, "MyResources_de_CH" contains objects for 0N/A * the German language (de) in Switzerland (CH). If you want to only 0N/A * modify some of the resources 0N/A * in the specialization, you can do so. 0N/A * When your program needs a locale-specific object, it loads 0N/A * the <code>ResourceBundle</code> class using the 0N/A * {@link #getBundle(java.lang.String, java.util.Locale) getBundle} 0N/A * ResourceBundle myResources = 0N/A * ResourceBundle.getBundle("MyResources", currentLocale); 0N/A * Resource bundles contain key/value pairs. The keys uniquely 0N/A * identify a locale-specific object in the bundle. Here's an 0N/A * example of a <code>ListResourceBundle</code> that contains 0N/A * public class MyResources extends ListResourceBundle { 0N/A * protected Object[][] getContents() { 0N/A * return new Object[][] { 0N/A * // LOCALIZE THE SECOND STRING OF EACH ARRAY (e.g., "OK") 0N/A * {"CancelKey", "Cancel"}, 0N/A * // END OF MATERIAL TO LOCALIZE 0N/A * Keys are always <code>String</code>s. 0N/A * In this example, the keys are "OkKey" and "CancelKey". 0N/A * In the above example, the values 0N/A * are also <code>String</code>s--"OK" and "Cancel"--but 0N/A * they don't have to be. The values can be any type of object. 0N/A * You retrieve an object from resource bundle using the appropriate 0N/A * getter method. Because "OkKey" and "CancelKey" 0N/A * are both strings, you would use <code>getString</code> to retrieve them: 0N/A * button1 = new Button(myResources.getString("OkKey")); 0N/A * button2 = new Button(myResources.getString("CancelKey")); 0N/A * The getter methods all require the key as an argument and return 0N/A * the object if found. If the object is not found, the getter method 0N/A * throws a <code>MissingResourceException</code>. 0N/A * Besides <code>getString</code>, <code>ResourceBundle</code> also provides 0N/A * a method for getting string arrays, <code>getStringArray</code>, 0N/A * as well as a generic <code>getObject</code> method for any other 0N/A * type of object. When using <code>getObject</code>, you'll 0N/A * have to cast the result to the appropriate type. For example: 0N/A * int[] myIntegers = (int[]) myResources.getObject("intList"); 0N/A * The Java Platform provides two subclasses of <code>ResourceBundle</code>, 0N/A * <code>ListResourceBundle</code> and <code>PropertyResourceBundle</code>, 0N/A * that provide a fairly simple way to create resources. 0N/A * As you saw briefly in a previous example, <code>ListResourceBundle</code> 0N/A * <code>PropertyResourceBundle</code> uses a properties file to manage 0N/A * If <code>ListResourceBundle</code> or <code>PropertyResourceBundle</code> 0N/A * do not suit your needs, you can write your own <code>ResourceBundle</code> 0N/A * subclass. Your subclasses must override two methods: <code>handleGetObject</code> 0N/A * and <code>getKeys()</code>. 0N/A * <h4>ResourceBundle.Control</h4> 0N/A * The {@link ResourceBundle.Control} class provides information necessary 0N/A * to perform the bundle loading process by the <code>getBundle</code> 0N/A * factory methods that take a <code>ResourceBundle.Control</code> 0N/A * instance. You can implement your own subclass in order to enable 0N/A * non-standard resource bundle formats, change the search strategy, or 0N/A * define caching parameters. Refer to the descriptions of the class and the 0N/A * {@link #getBundle(String, Locale, ClassLoader, Control) getBundle} 0N/A * factory method for details. 0N/A * <h4>Cache Management</h4> 0N/A * Resource bundle instances created by the <code>getBundle</code> factory 0N/A * methods are cached by default, and the factory methods return the same 0N/A * resource bundle instance multiple times if it has been 0N/A * cached. <code>getBundle</code> clients may clear the cache, manage the 0N/A * lifetime of cached resource bundle instances using time-to-live values, 0N/A * or specify not to cache resource bundle instances. Refer to the 0N/A * descriptions of the {@linkplain #getBundle(String, Locale, ClassLoader, 0N/A * Control) <code>getBundle</code> factory method}, {@link 0N/A * #clearCache(ClassLoader) clearCache}, {@link 0N/A * Control#getTimeToLive(String, Locale) 0N/A * ResourceBundle.Control.getTimeToLive}, and {@link 0N/A * Control#needsReload(String, Locale, String, ClassLoader, ResourceBundle, 0N/A * long) ResourceBundle.Control.needsReload} for details. 0N/A * The following is a very simple example of a <code>ResourceBundle</code> 0N/A * subclass, <code>MyResources</code>, that manages two resources (for a larger number of 0N/A * resources you would probably use a <code>Map</code>). 0N/A * Notice that you don't need to supply a value if 0N/A * a "parent-level" <code>ResourceBundle</code> handles the same 0N/A * key with the same value (as for the okKey below). 0N/A * // default (English language, United States) 0N/A * public class MyResources extends ResourceBundle { 0N/A * public Object handleGetObject(String key) { 0N/A * if (key.equals("okKey")) return "Ok"; 0N/A * if (key.equals("cancelKey")) return "Cancel"; 0N/A * public Enumeration<String> getKeys() { 0N/A * return Collections.enumeration(keySet()); 0N/A * // Overrides handleKeySet() so that the getKeys() implementation 0N/A * // can rely on the keySet() value. 0N/A * protected Set<String> handleKeySet() { 0N/A * return new HashSet<String>(Arrays.asList("okKey", "cancelKey")); 0N/A * // German language 0N/A * public class MyResources_de extends MyResources { 0N/A * public Object handleGetObject(String key) { 0N/A * // don't need okKey, since parent level handles it. 0N/A * if (key.equals("cancelKey")) return "Abbrechen"; 0N/A * protected Set<String> handleKeySet() { 0N/A * return new HashSet<String>(Arrays.asList("cancelKey")); 0N/A * You do not have to restrict yourself to using a single family of 0N/A * <code>ResourceBundle</code>s. For example, you could have a set of bundles for 0N/A * exception messages, <code>ExceptionResources</code> 0N/A * (<code>ExceptionResources_fr</code>, <code>ExceptionResources_de</code>, ...), 0N/A * and one for widgets, <code>WidgetResource</code> (<code>WidgetResources_fr</code>, 0N/A * <code>WidgetResources_de</code>, ...); breaking up the resources however you like. 0N/A * @see ListResourceBundle 0N/A * @see PropertyResourceBundle 0N/A * @see MissingResourceException 0N/A /** initial size of the bundle cache */ 0N/A /** constant indicating that no resource bundle exists */ 0N/A * The cache is a map from cache keys (with bundle base name, locale, and 0N/A * class loader) to either a resource bundle or NONEXISTENT_BUNDLE wrapped by a 0N/A * The cache is a ConcurrentMap, allowing the cache to be searched 0N/A * concurrently by multiple threads. This will also allow the cache keys 0N/A * to be reclaimed along with the ClassLoaders they reference. 0N/A * This variable would be better named "cache", but we keep the old 0N/A * name for compatibility with some workarounds for bug 4212439. 0N/A * Queue for reference objects referring to class loaders or bundles. 0N/A * The parent bundle of this bundle. 0N/A * The parent bundle is searched by {@link #getObject getObject} 0N/A * when this bundle does not contain a particular resource. 0N/A * The locale for this bundle. 0N/A * The base bundle name for this bundle. 0N/A * The flag indicating this bundle has expired in the cache. 0N/A * The back link to the cache key. null if this bundle isn't in 0N/A * the cache (yet) or has expired. 0N/A * A Set of the keys contained only in this ResourceBundle. 0N/A * Sole constructor. (For invocation by subclass constructors, typically 0N/A * Gets a string for the given key from this resource bundle or one of its parents. 0N/A * Calling this method is equivalent to calling 0N/A * <code>(String) {@link #getObject(java.lang.String) getObject}(key)</code>. 0N/A * @param key the key for the desired string 0N/A * @exception NullPointerException if <code>key</code> is <code>null</code> 0N/A * @exception MissingResourceException if no object for the given key can be found 0N/A * @exception ClassCastException if the object found for the given key is not a string 0N/A * @return the string for the given key 0N/A * Gets a string array for the given key from this resource bundle or one of its parents. 0N/A * Calling this method is equivalent to calling 0N/A * <code>(String[]) {@link #getObject(java.lang.String) getObject}(key)</code>. 0N/A * @param key the key for the desired string array 0N/A * @exception NullPointerException if <code>key</code> is <code>null</code> 0N/A * @exception MissingResourceException if no object for the given key can be found 0N/A * @exception ClassCastException if the object found for the given key is not a string array 0N/A * @return the string array for the given key 0N/A * Gets an object for the given key from this resource bundle or one of its parents. 0N/A * This method first tries to obtain the object from this resource bundle using 0N/A * {@link #handleGetObject(java.lang.String) handleGetObject}. 0N/A * If not successful, and the parent resource bundle is not null, 0N/A * it calls the parent's <code>getObject</code> method. 0N/A * If still not successful, it throws a MissingResourceException. 0N/A * @param key the key for the desired object 0N/A * @exception NullPointerException if <code>key</code> is <code>null</code> 0N/A * @exception MissingResourceException if no object for the given key can be found 0N/A * @return the object for the given key 0N/A * Returns the locale of this resource bundle. This method can be used after a 0N/A * call to getBundle() to determine whether the resource bundle returned really 0N/A * corresponds to the requested locale or is a fallback. 0N/A * @return the locale of this resource bundle 0N/A * Automatic determination of the ClassLoader to be used to load 6338N/A * resources on behalf of the client. 0N/A // When the caller's loader is the boot class loader, cl is null 0N/A // here. In that case, ClassLoader.getSystemClassLoader() may 0N/A // return the same class loader that the application is 0N/A // using. We therefore use a wrapper ClassLoader to create a 0N/A // separate scope for bundles loaded on behalf of the Java 0N/A // runtime so that these bundles cannot be returned from the 0N/A // cache to the application (5048280). 0N/A * A wrapper of ClassLoader.getSystemClassLoader(). 0N/A * Sets the parent bundle of this bundle. 0N/A * The parent bundle is searched by {@link #getObject getObject} 0N/A * when this bundle does not contain a particular resource. 0N/A * @param parent this bundle's parent bundle. 0N/A * Key used for cached resource bundles. The key checks the base 0N/A * name, the locale, and the class loader to determine if the 0N/A * resource is a match to the requested one. The loader may be 0N/A * null, but the base name and the locale must have a non-null 0N/A // These three are the actual keys for lookup in Map. 0N/A // bundle format which is necessary for calling 0N/A // Control.needsReload(). 0N/A // These time values are in CacheKey so that NONEXISTENT_BUNDLE 0N/A // doesn't need to be cloned for caching. 0N/A // The time when the bundle has been loaded 0N/A // The time when the bundle expires in the cache, or either 0N/A // Control.TTL_DONT_CACHE or Control.TTL_NO_EXPIRATION_CONTROL. 0N/A // Placeholder for an error report by a Throwable 0N/A // Hash code value cache to avoid recalculating the hash code 0N/A // of this instance. 0N/A //quick check to see if they are not equal 0N/A //are the names the same? 0N/A // are the locales the same? 0N/A //are refs (both non-null) or (both null)? 0N/A // with a null reference we can no longer find 0N/A // out which class loader was referenced; so 0N/A // treat it as unequal 0N/A // Clear the reference to a Throwable 0N/A //this should never happen 0N/A // Override the cause if the previous one is 0N/A // ClassNotFoundException. 0N/A * The common interface to get a CacheKey in LoaderReference and 0N/A * References to class loaders are weak references, so that they can be 0N/A * garbage collected when nobody else is using them. The ResourceBundle 0N/A * class has no reason to keep class loaders alive. 0N/A * References to bundles are soft references so that they can be garbage 0N/A * collected when they have no hard references. 0N/A * Gets a resource bundle using the specified base name, the default locale, 0N/A * and the caller's class loader. Calling this method is equivalent to calling 0N/A * <code>getBundle(baseName, Locale.getDefault(), this.getClass().getClassLoader())</code>, 0N/A * except that <code>getClassLoader()</code> is run with the security 0N/A * privileges of <code>ResourceBundle</code>. 0N/A * See {@link #getBundle(String, Locale, ClassLoader) getBundle} 0N/A * for a complete description of the search and instantiation strategy. 0N/A * @param baseName the base name of the resource bundle, a fully qualified class name 0N/A * @exception java.lang.NullPointerException 0N/A * if <code>baseName</code> is <code>null</code> 0N/A * @exception MissingResourceException 0N/A * if no resource bundle for the specified base name can be found 0N/A * @return a resource bundle for the given base name and the default locale 0N/A /* must determine loader here, else we break stack invariant */ 0N/A * Returns a resource bundle using the specified base name, the 0N/A * default locale and the specified control. Calling this method 0N/A * is equivalent to calling 0N/A * getBundle(baseName, Locale.getDefault(), 0N/A * this.getClass().getClassLoader(), control), 0N/A * except that <code>getClassLoader()</code> is run with the security 0N/A * privileges of <code>ResourceBundle</code>. See {@link 0N/A * #getBundle(String, Locale, ClassLoader, Control) getBundle} for the 0N/A * complete description of the resource bundle loading process with a 0N/A * <code>ResourceBundle.Control</code>. 0N/A * the base name of the resource bundle, a fully qualified class 0N/A * the control which gives information for the resource bundle 0N/A * @return a resource bundle for the given base name and the default 0N/A * @exception NullPointerException 0N/A * if <code>baseName</code> or <code>control</code> is 0N/A * @exception MissingResourceException 0N/A * if no resource bundle for the specified base name can be found 0N/A * @exception IllegalArgumentException 0N/A * if the given <code>control</code> doesn't perform properly 0N/A * (e.g., <code>control.getCandidateLocales</code> returns null.) 0N/A * Note that validation of <code>control</code> is performed as 0N/A /* must determine loader here, else we break stack invariant */ 0N/A * Gets a resource bundle using the specified base name and locale, 0N/A * and the caller's class loader. Calling this method is equivalent to calling 0N/A * <code>getBundle(baseName, locale, this.getClass().getClassLoader())</code>, 0N/A * except that <code>getClassLoader()</code> is run with the security 0N/A * privileges of <code>ResourceBundle</code>. 0N/A * See {@link #getBundle(String, Locale, ClassLoader) getBundle} 0N/A * for a complete description of the search and instantiation strategy. 0N/A * the base name of the resource bundle, a fully qualified class name 0N/A * the locale for which a resource bundle is desired 0N/A * @exception NullPointerException 0N/A * if <code>baseName</code> or <code>locale</code> is <code>null</code> 0N/A * @exception MissingResourceException 0N/A * if no resource bundle for the specified base name can be found 0N/A * @return a resource bundle for the given base name and locale 0N/A /* must determine loader here, else we break stack invariant */ 0N/A * Returns a resource bundle using the specified base name, target 0N/A * locale and control, and the caller's class loader. Calling this 0N/A * method is equivalent to calling 0N/A * getBundle(baseName, targetLocale, this.getClass().getClassLoader(), 0N/A * except that <code>getClassLoader()</code> is run with the security 0N/A * privileges of <code>ResourceBundle</code>. See {@link 0N/A * #getBundle(String, Locale, ClassLoader, Control) getBundle} for the 0N/A * complete description of the resource bundle loading process with a 0N/A * <code>ResourceBundle.Control</code>. 0N/A * the base name of the resource bundle, a fully qualified 0N/A * @param targetLocale 0N/A * the locale for which a resource bundle is desired 0N/A * the control which gives information for the resource 0N/A * bundle loading process 0N/A * @return a resource bundle for the given base name and a 0N/A * <code>Locale</code> in <code>locales</code> 0N/A * @exception NullPointerException 0N/A * if <code>baseName</code>, <code>locales</code> or 0N/A * <code>control</code> is <code>null</code> 0N/A * @exception MissingResourceException 0N/A * if no resource bundle for the specified base name in any 0N/A * of the <code>locales</code> can be found. 0N/A * @exception IllegalArgumentException 0N/A * if the given <code>control</code> doesn't perform properly 0N/A * (e.g., <code>control.getCandidateLocales</code> returns null.) 0N/A * Note that validation of <code>control</code> is performed as 0N/A /* must determine loader here, else we break stack invariant */ 2712N/A * Gets a resource bundle using the specified base name, locale, and class 2712N/A * <p><a name="default_behavior"/>This method behaves the same as calling 2712N/A * {@link #getBundle(String, Locale, ClassLoader, Control)} passing a 2712N/A * default instance of {@link Control}. The following describes this behavior. 2712N/A * <p><code>getBundle</code> uses the base name, the specified locale, and 2712N/A * the default locale (obtained from {@link java.util.Locale#getDefault() 2712N/A * Locale.getDefault}) to generate a sequence of <a 2712N/A * name="candidates"><em>candidate bundle names</em></a>. If the specified 2712N/A * locale's language, script, country, and variant are all empty strings, 2712N/A * then the base name is the only candidate bundle name. Otherwise, a list 2712N/A * of candidate locales is generated from the attribute values of the 2712N/A * specified locale (language, script, country and variant) and appended to 2712N/A * the base name. Typically, this will look like the following: 2712N/A * baseName + "_" + language + "_" + script + "_" + country + "_" + variant 2712N/A * baseName + "_" + language + "_" + script + "_" + country 2712N/A * baseName + "_" + language + "_" + script 2712N/A * baseName + "_" + language + "_" + country + "_" + variant 2712N/A * baseName + "_" + language + "_" + country 2712N/A * baseName + "_" + language 2712N/A * <p>Candidate bundle names where the final component is an empty string 2712N/A * are omitted, along with the underscore. For example, if country is an 2712N/A * empty string, the second and the fifth candidate bundle names above 2712N/A * would be omitted. Also, if script is an empty string, the candidate names 2712N/A * including script are omitted. For example, a locale with language "de" 2712N/A * and variant "JAVA" will produce candidate names with base name 2712N/A * In the case that the variant contains one or more underscores ('_'), a 2712N/A * sequence of bundle names generated by truncating the last underscore and 2712N/A * the part following it is inserted after a candidate bundle name with the 2712N/A * original variant. For example, for a locale with language "en", script 2712N/A * "Latn, country "US" and variant "WINDOWS_VISTA", and bundle base name 2712N/A * "MyResource", the list of candidate bundle names below is generated: 2712N/A * MyResource_en_Latn_US_WINDOWS_VISTA 2712N/A * MyResource_en_Latn_US_WINDOWS 2712N/A * MyResource_en_US_WINDOWS_VISTA 2712N/A * <blockquote><b>Note:</b> For some <code>Locale</code>s, the list of 2712N/A * candidate bundle names contains extra names, or the order of bundle names 2712N/A * is slightly modified. See the description of the default implementation 2712N/A * of {@link Control#getCandidateLocales(String, Locale) 2712N/A * getCandidateLocales} for details.</blockquote> 2712N/A * <p><code>getBundle</code> then iterates over the candidate bundle names 2712N/A * to find the first one for which it can <em>instantiate</em> an actual 2712N/A * resource bundle. It uses the default controls' {@link Control#getFormats 2712N/A * getFormats} method, which generates two bundle names for each generated 2712N/A * name, the first a class name and the second a properties file name. For 2712N/A * each candidate bundle name, it attempts to create a resource bundle: 2712N/A * <ul><li>First, it attempts to load a class using the generated class name. 2712N/A * If such a class can be found and loaded using the specified class 2712N/A * loader, is assignment compatible with ResourceBundle, is accessible from 2712N/A * ResourceBundle, and can be instantiated, <code>getBundle</code> creates a 2712N/A * new instance of this class and uses it as the <em>result resource 2712N/A * <li>Otherwise, <code>getBundle</code> attempts to locate a property 2712N/A * resource file using the generated properties file name. It generates a 2712N/A * path name from the candidate bundle name by replacing all "." characters 2712N/A * with "/" and appending the string ".properties". It attempts to find a 2712N/A * "resource" with this name using {@link 2712N/A * java.lang.ClassLoader#getResource(java.lang.String) 2712N/A * ClassLoader.getResource}. (Note that a "resource" in the sense of 2712N/A * <code>getResource</code> has nothing to do with the contents of a 2712N/A * resource bundle, it is just a container of data, such as a file.) If it 2712N/A * finds a "resource", it attempts to create a new {@link 2712N/A * PropertyResourceBundle} instance from its contents. If successful, this 2712N/A * instance becomes the <em>result resource bundle</em>. </ul> 2712N/A * <p>This continues until a result resource bundle is instantiated or the 2712N/A * list of candidate bundle names is exhausted. If no matching resource 2712N/A * bundle is found, the default control's {@link Control#getFallbackLocale 2712N/A * getFallbackLocale} method is called, which returns the current default 2712N/A * locale. A new sequence of candidate locale names is generated using this 2712N/A * locale and and searched again, as above. 2712N/A * <p>If still no result bundle is found, the base name alone is looked up. If 2712N/A * this still fails, a <code>MissingResourceException</code> is thrown. 2712N/A * <p><a name="parent_chain"/> Once a result resource bundle has been found, 2712N/A * its <em>parent chain</em> is instantiated. If the result bundle already 2712N/A * has a parent (perhaps because it was returned from a cache) the chain is 2712N/A * <p>Otherwise, <code>getBundle</code> examines the remainder of the 2712N/A * candidate locale list that was used during the pass that generated the 2712N/A * result resource bundle. (As before, candidate bundle names where the 2712N/A * final component is an empty string are omitted.) When it comes to the 2712N/A * end of the candidate list, it tries the plain bundle name. With each of the 2712N/A * candidate bundle names it attempts to instantiate a resource bundle (first 2712N/A * looking for a class and then a properties file, as described above). 2712N/A * <p>Whenever it succeeds, it calls the previously instantiated resource 0N/A * bundle's {@link #setParent(java.util.ResourceBundle) setParent} method 2712N/A * with the new resource bundle. This continues until the list of names 2712N/A * is exhausted or the current bundle already has a non-null parent. 2712N/A * <p>Once the parent chain is complete, the bundle is returned. 2712N/A * <p><b>Note:</b> <code>getBundle</code> caches instantiated resource 2712N/A * bundles and might return the same resource bundle instance multiple times. 2712N/A * <p><b>Note:</b>The <code>baseName</code> argument should be a fully 2712N/A * qualified class name. However, for compatibility with earlier versions, 2712N/A * Sun's Java SE Runtime Environments do not verify this, and so it is 2712N/A * possible to access <code>PropertyResourceBundle</code>s by specifying a 2712N/A * path name (using "/") instead of a fully qualified class name (using 0N/A * <p><a name="default_behavior_example"/> 2712N/A * <strong>Example:</strong> 2712N/A * The following class and property files are provided: 0N/A * MyResources_fr_CH.class 0N/A * MyResources_es_ES.class 2712N/A * The contents of all files are valid (that is, public non-abstract 2712N/A * subclasses of <code>ResourceBundle</code> for the ".class" files, 2712N/A * syntactically correct ".properties" files). The default locale is 2712N/A * <code>Locale("en", "GB")</code>. 2712N/A * <p>Calling <code>getBundle</code> with the locale arguments below will 2712N/A * instantiate resource bundles as follows: 2712N/A * <tr><td>Locale("es", "ES")</td><td>MyResources_es_ES.class, parent MyResources.class</td></tr> 2712N/A * is also hidden by MyResources.class. 0N/A * @param baseName the base name of the resource bundle, a fully qualified class name 0N/A * @param locale the locale for which a resource bundle is desired 0N/A * @param loader the class loader from which to load the resource bundle 0N/A * @return a resource bundle for the given base name and locale 0N/A * @exception java.lang.NullPointerException 0N/A * if <code>baseName</code>, <code>locale</code>, or <code>loader</code> is <code>null</code> 0N/A * @exception MissingResourceException 0N/A * if no resource bundle for the specified base name can be found 0N/A * Returns a resource bundle using the specified base name, target 0N/A * locale, class loader and control. Unlike the {@linkplain 0N/A * #getBundle(String, Locale, ClassLoader) <code>getBundle</code> 0N/A * factory methods with no <code>control</code> argument}, the given 0N/A * <code>control</code> specifies how to locate and instantiate resource 0N/A * bundles. Conceptually, the bundle loading process with the given 0N/A * <code>control</code> is performed in the following steps. 0N/A * <li>This factory method looks up the resource bundle in the cache for 0N/A * the specified <code>baseName</code>, <code>targetLocale</code> and 0N/A * <code>loader</code>. If the requested resource bundle instance is 0N/A * found in the cache and the time-to-live periods of the instance and 0N/A * all of its parent instances have not expired, the instance is returned 0N/A * to the caller. Otherwise, this factory method proceeds with the 0N/A * loading process below.</li> 0N/A * <li>The {@link ResourceBundle.Control#getFormats(String) 0N/A * control.getFormats} method is called to get resource bundle formats 0N/A * to produce bundle or resource names. The strings 0N/A * designate class-based and {@linkplain PropertyResourceBundle 0N/A * property}-based resource bundles, respectively. Other strings 0N/A * starting with <code>"java."</code> are reserved for future extensions 0N/A * and must not be used for application-defined formats. Other strings 0N/A * designate application-defined formats.</li> 0N/A * <li>The {@link ResourceBundle.Control#getCandidateLocales(String, 0N/A * Locale) control.getCandidateLocales} method is called with the target 0N/A * locale to get a list of <em>candidate <code>Locale</code>s</em> for 0N/A * which resource bundles are searched.</li> 0N/A * <li>The {@link ResourceBundle.Control#newBundle(String, Locale, 0N/A * String, ClassLoader, boolean) control.newBundle} method is called to 0N/A * instantiate a <code>ResourceBundle</code> for the base bundle name, a 0N/A * candidate locale, and a format. (Refer to the note on the cache 0N/A * lookup below.) This step is iterated over all combinations of the 0N/A * candidate locales and formats until the <code>newBundle</code> method 0N/A * returns a <code>ResourceBundle</code> instance or the iteration has 0N/A * used up all the combinations. For example, if the candidate locales 0N/A * are <code>Locale("de", "DE")</code>, <code>Locale("de")</code> and 0N/A * <code>Locale("")</code> and the formats are <code>"java.class"</code> 0N/A * sequence of locale-format combinations to be used to call 0N/A * <code>control.newBundle</code>. 0N/A * <table style="width: 50%; text-align: left; margin-left: 40px;" 0N/A * border="0" cellpadding="2" cellspacing="2"> 0N/A * style="vertical-align: top; text-align: left; font-weight: bold; width: 50%;">Locale<br> 0N/A * style="vertical-align: top; text-align: left; font-weight: bold; width: 50%;">format<br> 0N/A * <td style="vertical-align: top; width: 50%;">Locale("de", "DE")<br> 0N/A * <td style="vertical-align: top; width: 50%;">java.class<br> 0N/A * <td style="vertical-align: top; width: 50%;">Locale("de", "DE")</td> 0N/A * <td style="vertical-align: top; width: 50%;">Locale("de")</td> 0N/A * <td style="vertical-align: top; width: 50%;">java.class</td> 0N/A * <td style="vertical-align: top; width: 50%;">Locale("de")</td> 0N/A * <td style="vertical-align: top; width: 50%;">Locale("")<br> 0N/A * <td style="vertical-align: top; width: 50%;">java.class</td> 0N/A * <td style="vertical-align: top; width: 50%;">Locale("")</td> 0N/A * <li>If the previous step has found no resource bundle, proceed to 0N/A * Step 6. If a bundle has been found that is a base bundle (a bundle 0N/A * for <code>Locale("")</code>), and the candidate locale list only contained 0N/A * <code>Locale("")</code>, return the bundle to the caller. If a bundle 0N/A * has been found that is a base bundle, but the candidate locale list 0N/A * contained locales other than Locale(""), put the bundle on hold and 0N/A * proceed to Step 6. If a bundle has been found that is not a base 0N/A * bundle, proceed to Step 7.</li> 0N/A * <li>The {@link ResourceBundle.Control#getFallbackLocale(String, 0N/A * Locale) control.getFallbackLocale} method is called to get a fallback 0N/A * locale (alternative to the current target locale) to try further 0N/A * finding a resource bundle. If the method returns a non-null locale, 0N/A * it becomes the next target locale and the loading process starts over 0N/A * from Step 3. Otherwise, if a base bundle was found and put on hold in 0N/A * a previous Step 5, it is returned to the caller now. Otherwise, a 0N/A * MissingResourceException is thrown.</li> 0N/A * <li>At this point, we have found a resource bundle that's not the 0N/A * base bundle. If this bundle set its parent during its instantiation, 0N/A * it is returned to the caller. Otherwise, its <a 0N/A * instantiated based on the list of candidate locales from which it was 0N/A * found. Finally, the bundle is returned to the caller.</li> 0N/A * <p>During the resource bundle loading process above, this factory 0N/A * method looks up the cache before calling the {@link 0N/A * Control#newBundle(String, Locale, String, ClassLoader, boolean) 0N/A * control.newBundle} method. If the time-to-live period of the 0N/A * resource bundle found in the cache has expired, the factory method 0N/A * calls the {@link ResourceBundle.Control#needsReload(String, Locale, 0N/A * String, ClassLoader, ResourceBundle, long) control.needsReload} 0N/A * method to determine whether the resource bundle needs to be reloaded. 0N/A * If reloading is required, the factory method calls 0N/A * <code>control.newBundle</code> to reload the resource bundle. If 0N/A * <code>control.newBundle</code> returns <code>null</code>, the factory 0N/A * method puts a dummy resource bundle in the cache as a mark of 0N/A * nonexistent resource bundles in order to avoid lookup overhead for 0N/A * subsequent requests. Such dummy resource bundles are under the same 0N/A * expiration control as specified by <code>control</code>. 0N/A * <p>All resource bundles loaded are cached by default. Refer to 0N/A * {@link Control#getTimeToLive(String,Locale) 0N/A * control.getTimeToLive} for details. 0N/A * <p>The following is an example of the bundle loading process with the 0N/A * default <code>ResourceBundle.Control</code> implementation. 0N/A * <li>Base bundle name: <code>foo.bar.Messages</code> 0N/A * <li>Requested <code>Locale</code>: {@link Locale#ITALY}</li> 0N/A * <li>Default <code>Locale</code>: {@link Locale#FRENCH}</li> 0N/A * <li>Available resource bundles: 0N/A * <p>First, <code>getBundle</code> tries loading a resource bundle in 0N/A * the following sequence. 0N/A * <li>class <code>foo.bar.Messages_it_IT</code> 0N/A * <li>class <code>foo.bar.Messages_it</code></li> 0N/A * <li>class <code>foo.bar.Messages</code></li> 0N/A * <p>At this point, <code>getBundle</code> finds 0N/A * because it's the base bundle. <code>getBundle</code> calls {@link 0N/A * Control#getFallbackLocale(String, Locale) 0N/A * control.getFallbackLocale("foo.bar.Messages", Locale.ITALY)} which 0N/A * returns <code>Locale.FRENCH</code>. Next, <code>getBundle</code> 0N/A * tries loading a bundle in the following sequence. 0N/A * <li>class <code>foo.bar.Messages_fr</code></li> 0N/A * <li>class <code>foo.bar.Messages</code></li> 0N/A * <p><code>getBundle</code> finds 0N/A * <code>ResourceBundle</code> instance. Then, <code>getBundle</code> 0N/A * sets up its parent chain from the list of the candiate locales. Only 0N/A * <code>getBundle</code> creates a <code>ResourceBundle</code> instance 0N/A * that becomes the parent of the instance for 0N/A * the base name of the resource bundle, a fully qualified 0N/A * @param targetLocale 0N/A * the locale for which a resource bundle is desired 0N/A * the class loader from which to load the resource bundle 0N/A * the control which gives information for the resource 0N/A * bundle loading process 0N/A * @return a resource bundle for the given base name and locale 0N/A * @exception NullPointerException 0N/A * if <code>baseName</code>, <code>targetLocale</code>, 0N/A * <code>loader</code>, or <code>control</code> is 0N/A * @exception MissingResourceException 0N/A * if no resource bundle for the specified base name can be found 0N/A * @exception IllegalArgumentException 0N/A * if the given <code>control</code> doesn't perform properly 0N/A * (e.g., <code>control.getCandidateLocales</code> returns null.) 0N/A * Note that validation of <code>control</code> is performed as 0N/A // We create a CacheKey here for use by this call. The base 0N/A // name and loader will never change during the bundle loading 0N/A // process. We have to make sure that the locale is set before 0N/A // using it as a cache key. 0N/A // Quick lookup of the cache. 0N/A // If this bundle and all of its parents are valid (not expired), 0N/A // then return this bundle. If any of the bundles is expired, we 0N/A // don't call control.needsReload here but instead drop into the 0N/A // complete loading process below. 0N/A // No valid bundle was found in the cache, so we need to load the 0N/A // resource bundle and its parents. 0N/A // If the loaded bundle is the base bundle and exactly for the 0N/A // requested locale or the only candidate locale, then take the 0N/A // bundle as the resulting one. If the loaded bundle is the base 0N/A // bundle, it's put on hold until we finish processing all 0N/A // fallback locales. 0N/A // If the base bundle has been loaded, keep the reference in 0N/A // baseBundle so that we can avoid any redundant loading in case 0N/A // the control specify not to cache bundles. 0N/A * Checks if the given <code>List</code> is not null, not empty, 0N/A * not having null in its elements. 0N/A // Before we do the real loading work, see whether we need to 0N/A // do some housekeeping: If references to class loaders or 0N/A // resource bundles have been nulled out, remove all related 0N/A // information from the cache. 0N/A // flag indicating the resource bundle has expired in the cache 0N/A // First, look up the cache to see if it's in the cache, without 2791N/A // attempting to load bundle. 0N/A // If its parent is the one asked for by the candidate 0N/A // locales (the runtime lookup path), we can take the cached 0N/A // one. (If it's not identical, then we'd have to check the 0N/A // parent's parents to be consistent with what's been 0N/A // Otherwise, remove the cached one since we can't keep 0N/A // the same bundles having different parents. 2791N/A // Put NONEXISTENT_BUNDLE in the cache as a mark that there's no bundle 2791N/A // instance for the locale. 0N/A // Here we actually load the bundle in the order of formats 0N/A // specified by the getFormats() value. 0N/A // We need to handle the LinkageError case due to 0N/A // inconsistent case-sensitivity in ClassLoader. 0N/A // See 6572242 for details. 0N/A // Set the format in the cache key so that it can be 0N/A // used when calling needsReload later. 0N/A // Bundle provider might reuse instances. So we should make 0N/A // sure to clear the expired flag here. 0N/A * Determines whether any of resource bundles in the parent chain, 0N/A * including the leaf, have expired. 0N/A * Throw a MissingResourceException with proper message 0N/A // If the cause is a MissingResourceException, avoid creating 0N/A // a long chain. (6355009) 0N/A * Finds a bundle in the cache. Any expired bundles are marked as 0N/A * `expired' and removed from the cache upon return. 0N/A * @param cacheKey the key to look up the cache 0N/A * @param control the Control to be used for the expiration control 0N/A * @return the cached bundle, or null if the bundle is not found in the 0N/A * cache or its parent has expired. <code>bundle.expire</code> is true 0N/A * upon return if the bundle in the cache has expired. 0N/A // If the parent has expired, then this one must also expire. We 0N/A // check only the immediate parent because the actual loading is 0N/A // done from the root (base) to leaf (child) and the purpose of 0N/A // checking is to propagate expiration towards the leaf. For 0N/A // example, if the requested locale is ja_JP_JP and there are 0N/A // bundles for all of the candidates in the cache, we have a list, 0N/A // base <- ja <- ja_JP <- ja_JP_JP 0N/A // If ja has expired, then it will reload ja and the list becomes a 0N/A // " <- ja (expired) <- ja_JP <- ja_JP_JP 0N/A // When looking up ja_JP in the cache, it finds ja_JP in the cache 0N/A // which references to the expired ja. Then, ja_JP is marked as 0N/A // expired and removed from the cache. This will be propagated to 0N/A // Now, it's possible, for example, that while loading new ja_JP, 0N/A // someone else has started loading the same bundle and finds the 0N/A // base bundle has expired. Then, what we get from the first 0N/A // getBundle call includes the expired base bundle. However, if 0N/A // someone else didn't start its loading, we wouldn't know if the 0N/A // base bundle has expired at the end of the loading process. The 0N/A // expiration control doesn't guarantee that the returned bundle and 0N/A // its parents haven't expired. 0N/A // We could check the entire parent chain to see if there's any in 0N/A // the chain that has expired. But this process may never end. An 0N/A // extreme case would be that getTimeToLive returns 0 and 0N/A // needsReload always returns true. 0N/A // its TTL period has expired. 0N/A // Synchronize here to call needsReload to avoid 0N/A // redundant concurrent calls for the same bundle. 0N/A // If the bundle needs to be reloaded, then 0N/A // remove the bundle from the cache, but 0N/A // return the bundle with the expired flag 0N/A // Update the expiration control info. and reuse 0N/A // the same bundle instance 0N/A // We just remove NONEXISTENT_BUNDLE from the cache. 0N/A * Put a new bundle in the cache. 0N/A * @param cacheKey the key for the resource bundle 0N/A * @param bundle the resource bundle to be put in the cache 0N/A * @return the ResourceBundle for the cacheKey; if someone has put 0N/A * the bundle before this call, the one found in the cache is 0N/A // Put the bundle in the cache if it's not been in the cache. 0N/A // If someone else has put the same bundle in the cache before 0N/A // us and it has not expired, we should use the one in the cache. 0N/A // Clear the back link to the cache key 0N/A // Clear the reference in the BundleReference so that 0N/A // it won't be enqueued. 0N/A // Replace the invalid (garbage collected or expired) 0N/A // instance with the valid one. 0N/A // If any expiration time is specified, set the time to be 0N/A // expired in the cache. 0N/A * Removes all resource bundles from the cache that have been loaded 0N/A * using the caller's class loader. 0N/A * @see ResourceBundle.Control#getTimeToLive(String,Locale) 0N/A * Removes all resource bundles from the cache that have been loaded 0N/A * using the given class loader. 0N/A * @param loader the class loader 0N/A * @exception NullPointerException if <code>loader</code> is null 0N/A * @see ResourceBundle.Control#getTimeToLive(String,Locale) 0N/A * Gets an object for the given key from this resource bundle. 0N/A * Returns null if this resource bundle does not contain an 0N/A * object for the given key. 0N/A * @param key the key for the desired object 0N/A * @exception NullPointerException if <code>key</code> is <code>null</code> 0N/A * @return the object for the given key, or null 0N/A * Returns an enumeration of the keys. 0N/A * @return an <code>Enumeration</code> of the keys contained in 0N/A * this <code>ResourceBundle</code> and its parent bundles. 0N/A * Determines whether the given <code>key</code> is contained in 0N/A * this <code>ResourceBundle</code> or its parent bundles. 0N/A * the resource <code>key</code> 0N/A * @return <code>true</code> if the given <code>key</code> is 0N/A * contained in this <code>ResourceBundle</code> or its 0N/A * parent bundles; <code>false</code> otherwise. 0N/A * @exception NullPointerException 0N/A * if <code>key</code> is <code>null</code> 0N/A * Returns a <code>Set</code> of all keys contained in this 0N/A * <code>ResourceBundle</code> and its parent bundles. 0N/A * @return a <code>Set</code> of all keys contained in this 0N/A * <code>ResourceBundle</code> and its parent bundles. 0N/A * Returns a <code>Set</code> of the keys contained <em>only</em> 0N/A * in this <code>ResourceBundle</code>. 0N/A * <p>The default implementation returns a <code>Set</code> of the 0N/A * keys returned by the {@link #getKeys() getKeys} method except 0N/A * for the ones for which the {@link #handleGetObject(String) 0N/A * handleGetObject} method returns <code>null</code>. Once the 0N/A * <code>Set</code> has been created, the value is kept in this 0N/A * <code>ResourceBundle</code> in order to avoid producing the 2712N/A * same <code>Set</code> in subsequent calls. Subclasses can 2712N/A * override this method for faster handling. 0N/A * @return a <code>Set</code> of the keys contained only in this 0N/A * <code>ResourceBundle</code> 0N/A synchronized (
this) {
0N/A * <code>ResourceBundle.Control</code> defines a set of callback methods 0N/A * that are invoked by the {@link ResourceBundle#getBundle(String, 0N/A * Locale, ClassLoader, Control) ResourceBundle.getBundle} factory 0N/A * methods during the bundle loading process. In other words, a 0N/A * <code>ResourceBundle.Control</code> collaborates with the factory 0N/A * methods for loading resource bundles. The default implementation of 0N/A * the callback methods provides the information necessary for the 0N/A * factory methods to perform the <a 0N/A * <p>In addition to the callback methods, the {@link 0N/A * #toBundleName(String, Locale) toBundleName} and {@link 0N/A * #toResourceName(String, String) toResourceName} methods are defined 0N/A * primarily for convenience in implementing the callback 0N/A * methods. However, the <code>toBundleName</code> method could be 0N/A * overridden to provide different conventions in the organization and 0N/A * packaging of localized resources. The <code>toResourceName</code> 0N/A * method is <code>final</code> to avoid use of wrong resource and class 0N/A * <p>Two factory methods, {@link #getControl(List)} and {@link 0N/A * #getNoFallbackControl(List)}, provide 0N/A * <code>ResourceBundle.Control</code> instances that implement common 0N/A * variations of the default bundle loading process. 0N/A * <p>The formats returned by the {@link Control#getFormats(String) 0N/A * getFormats} method and candidate locales returned by the {@link 0N/A * ResourceBundle.Control#getCandidateLocales(String, Locale) 0N/A * getCandidateLocales} method must be consistent in all 0N/A * <code>ResourceBundle.getBundle</code> invocations for the same base 0N/A * bundle. Otherwise, the <code>ResourceBundle.getBundle</code> methods 0N/A * may return unintended bundles. For example, if only 0N/A * <code>"java.class"</code> is returned by the <code>getFormats</code> 0N/A * method for the first call to <code>ResourceBundle.getBundle</code> 0N/A * second call will return the class-based one that has been cached 0N/A * during the first call. 0N/A * <p>A <code>ResourceBundle.Control</code> instance must be thread-safe 0N/A * if it's simultaneously used by multiple threads. 0N/A * <code>ResourceBundle.getBundle</code> does not synchronize to call 0N/A * the <code>ResourceBundle.Control</code> methods. The default 0N/A * implementations of the methods are thread-safe. 0N/A * <p>Applications can specify <code>ResourceBundle.Control</code> 0N/A * instances returned by the <code>getControl</code> factory methods or 0N/A * created from a subclass of <code>ResourceBundle.Control</code> to 0N/A * customize the bundle loading process. The following are examples of 0N/A * changing the default bundle loading process. 0N/A * <p><b>Example 1</b> 0N/A * <p>The following code lets <code>ResourceBundle.getBundle</code> look 0N/A * up only properties-based resources. 0N/A * import java.util.*; 0N/A * import static java.util.ResourceBundle.Control.*; 0N/A * ResourceBundle bundle = 0N/A * ResourceBundle.getBundle("MyResources", new Locale("fr", "CH"), 0N/A * ResourceBundle.Control.getControl(FORMAT_PROPERTIES)); 0N/A * Given the resource bundles in the <a 0N/A * the <code>ResourceBundle.getBundle</code> description, this 0N/A * <code>ResourceBundle.getBundle</code> call loads 0N/A * is not hidden, but <code>MyResources_fr_CH.class</code> is.) 0N/A * <p><b>Example 2</b> 0N/A * <p>The following is an example of loading XML-based bundles 0N/A * using {@link Properties#loadFromXML(java.io.InputStream) 0N/A * Properties.loadFromXML}. 0N/A * ResourceBundle rb = ResourceBundle.getBundle("Messages", 0N/A * new ResourceBundle.Control() { 0N/A * public List<String> getFormats(String baseName) { 0N/A * if (baseName == null) 0N/A * throw new NullPointerException(); 0N/A * return Arrays.asList("xml"); 0N/A * public ResourceBundle newBundle(String baseName, 0N/A * ClassLoader loader, 0N/A * throws IllegalAccessException, 0N/A * InstantiationException, 0N/A * if (baseName == null || locale == null 0N/A * || format == null || loader == null) 0N/A * throw new NullPointerException(); 0N/A * ResourceBundle bundle = null; 0N/A * if (format.equals("xml")) { 0N/A * String bundleName = toBundleName(baseName, locale); 0N/A * String resourceName = toResourceName(bundleName, format); 0N/A * InputStream stream = null; 0N/A * URL url = loader.getResource(resourceName); 0N/A * if (url != null) { 0N/A * URLConnection connection = url.openConnection(); 0N/A * if (connection != null) { 0N/A * // Disable caches to get fresh data for 0N/A * connection.setUseCaches(false); 0N/A * stream = connection.getInputStream(); 0N/A * stream = loader.getResourceAsStream(resourceName); 0N/A * if (stream != null) { 0N/A * BufferedInputStream bis = new BufferedInputStream(stream); 0N/A * bundle = new XMLResourceBundle(bis); 0N/A * private static class XMLResourceBundle extends ResourceBundle { 0N/A * private Properties props; 0N/A * XMLResourceBundle(InputStream stream) throws IOException { 0N/A * props = new Properties(); 0N/A * props.loadFromXML(stream); 0N/A * protected Object handleGetObject(String key) { 0N/A * return props.getProperty(key); 0N/A * public Enumeration<String> getKeys() { 0N/A * The default format <code>List</code>, which contains the strings 0N/A * this order. This <code>List</code> is {@linkplain 0N/A * Collections#unmodifiableList(List) unmodifiable}. 0N/A * @see #getFormats(String) 0N/A * The class-only format <code>List</code> containing 0N/A * <code>"java.class"</code>. This <code>List</code> is {@linkplain 0N/A * Collections#unmodifiableList(List) unmodifiable}. 0N/A * @see #getFormats(String) 0N/A * The properties-only format <code>List</code> containing 0N/A * {@linkplain Collections#unmodifiableList(List) unmodifiable}. 0N/A * @see #getFormats(String) 0N/A * The time-to-live constant for not caching loaded resource bundle 0N/A * @see #getTimeToLive(String, Locale) 0N/A * The time-to-live constant for disabling the expiration control 0N/A * for loaded resource bundle instances in the cache. 0N/A * @see #getTimeToLive(String, Locale) 0N/A * Sole constructor. (For invocation by subclass constructors, 0N/A * typically implicit.) 0N/A * Returns a <code>ResourceBundle.Control</code> in which the {@link 0N/A * #getFormats(String) getFormats} method returns the specified 0N/A * <code>formats</code>. The <code>formats</code> must be equal to 0N/A * one of {@link Control#FORMAT_PROPERTIES}, {@link 0N/A * Control#FORMAT_CLASS} or {@link 0N/A * Control#FORMAT_DEFAULT}. <code>ResourceBundle.Control</code> 0N/A * instances returned by this method are singletons and thread-safe. 0N/A * <p>Specifying {@link Control#FORMAT_DEFAULT} is equivalent to 0N/A * instantiating the <code>ResourceBundle.Control</code> class, 0N/A * except that this method returns a singleton. 0N/A * the formats to be returned by the 0N/A * <code>ResourceBundle.Control.getFormats</code> method 0N/A * @return a <code>ResourceBundle.Control</code> supporting the 0N/A * specified <code>formats</code> 0N/A * @exception NullPointerException 0N/A * if <code>formats</code> is <code>null</code> 0N/A * @exception IllegalArgumentException 0N/A * if <code>formats</code> is unknown 0N/A * Returns a <code>ResourceBundle.Control</code> in which the {@link 0N/A * #getFormats(String) getFormats} method returns the specified 0N/A * <code>formats</code> and the {@link 0N/A * Control#getFallbackLocale(String, Locale) getFallbackLocale} 0N/A * method returns <code>null</code>. The <code>formats</code> must 0N/A * be equal to one of {@link Control#FORMAT_PROPERTIES}, {@link 0N/A * Control#FORMAT_CLASS} or {@link Control#FORMAT_DEFAULT}. 0N/A * <code>ResourceBundle.Control</code> instances returned by this 0N/A * method are singletons and thread-safe. 0N/A * the formats to be returned by the 0N/A * <code>ResourceBundle.Control.getFormats</code> method 0N/A * @return a <code>ResourceBundle.Control</code> supporting the 0N/A * specified <code>formats</code> with no fallback 0N/A * <code>Locale</code> support 0N/A * @exception NullPointerException 0N/A * if <code>formats</code> is <code>null</code> 0N/A * @exception IllegalArgumentException 0N/A * if <code>formats</code> is unknown 0N/A * Returns a <code>List</code> of <code>String</code>s containing 0N/A * formats to be used to load resource bundles for the given 0N/A * <code>baseName</code>. The <code>ResourceBundle.getBundle</code> 0N/A * factory method tries to load resource bundles with formats in the 0N/A * order specified by the list. The list returned by this method 0N/A * must have at least one <code>String</code>. The predefined 0N/A * formats are <code>"java.class"</code> for class-based resource 0N/A * PropertyResourceBundle properties-based} ones. Strings starting 0N/A * with <code>"java."</code> are reserved for future extensions and 0N/A * must not be used by application-defined formats. 0N/A * <p>It is not a requirement to return an immutable (unmodifiable) 0N/A * <code>List</code>. However, the returned <code>List</code> must 0N/A * not be mutated after it has been returned by 0N/A * <code>getFormats</code>. 0N/A * <p>The default implementation returns {@link #FORMAT_DEFAULT} so 0N/A * that the <code>ResourceBundle.getBundle</code> factory method 0N/A * looks up first class-based resource bundles, then 0N/A * properties-based ones. 0N/A * the base name of the resource bundle, a fully qualified class 0N/A * @return a <code>List</code> of <code>String</code>s containing 0N/A * formats for loading resource bundles. 0N/A * @exception NullPointerException 0N/A * if <code>baseName</code> is null 0N/A * @see #FORMAT_DEFAULT 0N/A * @see #FORMAT_CLASS 0N/A * @see #FORMAT_PROPERTIES 0N/A * Returns a <code>List</code> of <code>Locale</code>s as candidate 0N/A * locales for <code>baseName</code> and <code>locale</code>. This 0N/A * method is called by the <code>ResourceBundle.getBundle</code> 0N/A * factory method each time the factory method tries finding a 0N/A * resource bundle for a target <code>Locale</code>. 0N/A * <p>The sequence of the candidate locales also corresponds to the 0N/A * runtime resource lookup path (also known as the <I>parent 0N/A * chain</I>), if the corresponding resource bundles for the 0N/A * candidate locales exist and their parents are not defined by 0N/A * loaded resource bundles themselves. The last element of the list 0N/A * must be a {@linkplain Locale#ROOT root locale} if it is desired to 0N/A * have the base bundle as the terminal of the parent chain. 0N/A * <p>If the given locale is equal to <code>Locale.ROOT</code> (the 0N/A * root locale), a <code>List</code> containing only the root 0N/A * <code>Locale</code> must be returned. In this case, the 0N/A * <code>ResourceBundle.getBundle</code> factory method loads only 0N/A * the base bundle as the resulting resource bundle. 2712N/A * <p>It is not a requirement to return an immutable (unmodifiable) 2712N/A * <code>List</code>. However, the returned <code>List</code> must not 2712N/A * be mutated after it has been returned by 2712N/A * <code>getCandidateLocales</code>. 0N/A * <p>The default implementation returns a <code>List</code> containing 2712N/A * <code>Locale</code>s using the rules described below. In the 2712N/A * description below, <em>L</em>, <em>S</em>, <em>C</em> and <em>V</em> 2712N/A * respectively represent non-empty language, script, country, and 2712N/A * variant. For example, [<em>L</em>, <em>C</em>] represents a 2712N/A * <code>Locale</code> that has non-empty values only for language and 2712N/A * country. The form <em>L</em>("xx") represents the (non-empty) 2712N/A * language value is "xx". For all cases, <code>Locale</code>s whose 0N/A * final component values are empty strings are omitted. 2712N/A * <ol><li>For an input <code>Locale</code> with an empty script value, 2712N/A * append candidate <code>Locale</code>s by omitting the final component 2712N/A * <li> [<em>L</em>, <em>C</em>, <em>V</em>] 2712N/A * <li> [<em>L</em>, <em>C</em>] 2712N/A * <li> <code>Locale.ROOT</code> 2712N/A * <li>For an input <code>Locale</code> with a non-empty script value, 2712N/A * append candidate <code>Locale</code>s by omitting the final component 2712N/A * up to language, then append candidates generated from the 2712N/A * <code>Locale</code> with country and variant restored: 2712N/A * <li> [<em>L</em>, <em>S</em>, <em>C</em>, <em>V</em>] 2712N/A * <li> [<em>L</em>, <em>S</em>, <em>C</em>] 2712N/A * <li> [<em>L</em>, <em>S</em>] 2712N/A * <li> [<em>L</em>, <em>C</em>, <em>V</em>] 2712N/A * <li> [<em>L</em>, <em>C</em>] 2712N/A * <li> <code>Locale.ROOT</code> 2712N/A * <li>For an input <code>Locale</code> with a variant value consisting 2712N/A * of multiple subtags separated by underscore, generate candidate 2712N/A * <code>Locale</code>s by omitting the variant subtags one by one, then 2712N/A * insert them after every occurence of <code> Locale</code>s with the 2712N/A * full variant value in the original list. For example, if the 2712N/A * the variant consists of two subtags <em>V1</em> and <em>V2</em>: 2712N/A * <li> [<em>L</em>, <em>S</em>, <em>C</em>, <em>V1</em>, <em>V2</em>] 2712N/A * <li> [<em>L</em>, <em>S</em>, <em>C</em>, <em>V1</em>] 2712N/A * <li> [<em>L</em>, <em>S</em>, <em>C</em>] 2712N/A * <li> [<em>L</em>, <em>S</em>] 2712N/A * <li> [<em>L</em>, <em>C</em>, <em>V1</em>, <em>V2</em>] 2712N/A * <li> [<em>L</em>, <em>C</em>, <em>V1</em>] 2712N/A * <li> [<em>L</em>, <em>C</em>] 2712N/A * <li> <code>Locale.ROOT</code> 2712N/A * <li>Special cases for Chinese. When an input <code>Locale</code> has the 2712N/A * language "zh" (Chinese) and an empty script value, either "Hans" (Simplified) or 2712N/A * "Hant" (Traditional) might be supplied, depending on the country. 2712N/A * When the country is "CN" (China) or "SG" (Singapore), "Hans" is supplied. 2712N/A * When the country is "HK" (Hong Kong SAR China), "MO" (Macau SAR China), 2712N/A * or "TW" (Taiwan), "Hant" is supplied. For all other countries or when the country 2712N/A * is empty, no script is supplied. For example, for <code>Locale("zh", "CN") 2712N/A * </code>, the candidate list will be: 2712N/A * <li> [<em>L</em>("zh"), <em>S</em>("Hans"), <em>C</em>("CN")] 2712N/A * <li> [<em>L</em>("zh"), <em>S</em>("Hans")] 2712N/A * <li> [<em>L</em>("zh"), <em>C</em>("CN")] 2712N/A * <li> <code>Locale.ROOT</code> 2712N/A * For <code>Locale("zh", "TW")</code>, the candidate list will be: 2712N/A * <li> [<em>L</em>("zh"), <em>S</em>("Hant"), <em>C</em>("TW")] 2712N/A * <li> [<em>L</em>("zh"), <em>S</em>("Hant")] 2712N/A * <li> [<em>L</em>("zh"), <em>C</em>("TW")] 2712N/A * <li> <code>Locale.ROOT</code> 2712N/A * <li>Special cases for Norwegian. Both <code>Locale("no", "NO", 2712N/A * "NY")</code> and <code>Locale("nn", "NO")</code> represent Norwegian 2712N/A * Nynorsk. When a locale's language is "nn", the standard candidate 2712N/A * list is generated up to [<em>L</em>("nn")], and then the following 2712N/A * <ul><li> [<em>L</em>("no"), <em>C</em>("NO"), <em>V</em>("NY")] 2712N/A * <li> [<em>L</em>("no"), <em>C</em>("NO")] 2712N/A * <li> <code>Locale.ROOT</code> 2712N/A * If the locale is exactly <code>Locale("no", "NO", "NY")</code>, it is first 2712N/A * converted to <code>Locale("nn", "NO")</code> and then the above procedure is 2712N/A * <p>Also, Java treats the language "no" as a synonym of Norwegian 2712N/A * Bokmål "nb". Except for the single case <code>Locale("no", 2712N/A * "NO", "NY")</code> (handled above), when an input <code>Locale</code> 2712N/A * has language "no" or "nb", candidate <code>Locale</code>s with 2712N/A * language code "no" and "nb" are interleaved, first using the 2712N/A * requested language, then using its synonym. For example, 2712N/A * <code>Locale("nb", "NO", "POSIX")</code> generates the following 2712N/A * <li> [<em>L</em>("nb"), <em>C</em>("NO"), <em>V</em>("POSIX")] 2712N/A * <li> [<em>L</em>("no"), <em>C</em>("NO"), <em>V</em>("POSIX")] 2712N/A * <li> [<em>L</em>("nb"), <em>C</em>("NO")] 2712N/A * <li> [<em>L</em>("no"), <em>C</em>("NO")] 2712N/A * <li> <code>Locale.ROOT</code> 2712N/A * <code>Locale("no", "NO", "POSIX")</code> would generate the same list 2712N/A * except that locales with "no" would appear before the corresponding 0N/A * <p>The default implementation uses an {@link ArrayList} that 0N/A * overriding implementations may modify before returning it to the 0N/A * caller. However, a subclass must not modify it after it has 0N/A * been returned by <code>getCandidateLocales</code>. 0N/A * <p>For example, if the given <code>baseName</code> is "Messages" 0N/A * and the given <code>locale</code> is 0N/A * <code>Locale("ja", "", "XX")</code>, then a 0N/A * <code>List</code> of <code>Locale</code>s: 0N/A * Locale("ja", "", "XX") 0N/A * is returned. And if the resource bundles for the "ja" and 0N/A * "" <code>Locale</code>s are found, then the runtime resource 0N/A * lookup path (parent chain) is: 0N/A * Messages_ja -> Messages 0N/A * the base name of the resource bundle, a fully 0N/A * qualified class name 0N/A * the locale for which a resource bundle is desired 0N/A * @return a <code>List</code> of candidate 0N/A * <code>Locale</code>s for the given <code>locale</code> 0N/A * @exception NullPointerException 0N/A * if <code>baseName</code> or <code>locale</code> is 2712N/A // Special handling for Norwegian 2712N/A // Insert a locale replacing "nb" with "no" for every list entry 2712N/A // Insert no_NO_NY, no_NO, no after nn 2712N/A // Special handling for Chinese 2712N/A // as bundle names (recommended for Java7+) 2712N/A // Supply region(country) for users who still package Chinese 2712N/A // bundles using old convension. 2712N/A // With script, after truncating variant, region and script, 2712N/A // start over without script. 2712N/A // Add root locale at the end 0N/A * Returns a <code>Locale</code> to be used as a fallback locale for 0N/A * further resource bundle searches by the 0N/A * <code>ResourceBundle.getBundle</code> factory method. This method 0N/A * is called from the factory method every time when no resulting 0N/A * resource bundle has been found for <code>baseName</code> and 0N/A * <code>locale</code>, where locale is either the parameter for 0N/A * <code>ResourceBundle.getBundle</code> or the previous fallback 0N/A * locale returned by this method. 0N/A * <p>The method returns <code>null</code> if no further fallback 0N/A * search is desired. 0N/A * <p>The default implementation returns the {@linkplain 0N/A * Locale#getDefault() default <code>Locale</code>} if the given 0N/A * <code>locale</code> isn't the default one. Otherwise, 0N/A * <code>null</code> is returned. 0N/A * the base name of the resource bundle, a fully 0N/A * qualified class name for which 0N/A * <code>ResourceBundle.getBundle</code> has been 0N/A * unable to find any resource bundles (except for the 0N/A * the <code>Locale</code> for which 0N/A * <code>ResourceBundle.getBundle</code> has been 0N/A * unable to find any resource bundles (except for the 0N/A * @return a <code>Locale</code> for the fallback search, 0N/A * or <code>null</code> if no further fallback search 0N/A * @exception NullPointerException 0N/A * if <code>baseName</code> or <code>locale</code> 0N/A * is <code>null</code> 0N/A * Instantiates a resource bundle for the given bundle name of the 0N/A * given format and locale, using the given class loader if 0N/A * necessary. This method returns <code>null</code> if there is no 0N/A * resource bundle available for the given parameters. If a resource 0N/A * bundle can't be instantiated due to an unexpected error, the 0N/A * error must be reported by throwing an <code>Error</code> or 0N/A * <code>Exception</code> rather than simply returning 0N/A * <code>null</code>. 0N/A * <p>If the <code>reload</code> flag is <code>true</code>, it 0N/A * indicates that this method is being called because the previously 0N/A * loaded resource bundle has expired. 0N/A * <p>The default implementation instantiates a 0N/A * <code>ResourceBundle</code> as follows. 0N/A * <li>The bundle name is obtained by calling {@link 0N/A * #toBundleName(String, Locale) toBundleName(baseName, 0N/A * <li>If <code>format</code> is <code>"java.class"</code>, the 0N/A * {@link Class} specified by the bundle name is loaded by calling 0N/A * {@link ClassLoader#loadClass(String)}. Then, a 0N/A * <code>ResourceBundle</code> is instantiated by calling {@link 0N/A * Class#newInstance()}. Note that the <code>reload</code> flag is 0N/A * ignored for loading class-based resource bundles in this default 0N/A * implementation.</li> 0N/A * {@link #toResourceName(String, String) toResourceName(bundlename, 0N/A * "properties")} is called to get the resource name. 0N/A * If <code>reload</code> is <code>true</code>, {@link 0N/A * ClassLoader#getResource(String) load.getResource} is called 0N/A * to get a {@link URL} for creating a {@link 0N/A * URLConnection}. This <code>URLConnection</code> is used to 0N/A * {@linkplain URLConnection#setUseCaches(boolean) disable the 0N/A * caches} of the underlying resource loading layers, 0N/A * and to {@linkplain URLConnection#getInputStream() get an 0N/A * <code>InputStream</code>}. 0N/A * Otherwise, {@link ClassLoader#getResourceAsStream(String) 0N/A * loader.getResourceAsStream} is called to get an {@link 0N/A * InputStream}. Then, a {@link 0N/A * PropertyResourceBundle} is constructed with the 0N/A * <code>InputStream</code>.</li> 0N/A * <li>If <code>format</code> is neither <code>"java.class"</code> 0N/A * <code>IllegalArgumentException</code> is thrown.</li> 0N/A * the base bundle name of the resource bundle, a fully 0N/A * qualified class name 0N/A * the locale for which the resource bundle should be 0N/A * the resource bundle format to be loaded 0N/A * the <code>ClassLoader</code> to use to load the bundle 0N/A * the flag to indicate bundle reloading; <code>true</code> 0N/A * if reloading an expired resource bundle, 0N/A * <code>false</code> otherwise 0N/A * @return the resource bundle instance, 0N/A * or <code>null</code> if none could be found. 0N/A * @exception NullPointerException 0N/A * if <code>bundleName</code>, <code>locale</code>, 0N/A * <code>format</code>, or <code>loader</code> is 0N/A * <code>null</code>, or if <code>null</code> is returned by 0N/A * {@link #toBundleName(String, Locale) toBundleName} 0N/A * @exception IllegalArgumentException 0N/A * if <code>format</code> is unknown, or if the resource 0N/A * found for the given parameters contains malformed data. 0N/A * @exception ClassCastException 0N/A * if the loaded class cannot be cast to <code>ResourceBundle</code> 0N/A * @exception IllegalAccessException 0N/A * if the class or its nullary constructor is not 0N/A * @exception InstantiationException 0N/A * if the instantiation of a class fails for some other 0N/A * @exception ExceptionInInitializerError 0N/A * if the initialization provoked by this method fails. 0N/A * @exception SecurityException 0N/A * If a security manager is present and creation of new 0N/A * instances is denied. See {@link Class#newInstance()} 0N/A * @exception IOException 0N/A * if an error occurred when reading resources using 0N/A * any I/O operations 0N/A // If the class isn't a ResourceBundle subclass, throw a 0N/A // ClassCastException. 0N/A +
" cannot be cast to ResourceBundle");
0N/A // Disable caches to get fresh data for 0N/A * Returns the time-to-live (TTL) value for resource bundles that 0N/A * are loaded under this 0N/A * <code>ResourceBundle.Control</code>. Positive time-to-live values 0N/A * specify the number of milliseconds a bundle can remain in the 0N/A * cache without being validated against the source data from which 0N/A * it was constructed. The value 0 indicates that a bundle must be 0N/A * validated each time it is retrieved from the cache. {@link 0N/A * #TTL_DONT_CACHE} specifies that loaded resource bundles are not 0N/A * put in the cache. {@link #TTL_NO_EXPIRATION_CONTROL} specifies 0N/A * that loaded resource bundles are put in the cache with no 0N/A * expiration control. 0N/A * <p>The expiration affects only the bundle loading process by the 0N/A * <code>ResourceBundle.getBundle</code> factory method. That is, 0N/A * if the factory method finds a resource bundle in the cache that 0N/A * has expired, the factory method calls the {@link 0N/A * #needsReload(String, Locale, String, ClassLoader, ResourceBundle, 0N/A * long) needsReload} method to determine whether the resource 0N/A * bundle needs to be reloaded. If <code>needsReload</code> returns 0N/A * <code>true</code>, the cached resource bundle instance is removed 0N/A * from the cache. Otherwise, the instance stays in the cache, 0N/A * updated with the new TTL value returned by this method. 0N/A * <p>All cached resource bundles are subject to removal from the 0N/A * cache due to memory constraints of the runtime environment. 0N/A * Returning a large positive value doesn't mean to lock loaded 0N/A * resource bundles in the cache. 0N/A * <p>The default implementation returns {@link #TTL_NO_EXPIRATION_CONTROL}. 0N/A * the base name of the resource bundle for which the 0N/A * expiration value is specified. 0N/A * the locale of the resource bundle for which the 0N/A * expiration value is specified. 0N/A * @return the time (0 or a positive millisecond offset from the 0N/A * cached time) to get loaded bundles expired in the cache, 0N/A * {@link #TTL_NO_EXPIRATION_CONTROL} to disable the 0N/A * expiration control, or {@link #TTL_DONT_CACHE} to disable 0N/A * @exception NullPointerException 0N/A * if <code>baseName</code> or <code>locale</code> is 0N/A * Determines if the expired <code>bundle</code> in the cache needs 0N/A * to be reloaded based on the loading time given by 0N/A * <code>loadTime</code> or some other criteria. The method returns 0N/A * <code>true</code> if reloading is required; <code>false</code> 0N/A * otherwise. <code>loadTime</code> is a millisecond offset since 0N/A * The calling <code>ResourceBundle.getBundle</code> factory method 0N/A * calls this method on the <code>ResourceBundle.Control</code> 0N/A * instance used for its current invocation, not on the instance 0N/A * used in the invocation that originally loaded the resource 0N/A * <p>The default implementation compares <code>loadTime</code> and 0N/A * the last modified time of the source data of the resource 0N/A * bundle. If it's determined that the source data has been modified 0N/A * since <code>loadTime</code>, <code>true</code> is 0N/A * returned. Otherwise, <code>false</code> is returned. This 0N/A * implementation assumes that the given <code>format</code> is the 0N/A * same string as its file suffix if it's not one of the default 0N/A * formats, <code>"java.class"</code> or 0N/A * the base bundle name of the resource bundle, a 0N/A * fully qualified class name 0N/A * the locale for which the resource bundle 0N/A * should be instantiated 0N/A * the resource bundle format to be loaded 0N/A * the <code>ClassLoader</code> to use to load the bundle 0N/A * the resource bundle instance that has been expired 0N/A * the time when <code>bundle</code> was loaded and put 0N/A * @return <code>true</code> if the expired bundle needs to be 0N/A * reloaded; <code>false</code> otherwise. 0N/A * @exception NullPointerException 0N/A * if <code>baseName</code>, <code>locale</code>, 0N/A * <code>format</code>, <code>loader</code>, or 0N/A * <code>bundle</code> is <code>null</code> 0N/A // disable caches to get the correct data 0N/A // ignore other exceptions 0N/A * Converts the given <code>baseName</code> and <code>locale</code> 0N/A * to the bundle name. This method is called from the default 0N/A * implementation of the {@link #newBundle(String, Locale, String, 0N/A * ClassLoader, boolean) newBundle} and {@link #needsReload(String, 0N/A * Locale, String, ClassLoader, ResourceBundle, long) needsReload} 0N/A * <p>This implementation returns the following value: 2712N/A * baseName + "_" + language + "_" + script + "_" + country + "_" + variant 2712N/A * where <code>language</code>, <code>script</code>, <code>country</code>, 2712N/A * and <code>variant</code> are the language, script, country, and variant 2712N/A * values of <code>locale</code>, respectively. Final component values that 2712N/A * are empty Strings are omitted along with the preceding '_'. When the 2712N/A * script is empty, the script value is ommitted along with the preceding '_'. 2712N/A * If all of the values are empty strings, then <code>baseName</code> 0N/A * <p>For example, if <code>baseName</code> is 0N/A * <code>"baseName"</code> and <code>locale</code> is 0N/A * <code>Locale("ja", "", "XX")</code>, then 0N/A * <code>"baseName_ja_ _XX"</code> is returned. If the given 0N/A * locale is <code>Locale("en")</code>, then 0N/A * <code>"baseName_en"</code> is returned. 0N/A * <p>Overriding this method allows applications to use different 0N/A * conventions in the organization and packaging of localized 0N/A * the base name of the resource bundle, a fully 0N/A * qualified class name 0N/A * the locale for which a resource bundle should be 0N/A * @return the bundle name for the resource bundle 0N/A * @exception NullPointerException 0N/A * if <code>baseName</code> or <code>locale</code> 0N/A * is <code>null</code> 0N/A * Converts the given <code>bundleName</code> to the form required 0N/A * by the {@link ClassLoader#getResource ClassLoader.getResource} 0N/A * method by replacing all occurrences of <code>'.'</code> in 0N/A * <code>bundleName</code> with <code>'/'</code> and appending a 0N/A * <code>'.'</code> and the given file <code>suffix</code>. For 0N/A * example, if <code>bundleName</code> is 0N/A * <code>"foo.bar.MyResources_ja_JP"</code> and <code>suffix</code> 0N/A * is <code>"properties"</code>, then 0N/A * the file type suffix 0N/A * @return the converted resource name 0N/A * @exception NullPointerException 0N/A * if <code>bundleName</code> or <code>suffix</code> 0N/A * is <code>null</code>