/*

 * Copyright (c) 1996, 2017, 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.io.UncheckedIOException;

import java.lang.ref.Reference;

import java.lang.ref.ReferenceQueue;

import java.lang.ref.SoftReference;

import java.lang.ref.WeakReference;

import java.lang.reflect.Constructor;

import java.lang.reflect.InvocationTargetException;

import java.lang.reflect.Modifier;

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;

import java.util.spi.ResourceBundleControlProvider;

import java.util.spi.ResourceBundleProvider;

import java.util.stream.Collectors;

import java.util.stream.Stream;

import jdk.internal.loader.BootLoader;

import jdk.internal.misc.JavaUtilResourceBundleAccess;

import jdk.internal.misc.SharedSecrets;

import jdk.internal.reflect.CallerSensitive;

import jdk.internal.reflect.Reflection;

import sun.security.action.GetPropertyAction;

import sun.util.locale.BaseLocale;

import sun.util.locale.LocaleObjectCache;

import static sun.security.util.SecurityConstants.GET_CLASSLOADER_PERMISSION;

/**

 *

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

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

 *

 * <p>

 * The implementation of a {@code ResourceBundle} subclass must be thread-safe

 * if it's simultaneously used by multiple threads. The default implementations

 * of the non-abstract methods in this class, and the methods in the direct

 * known concrete subclasses {@code ListResourceBundle} and

 * {@code PropertyResourceBundle} are thread-safe.

 *

 * <h3><a name="bundleprovider">Resource Bundles in Named Modules</a></h3>

 *

 * When resource bundles are deployed in named modules, the following

 * module-specific requirements and restrictions are applied.

 *

 * <ul>

 * <li>Code in a named module that calls {@link #getBundle(String, Locale)}

 * will locate resource bundles in the caller's module (<em>caller module</em>).</li>

 * <li>If resource bundles are deployed in named modules separate from

 * the caller module, those resource bundles need to be loaded from service

 * providers of {@link ResourceBundleProvider}. The caller module must declare

 * "{@code uses}" and the service interface name is the concatenation of the

 * base name of the bundles and the string "{@code Provider}". The

 * <em>bundle provider modules</em> containing resource bundles must

 * declare "{@code provides}" with the service interface name and

 * its implementation class name. For example, if the base name is

 * "{@code com.example.app.MyResources}", the caller module must declare

 * "{@code uses com.example.app.MyResourcesProvider;}" and a module containing resource

 * bundles must declare "{@code provides com.example.app.MyResourcesProvider

 * with com.example.app.internal.MyResourcesProviderImpl;}"

 * where {@code com.example.app.internal.MyResourcesProviderImpl} is an

 * implementation class of {@code com.example.app.MyResourcesProvider}.</li>

 * <li>If you want to use non-standard formats in named modules, such as XML,

 * {@link ResourceBundleProvider} needs to be used.</li>

 * <li>The {@code getBundle} method with a {@code ClassLoader} may not be able to

 * find resource bundles using the given {@code ClassLoader} in named modules.

 * The {@code getBundle} method with a {@code Module} can be used, instead.</li>

 * <li>{@code ResourceBundle.Control} is <em>not</em> supported in named modules.

 * If the {@code getBundle} method with a {@code ResourceBundle.Control} is called

 * in a named module, the method will throw an {@code UnsupportedOperationException}.

 * Any service providers of {@link ResourceBundleControlProvider} are ignored in

 * named modules.

 * </li>

 * </ul>

 *

 * <h3><a name="RBP_support">ResourceBundleProvider Service Providers</a></h3>

 *

 * The {@code getBundle} factory methods load service providers of

 * {@link ResourceBundleProvider}, if available, using {@link ServiceLoader}.

 * The service type is designated by {@code basename+"Provider"}. For

 * example, if the base name is "{@code com.example.app.MyResources}", the service

 * type is {@code com.example.app.MyResourcesProvider}.

 * <p>

 * In named modules, the loaded service providers for the given base name are

 * used to load resource bundles. If no service provider is available, or if

 * none of the service providers returns a resource bundle and the caller module

 * doesn't have its own service provider, the {@code getBundle} factory method

 * searches for resource bundles that are local in the caller module and that

 * are visible to the class loader of the caller module.  The resource bundle

 * formats for local module searching are "java.class" and "java.properties".

 *

 * <h3>ResourceBundle.Control</h3>

 *

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

 *

 * <p><a name="modify_default_behavior">For the {@code getBundle} factory</a>

 * methods that take no {@link Control} instance, their <a

 * href="#default_behavior"> default behavior</a> of resource bundle loading

 * can be modified with custom {@link

 * ResourceBundleControlProvider} implementations.

 * If any of the

 * providers provides a {@link Control} for the given base name, that {@link

 * Control} will be used instead of the default {@link Control}. If there is

 * more than one service provider for supporting the same base name,

 * the first one returned from {@link ServiceLoader} will be used.

 * A custom {@link Control} implementation is ignored by named modules.

 *

 * <h3>Cache Management</h3>

 *

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

 *

 * <h3>Example</h3>

 *

 * 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

 * @see ResourceBundleProvider

 * @since 1.1

 * @revised 9

 * @spec JPMS

 */

public abstract class ResourceBundle {

    /** initial size of the bundle cache */

    private static final int INITIAL_CACHE_SIZE = 32;

    static {

        SharedSecrets.setJavaUtilResourceBundleAccess(

            new JavaUtilResourceBundleAccess() {

                @Override

                public void setParent(ResourceBundle bundle,

                                      ResourceBundle parent) {

                    bundle.setParent(parent);

                }

                @Override

                public ResourceBundle getParent(ResourceBundle bundle) {

                    return bundle.parent;

                }

                @Override

                public void setLocale(ResourceBundle bundle, Locale locale) {

                    bundle.locale = locale;

                }

                @Override

                public void setName(ResourceBundle bundle, String name) {

                    bundle.name = name;

                }

                @Override

                public ResourceBundle getBundle(String baseName, Locale locale, Module module) {

                    // use the given module as the caller to bypass the access check

                    return getBundleImpl(module, module,

                                         baseName, locale,

                                         getDefaultControl(module, baseName));

                }

                @Override

                public ResourceBundle newResourceBundle(Class<? extends ResourceBundle> bundleClass) {

                    return ResourceBundleProviderHelper.newResourceBundle(bundleClass);

                }

            });

    }

    /** 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<>(INITIAL_CACHE_SIZE);

    /**

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

     */

    private static final ReferenceQueue<Object> referenceQueue = new ReferenceQueue<>();

    /**

     * Returns the base name of this bundle, if known, or {@code null} if unknown.

     *

     * If not null, then this is the value of the {@code baseName} parameter

     * that was passed to the {@code ResourceBundle.getBundle(...)} method

     * when the resource bundle was loaded.

     *

     * @return The base name of the resource bundle, as provided to and expected

     * by the {@code ResourceBundle.getBundle(...)} methods.

     *

     * @see #getBundle(java.lang.String, java.util.Locale, java.lang.ClassLoader)

     *

     * @since 1.8

     */

    public String getBaseBundleName() {

        return name;

    }

    /**

     * 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