/*

 * Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

/*

 * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved

 * (C) Copyright IBM Corp. 1996 - 1999 - All Rights Reserved

 *

 * The original version of this source code and documentation

 * is copyrighted and owned by Taligent, Inc., a wholly-owned

 * subsidiary of IBM. These materials are provided under terms

 * of a License Agreement between Taligent and Sun. This technology

 * is protected by multiple US and International patents.

 *

 * This notice and attribution to Taligent may not be removed.

 * Taligent is a registered trademark of Taligent, Inc.

 *

 */

package java.util;

import java.io.IOException;

import java.io.InputStream;

import java.lang.ref.ReferenceQueue;

import java.lang.ref.SoftReference;

import java.lang.ref.WeakReference;

import java.net.URL;

/**

 *

 * Resource bundles contain locale-specific objects.  When your program needs a

 * locale-specific resource, a <code>String</code> for example, your program can

 * load it from the resource bundle that is appropriate for the current user's

 * locale. In this way, you can write program code that is largely independent

 * of the user's locale isolating most, if not all, of the locale-specific

 * information in resource bundles.

 *

 * <p>

 * This allows you to write programs that can:

 * <UL type=SQUARE>

 * <LI> be easily localized, or translated, into different languages

 * <LI> handle multiple locales at once

 * <LI> be easily modified later to support even more locales

 * </UL>

 *

 * <P>

 * Resource bundles belong to families whose members share a common base

 * name, but whose names also have additional components that identify

 * their locales. For example, the base name of a family of resource

 * bundles might be "MyResources". The family should have a default

 * resource bundle which simply has the same name as its family -

 * "MyResources" - and will be used as the bundle of last resort if a

 * specific locale is not supported. The family can then provide as

 * many locale-specific members as needed, for example a German one

 * named "MyResources_de".

 *

 * <P>

 * Each resource bundle in a family contains the same items, but the items have

 * been translated for the locale represented by that resource bundle.

 * For example, both "MyResources" and "MyResources_de" may have a

 * <code>String</code> that's used on a button for canceling operations.

 * In "MyResources" the <code>String</code> may contain "Cancel" and in

 * "MyResources_de" it may contain "Abbrechen".

 *

 * <P>

 * If there are different resources for different countries, you

 * can make specializations: for example, "MyResources_de_CH" contains objects for

 * the German language (de) in Switzerland (CH). If you want to only

 * modify some of the resources

 * in the specialization, you can do so.

 *

 * <P>

 * When your program needs a locale-specific object, it loads

 * the <code>ResourceBundle</code> class using the

 * {@link #getBundle(java.lang.String, java.util.Locale) getBundle}

 * method:

 * <blockquote>

 * <pre>

 * ResourceBundle myResources =

 *      ResourceBundle.getBundle("MyResources", currentLocale);

 * </pre>

 * </blockquote>

 *

 * <P>

 * Resource bundles contain key/value pairs. The keys uniquely

 * identify a locale-specific object in the bundle. Here's an

 * example of a <code>ListResourceBundle</code> that contains

 * two key/value pairs:

 * <blockquote>

 * <pre>

 * public class MyResources extends ListResourceBundle {

 *     protected Object[][] getContents() {

 *         return new Object[][] {

 *             // LOCALIZE THE SECOND STRING OF EACH ARRAY (e.g., "OK")

 *             {"OkKey", "OK"},

 *             {"CancelKey", "Cancel"},

 *             // END OF MATERIAL TO LOCALIZE

 *        };

 *     }

 * }

 * </pre>

 * </blockquote>

 * Keys are always <code>String</code>s.

 * In this example, the keys are "OkKey" and "CancelKey".

 * In the above example, the values

 * are also <code>String</code>s--"OK" and "Cancel"--but

 * they don't have to be. The values can be any type of object.

 *

 * <P>

 * You retrieve an object from resource bundle using the appropriate

 * getter method. Because "OkKey" and "CancelKey"

 * are both strings, you would use <code>getString</code> to retrieve them:

 * <blockquote>

 * <pre>

 * button1 = new Button(myResources.getString("OkKey"));

 * button2 = new Button(myResources.getString("CancelKey"));

 * </pre>

 * </blockquote>

 * The getter methods all require the key as an argument and return

 * the object if found. If the object is not found, the getter method

 * throws a <code>MissingResourceException</code>.

 *

 * <P>

 * Besides <code>getString</code>, <code>ResourceBundle</code> also provides

 * a method for getting string arrays, <code>getStringArray</code>,

 * as well as a generic <code>getObject</code> method for any other

 * type of object. When using <code>getObject</code>, you'll

 * have to cast the result to the appropriate type. For example:

 * <blockquote>

 * <pre>

 * int[] myIntegers = (int[]) myResources.getObject("intList");

 * </pre>

 * </blockquote>

 *

 * <P>

 * The Java Platform provides two subclasses of <code>ResourceBundle</code>,

 * <code>ListResourceBundle</code> and <code>PropertyResourceBundle</code>,

 * that provide a fairly simple way to create resources.

 * As you saw briefly in a previous example, <code>ListResourceBundle</code>

 * manages its resource as a list of key/value pairs.

 * <code>PropertyResourceBundle</code> uses a properties file to manage

 * its resources.

 *

 * <p>

 * If <code>ListResourceBundle</code> or <code>PropertyResourceBundle</code>

 * do not suit your needs, you can write your own <code>ResourceBundle</code>

 * subclass.  Your subclasses must override two methods: <code>handleGetObject</code>

 * and <code>getKeys()</code>.

 *

 * <h4>ResourceBundle.Control</h4>

 *

 * The {@link ResourceBundle.Control} class provides information necessary

 * to perform the bundle loading process by the <code>getBundle</code>

 * factory methods that take a <code>ResourceBundle.Control</code>

 * instance. You can implement your own subclass in order to enable

 * non-standard resource bundle formats, change the search strategy, or

 * define caching parameters. Refer to the descriptions of the class and the

 * {@link #getBundle(String, Locale, ClassLoader, Control) getBundle}

 * factory method for details.

 *

 * <h4>Cache Management</h4>

 *

 * Resource bundle instances created by the <code>getBundle</code> factory

 * methods are cached by default, and the factory methods return the same

 * resource bundle instance multiple times if it has been

 * cached. <code>getBundle</code> clients may clear the cache, manage the

 * lifetime of cached resource bundle instances using time-to-live values,

 * or specify not to cache resource bundle instances. Refer to the

 * descriptions of the {@linkplain #getBundle(String, Locale, ClassLoader,

 * Control) <code>getBundle</code> factory method}, {@link

 * #clearCache(ClassLoader) clearCache}, {@link

 * Control#getTimeToLive(String, Locale)

 * ResourceBundle.Control.getTimeToLive}, and {@link

 * Control#needsReload(String, Locale, String, ClassLoader, ResourceBundle,

 * long) ResourceBundle.Control.needsReload} for details.

 *

 * <h4>Example</h4>

 *

 * The following is a very simple example of a <code>ResourceBundle</code>

 * subclass, <code>MyResources</code>, that manages two resources (for a larger number of

 * resources you would probably use a <code>Map</code>).

 * Notice that you don't need to supply a value if

 * a "parent-level" <code>ResourceBundle</code> handles the same

 * key with the same value (as for the okKey below).

 * <blockquote>

 * <pre>

 * // default (English language, United States)

 * public class MyResources extends ResourceBundle {

 *     public Object handleGetObject(String key) {

 *         if (key.equals("okKey")) return "Ok";

 *         if (key.equals("cancelKey")) return "Cancel";

 *         return null;

 *     }

 *

 *     public Enumeration<String> getKeys() {

 *         return Collections.enumeration(keySet());

 *     }

 *

 *     // Overrides handleKeySet() so that the getKeys() implementation

 *     // can rely on the keySet() value.

 *     protected Set<String> handleKeySet() {

 *         return new HashSet<String>(Arrays.asList("okKey", "cancelKey"));

 *     }

 * }

 *

 * // German language

 * public class MyResources_de extends MyResources {

 *     public Object handleGetObject(String key) {

 *         // don't need okKey, since parent level handles it.

 *         if (key.equals("cancelKey")) return "Abbrechen";

 *         return null;

 *     }

 *

 *     protected Set<String> handleKeySet() {

 *         return new HashSet<String>(Arrays.asList("cancelKey"));

 *     }

 * }

 * </pre>

 * </blockquote>

 * You do not have to restrict yourself to using a single family of

 * <code>ResourceBundle</code>s. For example, you could have a set of bundles for

 * exception messages, <code>ExceptionResources</code>

 * (<code>ExceptionResources_fr</code>, <code>ExceptionResources_de</code>, ...),

 * and one for widgets, <code>WidgetResource</code> (<code>WidgetResources_fr</code>,

 * <code>WidgetResources_de</code>, ...); breaking up the resources however you like.

 *

 * @see ListResourceBundle

 * @see PropertyResourceBundle

 * @see MissingResourceException

 * @since JDK1.1

 */

public abstract class ResourceBundle {

    /** initial size of the bundle cache */

    private static final int INITIAL_CACHE_SIZE = 32;

    /** constant indicating that no resource bundle exists */

    private static final ResourceBundle NONEXISTENT_BUNDLE = new ResourceBundle() {

            public Enumeration<String> getKeys() { return null; }

            protected Object handleGetObject(String key) { return null; }

            public String toString() { return "NONEXISTENT_BUNDLE"; }

        };

    /**

     * The cache is a map from cache keys (with bundle base name, locale, and

     * class loader) to either a resource bundle or NONEXISTENT_BUNDLE wrapped by a

     * BundleReference.

     *

     * The cache is a ConcurrentMap, allowing the cache to be searched

     * concurrently by multiple threads.  This will also allow the cache keys

     * to be reclaimed along with the ClassLoaders they reference.

     *

     * This variable would be better named "cache", but we keep the old

     * name for compatibility with some workarounds for bug 4212439.

     */

    private static final Map<CacheKey, BundleReference> cacheList

        = new HashMap<>(INITIAL_CACHE_SIZE);

    /**

     * Queue for reference objects referring to class loaders or bundles.

     */

    private static final ReferenceQueue referenceQueue = new ReferenceQueue();

    /**

     * The parent bundle of this bundle.

     * The parent bundle is searched by {@link #getObject getObject}

     * when this bundle does not contain a particular resource.

     */

    protected ResourceBundle parent = null;

    /**

     * The locale for this bundle.

     */

    private Locale locale = null;

    /**

     * The base bundle name for this bundle.

     */

    private String name;

    /**

     * The flag indicating this bundle has expired in the cache.

     */

    private volatile boolean expired;

    /**

     * The back link to the cache key. null if this bundle isn't in

     * the cache (yet) or has expired.

     */

    private volatile CacheKey cacheKey;

    /**

     * A Set of the keys contained only in this ResourceBundle.

     */

    private volatile Set<String> keySet;

    /**

     * Sole constructor.  (For invocation by subclass constructors, typically

     * implicit.)

     */

    public ResourceBundle() {

    }

    /**

     * Gets a string for the given key from this resource bundle or one of its parents.

     * Calling this method is equivalent to calling

     * <blockquote>

     * <code>(String) {@link #getObject(java.lang.String) getObject}(key)</code>.

     * </blockquote>

     *

     * @param key the key for the desired string

     * @exception NullPointerException if <code>key</code> is <code>null</code>

     * @exception MissingResourceException if no object for the given key can be found

     * @exception ClassCastException if the object found for the given key is not a string

     * @return the string for the given key

     */

    public final String getString(String key) {

        return (String) getObject(key);

    }

    /**

     * Gets a string array for the given key from this resource bundle or one of its parents.

     * Calling this method is equivalent to calling

     * <blockquote>

     * <code>(String[]) {@link #getObject(java.lang.String) getObject}(key)</code>.

     * </blockquote>

     *

     * @param key the key for the desired string array

     * @exception NullPointerException if <code>key</code> is <code>null</code>

     * @exception MissingResourceException if no object for the given key can be found

     * @exception ClassCastException if the object found for the given key is not a string array

     * @return the string array for the given key

     */

    public final String[] getStringArray(String key) {

        return (String[]) getObject(key);

    }

    /**

     * Gets an object for the given key from this resource bundle or one of its parents.

     * This method first tries to obtain the object from this resource bundle using

     * {@link #handleGetObject(java.lang.String) handleGetObject}.

     * If not successful, and the parent resource bundle is not null,

     * it calls the parent's <code>getObject</code> method.

     * If still not successful, it throws a MissingResourceException.

     *

     * @param key the key for the desired object

     * @exception NullPointerException if <code>key</code> is <code>null</code>

     * @exception MissingResourceException if no object for the given key can be found

     * @return the object for the given key

     */

    public final Object getObject(String key) {

        Object obj = handleGetObject(key);

        if (obj == null) {

            if (parent != null) {

                obj = parent.getObject(key);

            }

            if (obj == null)

                throw new MissingResourceException("Can't find resource for bundle "

                                                   +this.getClass().getName()

                                                   +", key "+key,

                                                   this.getClass().getName(),

                                                   key);

        }

        return obj;

    }

    /**

     * Returns the locale of this resource bundle. This method can be used after a

     * call to getBundle() to determine whether the resource bundle returned really

     * corresponds to the requested locale or is a fallback.

     *

     * @return the locale of this resource bundle

     */

    public Locale getLocale() {

        return locale;

    }

    /**

     * Sets the parent bundle of this bundle.

     * The parent bundle is searched by {@link #getObject getObject}

     * when this bundle does not contain a particular resource.

     *

     * @param parent this bundle's parent bundle.

     */

    protected void setParent(ResourceBundle parent) {

        assert parent != NONEXISTENT_BUNDLE;

        this.parent = parent;

    }

    /**

     * Key used for cached resource bundles.  The key checks the base

     * name, the locale, and the class loader to determine if the

     * resource is a match to the requested one. The loader may be

     * null, but the base name and the locale must have a non-null

     * value.

     */

    private static final class CacheKey implements Cloneable {

        // These three are the actual keys for lookup in Map.

        private String name;

        private Locale locale;

        // bundle format which is necessary for calling

        // Control.needsReload().

        private String format;

        // These time values are in CacheKey so that NONEXISTENT_BUNDLE

        // doesn't need to be cloned for caching.

        // The time when the bundle has been loaded

        private volatile long loadTime;

        // The time when the bundle expires in the cache, or either

        // Control.TTL_DONT_CACHE or Control.TTL_NO_EXPIRATION_CONTROL.

        private volatile long expirationTime;

        // Placeholder for an error report by a Throwable

        private Throwable cause;

        // Hash code value cache to avoid recalculating the hash code

        // of this instance.

        private int hashCodeCache;

        CacheKey(String baseName, Locale locale) {

            this.name = baseName;

            this.locale = locale;

            calculateHashCode();

        }

        String getName() {

            return name;

        }

        CacheKey setName(String baseName) {

            if (!this.name.equals(baseName)) {

                this.name = baseName;

                calculateHashCode();

            }

            return this;

        }

        Locale getLocale() {

            return locale;

        }

        CacheKey setLocale(Locale locale) {

            if (!this.locale.equals(locale)) {

                this.locale = locale;

                calculateHashCode();

            }

            return this;

        }

        public boolean equals(Object other) {

            if (this == other) {

                return true;

            }

            try {

                final CacheKey otherEntry = (CacheKey)other;

                //quick check to see if they are not equal

                if (hashCodeCache != otherEntry.hashCodeCache) {

                    return false;

                }

                //are the names the same?

                if (!name.equals(otherEntry.name)) {

                    return false;

                }

                // are the locales the same?

                if (!locale.equals(otherEntry.locale)) {

                    return false;

                }

                return true;

            } catch (NullPointerException e) {

            } catch (ClassCastException e) {

            }

            return false;

        }

        public int hashCode() {

            return hashCodeCache;

        }

        private void calculateHashCode() {

            hashCodeCache = name.hashCode() << 3;

            hashCodeCache ^= locale.hashCode();

        }

        public Object clone() {

            try {

                CacheKey clone = (CacheKey) super.clone();

                // Clear the reference to a Throwable

                clone.cause = null;

                return clone;

            } catch (CloneNotSupportedException e) {

                //this should never happen

                throw new InternalError();

            }

        }

        String getFormat() {

            return format;

        }

        void setFormat(String format) {

            this.format = format;

        }

        private void setCause(Throwable cause) {

            if (this.cause == null) {

                this.cause = cause;

            } else {

                // Override the cause if the previous one is

                // ClassNotFoundException.

                if (this.cause instanceof ClassNotFoundException) {

                    this.cause = cause;

                }

            }

        }

        private Throwable getCause() {

            return cause;

        }

        public String toString() {

            String l = locale.toString();

            if (l.length() == 0) {

                if (locale.getVariant().length() != 0) {

                    l = "__" + locale.getVariant();

                } else {

                    l = "\"\"";

                }

            }

            return "CacheKey[" + name + ", lc=" + l

                + "(format=" + format + ")]";

        }

    }

    /**

     * The common interface to get a CacheKey in LoaderReference and

     * BundleReference.

     */

    private static interface CacheKeyReference {

        public CacheKey getCacheKey();

    }

    /**

     * References to bundles are soft references so that they can be garbage

     * collected when they have no hard references.

     */

    private static final class BundleReference extends SoftReference<ResourceBundle>

                                               implements CacheKeyReference {

        private CacheKey cacheKey;

        BundleReference(ResourceBundle referent, ReferenceQueue q, CacheKey key) {

            super(referent, q);

            cacheKey = key;

        }

        public CacheKey getCacheKey() {

            return cacheKey;

        }

    }

    /**

     * Gets a resource bundle using the specified base name, the default locale,

     * and the caller's class loader. Calling this method is equivalent to calling

     * <blockquote>

     * <code>getBundle(baseName, Locale.getDefault(), this.getClass().getClassLoader())</code>,

     * </blockquote>

     * except that <code>getClassLoader()</code> is run with the security

     * privileges of <code>ResourceBundle</code>.

     * See {@link #getBundle(String, Locale, ClassLoader) getBundle}

     * for a complete description of the search and instantiation strategy.

     *

     * @param baseName the base name of the resource bundle, a fully qualified class name

     * @exception java.lang.NullPointerException

     *     if <code>baseName</code> is <code>null</code>

     * @exception MissingResourceException

     *     if no resource bundle for the specified base name can be found

     * @return a resource bundle for the given base name and the default locale

     */

    public static final ResourceBundle getBundle(String baseName)

    {

        return getBundleImpl(baseName, Locale.getDefault(),

                             Control.INSTANCE);

    }

    /**

     * Returns a resource bundle using the specified base name, the

     * default locale and the specified control. Calling this method

     * is equivalent to calling

     * <pre>

     * getBundle(baseName, Locale.getDefault(),

     *           this.getClass().getClassLoader(), control),

     * </pre>

     * except that <code>getClassLoader()</code> is run with the security

     * privileges of <code>ResourceBundle</code>.  See {@link

     * #getBundle(String, Locale, ClassLoader, Control) getBundle} for the

     * complete description of the resource bundle loading process with a

     * <code>ResourceBundle.Control</code>.

     *

     * @param baseName

     *        the base name of the resource bundle, a fully qualified class

     *        name

     * @param control

     *        the control which gives information for the resource bundle

     *        loading process

     * @return a resource bundle for the given base name and the default

     *        locale

     * @exception NullPointerException

     *        if <code>baseName</code> or <code>control</code> is

     *        <code>null</code>

     * @exception MissingResourceException

     *        if no resource bundle for the specified base name can be found

     * @exception IllegalArgumentException

     *        if the given <code>control</code> doesn't perform properly

     *        (e.g., <code>control.getCandidateLocales</code> returns null.)

     *        Note that validation of <code>control</code> is performed as

     *        needed.

     * @since 1.6

     */

    public static final ResourceBundle getBundle(String baseName,

                                                 Control control) {

        return getBundleImpl(baseName, Locale.getDefault(),

                             /* must determine loader here, else we break stack invariant */

                             control);

    }

    /**

     * Gets a resource bundle using the specified base name and locale,

     * and the caller's class loader. Calling this method is equivalent to calling

     * <blockquote>

     * <code>getBundle(baseName, locale, this.getClass().getClassLoader())</code>,

     * </blockquote>

     * except that <code>getClassLoader()</code> is run with the security

     * privileges of <code>ResourceBundle</code>.

     * See {@link #getBundle(String, Locale, ClassLoader) getBundle}

     * for a complete description of the search and instantiation strategy.

     *

     * @param baseName

     *        the base name of the resource bundle, a fully qualified class name

     * @param locale

     *        the locale for which a resource bundle is desired

     * @exception NullPointerException

     *        if <code>baseName</code> or <code>locale</code> is <code>null</code>

     * @exception MissingResourceException

     *        if no resource bundle for the specified base name can be found

     * @return a resource bundle for the given base name and locale

     */

    public static final ResourceBundle getBundle(String baseName,

                                                 Locale locale)

    {

        return getBundleImpl(baseName, locale,

                             /* must determine loader here, else we break stack invariant */

                             Control.INSTANCE);

    }

    /**

     * Returns a resource bundle using the specified base name, target

     * locale and control, and the caller's class loader. Calling this

     * method is equivalent to calling

     * <pre>

     * getBundle(baseName, targetLocale, this.getClass().getClassLoader(),

     *           control),

     * </pre>

     * except that <code>getClassLoader()</code> is run with the security

     * privileges of <code>ResourceBundle</code>.  See {@link

     * #getBundle(String, Locale, ClassLoader, Control) getBundle} for the

     * complete description of the resource bundle loading process with a

     * <code>ResourceBundle.Control</code>.

     *

     * @param baseName

     *        the base name of the resource bundle, a fully qualified

     *        class name

     * @param targetLocale

     *        the locale for which a resource bundle is desired

     * @param control

     *        the control which gives information for the resource

     *        bundle loading process

     * @return a resource bundle for the given base name and a

     *        <code>Locale</code> in <code>locales</code>

     * @exception NullPointerException

     *        if <code>baseName</code>, <code>locales</code> or

     *        <code>control</code> is <code>null</code>

     * @exception MissingResourceException

     *        if no resource bundle for the specified base name in any

     *        of the <code>locales</code> can be found.

     * @exception IllegalArgumentException

     *        if the given <code>control</code> doesn't perform properly

     *        (e.g., <code>control.getCandidateLocales</code> returns null.)

     *        Note that validation of <code>control</code> is performed as

     *        needed.

     * @since 1.6

     */

    public static final ResourceBundle getBundle(String baseName, Locale targetLocale,

                                                 Control control) {

        return getBundleImpl(baseName, targetLocale,

                             /* must determine loader here, else we break stack invariant */

                             control);

    }

    /**

     * Gets a resource bundle using the specified base name, locale, and class

     * loader.

     *

     * <p><a name="default_behavior"/>This method behaves the same as calling

     * {@link #getBundle(String, Locale, ClassLoader, Control)} passing a

     * default instance of {@link Control}. The following describes this behavior.

     *

     * <p><code>getBundle</code> uses the base name, the specified locale, and

     * the default locale (obtained from {@link java.util.Locale#getDefault()

     * Locale.getDefault}) to generate a sequence of <a

     * name="candidates"><em>candidate bundle names</em></a>.  If the specified

     * locale's language, script, country, and variant are all empty strings,

     * then the base name is the only candidate bundle name.  Otherwise, a list

     * of candidate locales is generated from the attribute values of the

     * specified locale (language, script, country and variant) and appended to

     * the base name.  Typically, this will look like the following:

     *

     * <pre>

     *     baseName + "_" + language + "_" + script + "_" + country + "_" + variant

     *     baseName + "_" + language + "_" + script + "_" + country

     *     baseName + "_" + language + "_" + script

     *     baseName + "_" + language + "_" + country + "_" + variant

     *     baseName + "_" + language + "_" + country

     *     baseName + "_" + language

     * </pre>

     *

     * <p>Candidate bundle names where the final component is an empty string

     * are omitted, along with the underscore.  For example, if country is an

     * empty string, the second and the fifth candidate bundle names above

     * would be omitted.  Also, if script is an empty string, the candidate names

     * including script are omitted.  For example, a locale with language "de"

     * and variant "JAVA" will produce candidate names with base name

     * "MyResource" below.

     *

     * <pre>

     *     MyResource_de__JAVA

     *     MyResource_de

     * </pre>

     *

     * In the case that the variant contains one or more underscores ('_'), a

     * sequence of bundle names generated by truncating the last underscore and

     * the part following it is inserted after a candidate bundle name with the

     * original variant.  For example, for a locale with language "en", script

     * "Latn, country "US" and variant "WINDOWS_VISTA", and bundle base name

     * "MyResource", the list of candidate bundle names below is generated:

     *

     * <pre>

     * MyResource_en_Latn_US_WINDOWS_VISTA

     * MyResource_en_Latn_US_WINDOWS

     * MyResource_en_Latn_US

     * MyResource_en_Latn

     * MyResource_en_US_WINDOWS_VISTA

     * MyResource_en_US_WINDOWS

     * MyResource_en_US

     * MyResource_en

     * </pre>

     *

     * <blockquote><b>Note:</b> For some <code>Locale</code>s, the list of

     * candidate bundle names contains extra names, or the order of bundle names

     * is slightly modified.  See the description of the default implementation

     * of {@link Control#getCandidateLocales(String, Locale)

     * getCandidateLocales} for details.</blockquote>

     *

     * <p><code>getBundle</code> then iterates over the candidate bundle names

     * to find the first one for which it can <em>instantiate</em> an actual

     * resource bundle. It uses the default controls' {@link Control#getFormats

     * getFormats} method, which generates two bundle names for each generated

     * name, the first a class name and the second a properties file name. For

     * each candidate bundle name, it attempts to create a resource bundle:

     *

     * <ul><li>First, it attempts to load a class using the generated class name.

     * If such a class can be found and loaded using the specified class

     * loader, is assignment compatible with ResourceBundle, is accessible from

     * ResourceBundle, and can be instantiated, <code>getBundle</code> creates a

     * new instance of this class and uses it as the <em>result resource

     * bundle</em>.

     *

     * <li>Otherwise, <code>getBundle</code> attempts to locate a property

     * resource file using the generated properties file name.  It generates a

     * path name from the candidate bundle name by replacing all "." characters

     * with "/" and appending the string ".properties".  It attempts to find a

     * "resource" with this name using {@link

     * java.lang.ClassLoader#getResource(java.lang.String)

     * ClassLoader.getResource}.  (Note that a "resource" in the sense of

     * <code>getResource</code> has nothing to do with the contents of a

     * resource bundle, it is just a container of data, such as a file.)  If it

     * finds a "resource", it attempts to create a new {@link

     * PropertyResourceBundle} instance from its contents.  If successful, this

     * instance becomes the <em>result resource bundle</em>.  </ul>

     *

     * <p>This continues until a result resource bundle is instantiated or the

     * list of candidate bundle names is exhausted.  If no matching resource

     * bundle is found, the default control's {@link Control#getFallbackLocale

     * getFallbackLocale} method is called, which returns the current default

     * locale.  A new sequence of candidate locale names is generated using this

     * locale and and searched again, as above.

     *

     * <p>If still no result bundle is found, the base name alone is looked up. If

     * this still fails, a <code>MissingResourceException</code> is thrown.

     *

     * <p><a name="parent_chain"/> Once a result resource bundle has been found,

     * its <em>parent chain</em> is instantiated.  If the result bundle already

     * has a parent (perhaps because it was returned from a cache) the chain is

     * complete.

     *

     * <p>Otherwise, <code>getBundle</code> examines the remainder of the

     * candidate locale list that was used during the pass that generated the

     * result resource bundle.  (As before, candidate bundle names where the

     * final component is an empty string are omitted.)  When it comes to the

     * end of the candidate list, it tries the plain bundle name.  With each of the

     * candidate bundle names it attempts to instantiate a resource bundle (first

     * looking for a class and then a properties file, as described above).

     *

     * <p>Whenever it succeeds, it calls the previously instantiated resource

     * bundle's {@link #setParent(java.util.ResourceBundle) setParent} method

     * with the new resource bundle.  This continues until the list of names

     * is exhausted or the current bundle already has a non-null parent.

     *

     * <p>Once the parent chain is complete, the bundle is returned.

     *

     * <p><b>Note:</b> <code>getBundle</code> caches instantiated resource

     * bundles and might return the same resource bundle instance multiple times.

     *

     * <p><b>Note:</b>The <code>baseName</code> argument should be a fully

     * qualified class name. However, for compatibility with earlier versions,

     * Sun's Java SE Runtime Environments do not verify this, and so it is

     * possible to access <code>PropertyResourceBundle</code>s by specifying a

     * path name (using "/") instead of a fully qualified class name (using

     * ".").

     *

     * <p><a name="default_behavior_example"/>

     * <strong>Example:</strong>

     * <p>

     * The following class and property files are provided:

     * <pre>

     *     MyResources.class

     *     MyResources.properties

     *     MyResources_fr.properties

     *     MyResources_fr_CH.class

     *     MyResources_fr_CH.properties

     *     MyResources_en.properties

     *     MyResources_es_ES.class

     * </pre>

     *

     * The contents of all files are valid (that is, public non-abstract

     * subclasses of <code>ResourceBundle</code> for the ".class" files,

     * syntactically correct ".properties" files).  The default locale is

     * <code>Locale("en", "GB")</code>.

     *

     * <p>Calling <code>getBundle</code> with the locale arguments below will

     * instantiate resource bundles as follows:

     *

     * <table>

     * <tr><td>Locale("fr", "CH")</td><td>MyResources_fr_CH.class, parent MyResources_fr.properties, parent MyResources.class</td></tr>

     * <tr><td>Locale("fr", "FR")</td><td>MyResources_fr.properties, parent MyResources.class</td></tr>

     * <tr><td>Locale("de", "DE")</td><td>MyResources_en.properties, parent MyResources.class</td></tr>

     * <tr><td>Locale("en", "US")</td><td>MyResources_en.properties, parent MyResources.class</td></tr>

     * <tr><td>Locale("es", "ES")</td><td>MyResources_es_ES.class, parent MyResources.class</td></tr>

     * </table>

     *

     * <p>The file MyResources_fr_CH.properties is never used because it is

     * hidden by the MyResources_fr_CH.class. Likewise, MyResources.properties

     * is also hidden by MyResources.class.

     *

     * @param baseName the base name of the resource bundle, a fully qualified class name

     * @param locale the locale for which a resource bundle is desired

     * @param loader the class loader from which to load the resource bundle

     * @return a resource bundle for the given base name and locale

     * @exception java.lang.NullPointerException

     *        if <code>baseName</code>, <code>locale</code>, or <code>loader</code> is <code>null</code>

     * @exception MissingResourceException

     *        if no resource bundle for the specified base name can be found

     * @since 1.2

     */

    public static ResourceBundle getBundle(String baseName, Locale locale,

                                           ClassLoader loader)

    {

        if (loader == null) {

            throw new NullPointerException();

        }

        return getBundleImpl(baseName, locale, Control.INSTANCE);

    }

    /**

     * Returns a resource bundle using the specified base name, target

     * locale, class loader and control. Unlike the {@linkplain

     * #getBundle(String, Locale, ClassLoader) <code>getBundle</code>

     * factory methods with no <code>control</code> argument}, the given

     * <code>control</code> specifies how to locate and instantiate resource

     * bundles. Conceptually, the bundle loading process with the given

     * <code>control</code> is performed in the following steps.

     *

     * <p>

     * <ol>

     * <li>This factory method looks up the resource bundle in the cache for

     * the specified <code>baseName</code>, <code>targetLocale</code> and

     * <code>loader</code>.  If the requested resource bundle instance is

     * found in the cache and the time-to-live periods of the instance and

     * all of its parent instances have not expired, the instance is returned

     * to the caller. Otherwise, this factory method proceeds with the

     * loading process below.</li>

     *

     * <li>The {@link ResourceBundle.Control#getFormats(String)

     * control.getFormats} method is called to get resource bundle formats

     * to produce bundle or resource names. The strings

     * <code>"java.class"</code> and <code>"java.properties"</code>

     * designate class-based and {@linkplain PropertyResourceBundle

     * property}-based resource bundles, respectively. Other strings

     * starting with <code>"java."</code> are reserved for future extensions

     * and must not be used for application-defined formats. Other strings

     * designate application-defined formats.</li>

     *

     * <li>The {@link ResourceBundle.Control#getCandidateLocales(String,

     * Locale) control.getCandidateLocales} method is called with the target

     * locale to get a list of <em>candidate <code>Locale</code>s</em> for

     * which resource bundles are searched.</li>

     *

     * <li>The {@link ResourceBundle.Control#newBundle(String, Locale,

     * String, ClassLoader, boolean) control.newBundle} method is called to

     * instantiate a <code>ResourceBundle</code> for the base bundle name, a

     * candidate locale, and a format. (Refer to the note on the cache

     * lookup below.) This step is iterated over all combinations of the

     * candidate locales and formats until the <code>newBundle</code> method

     * returns a <code>ResourceBundle</code> instance or the iteration has

     * used up all the combinations. For example, if the candidate locales

     * are <code>Locale("de", "DE")</code>, <code>Locale("de")</code> and

     * <code>Locale("")</code> and the formats are <code>"java.class"</code>

     * and <code>"java.properties"</code>, then the following is the

     * sequence of locale-format combinations to be used to call

     * <code>control.newBundle</code>.

     *

     * <table style="width: 50%; text-align: left; margin-left: 40px;"

     *  border="0" cellpadding="2" cellspacing="2">

     * <tbody><code>

     * <tr>

     * <td

     * style="vertical-align: top; text-align: left; font-weight: bold; width: 50%;">Locale<br>

     * </td>

     * <td

     * style="vertical-align: top; text-align: left; font-weight: bold; width: 50%;">format<br>

     * </td>

     * </tr>

     * <tr>

     * <td style="vertical-align: top; width: 50%;">Locale("de", "DE")<br>

     * </td>

     * <td style="vertical-align: top; width: 50%;">java.class<br>

     * </td>

     * </tr>

     * <tr>

     * <td style="vertical-align: top; width: 50%;">Locale("de", "DE")</td>

     * <td style="vertical-align: top; width: 50%;">java.properties<br>

     * </td>

     * </tr>

     * <tr>

     * <td style="vertical-align: top; width: 50%;">Locale("de")</td>

     * <td style="vertical-align: top; width: 50%;">java.class</td>

     * </tr>

     * <tr>

     * <td style="vertical-align: top; width: 50%;">Locale("de")</td>

     * <td style="vertical-align: top; width: 50%;">java.properties</td>

     * </tr>

     * <tr>

     * <td style="vertical-align: top; width: 50%;">Locale("")<br>

     * </td>

     * <td style="vertical-align: top; width: 50%;">java.class</td>

     * </tr>

     * <tr>

     * <td style="vertical-align: top; width: 50%;">Locale("")</td>

     * <td style="vertical-align: top; width: 50%;">java.properties</td>

     * </tr>