/*

 * Copyright 1996-2006 Sun Microsystems, Inc.  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.  Sun designates this

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

 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.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.JarURLConnection;

import java.net.URL;

import java.net.URLConnection;

import java.security.AccessController;

import java.security.PrivilegedAction;

import java.security.PrivilegedActionException;

import java.security.PrivilegedExceptionAction;

import java.util.concurrent.ConcurrentHashMap;

import java.util.concurrent.ConcurrentMap;

import java.util.jar.JarEntry;

/**

 *

 * 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 ConcurrentMap<CacheKey, BundleReference> cacheList

        = new ConcurrentHashMap<CacheKey, BundleReference>(INITIAL_CACHE_SIZE);

    /**

     * This ConcurrentMap is used to keep multiple threads from loading the

     * same bundle concurrently.  The table entries are <CacheKey, Thread>

     * where CacheKey is the key for the bundle that is under construction

     * and Thread is the thread that is constructing the bundle.

     * This list is manipulated in findBundleInCache and putBundleInCache.

     */

    private static final ConcurrentMap<CacheKey, Thread> underConstruction

        = new ConcurrentHashMap<CacheKey, Thread>();

    /**

     * 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;

    }

    /*

     * Automatic determination of the ClassLoader to be used to load

     * resources on behalf of the client.  N.B. The client is getLoader's

     * caller's caller.

     */

    private static ClassLoader getLoader() {

        Class[] stack = getClassContext();

        /* Magic number 2 identifies our caller's caller */

        Class c = stack[2];

        ClassLoader cl = (c == null) ? null : c.getClassLoader();

        if (cl == null) {

            // When the caller's loader is the boot class loader, cl is null

            // here. In that case, ClassLoader.getSystemClassLoader() may

            // return the same class loader that the application is

            // using. We therefore use a wrapper ClassLoader to create a

            // separate scope for bundles loaded on behalf of the Java

            // runtime so that these bundles cannot be returned from the

            // cache to the application (5048280).

            cl = RBClassLoader.INSTANCE;

        }

        return cl;

    }

    private static native Class[] getClassContext();

    /**

     * A wrapper of ClassLoader.getSystemClassLoader().

     */

    private static class RBClassLoader extends ClassLoader {

        private static final RBClassLoader INSTANCE = AccessController.doPrivileged(

                    new PrivilegedAction<RBClassLoader>() {

                        public RBClassLoader run() {

                            return new RBClassLoader();

                        }

                    });

        private static final ClassLoader loader = ClassLoader.getSystemClassLoader();

        private RBClassLoader() {

        }

        public Class<?> loadClass(String name) throws ClassNotFoundException {

            if (loader != null) {

                return loader.loadClass(name);

            }

            return Class.forName(name);

        }

        public URL getResource(String name) {

            if (loader != null) {

                return loader.getResource(name);

            }

            return ClassLoader.getSystemResource(name);

        }

        public InputStream getResourceAsStream(String name) {

            if (loader != null) {

                return loader.getResourceAsStream(name);

            }

            return ClassLoader.getSystemResourceAsStream(name);

        }

    }

    /**

     * 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;

        private LoaderReference loaderRef;

        // 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, ClassLoader loader) {

            this.name = baseName;