/*

 * Copyright (c) 1996, 2019, 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.access.JavaUtilResourceBundleAccess;

import jdk.internal.access.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} 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} that's used on a button for canceling operations.

 * In "MyResources" the {@code String} 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} 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} 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}s.

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

 * In the above example, the values

 * are also {@code String}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} 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}.

 *

 * <P>

 * Besides {@code getString}, {@code ResourceBundle} also provides

 * a method for getting string arrays, {@code getStringArray},

 * as well as a generic {@code getObject} method for any other

 * type of object. When using {@code getObject}, 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 ListResourceBundle} and {@code PropertyResourceBundle},

 * that provide a fairly simple way to create resources.

 * As you saw briefly in a previous example, {@code ListResourceBundle}

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

 * {@code PropertyResourceBundle} uses a properties file to manage

 * its resources.

 *

 * <p>

 * If {@code ListResourceBundle} or {@code PropertyResourceBundle}

 * do not suit your needs, you can write your own {@code ResourceBundle}

 * subclass.  Your subclasses must override two methods: {@code handleGetObject}

 * and {@code getKeys()}.

 *

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

 *

 * <h2><a id="resource-bundle-modules">Resource Bundles and Named Modules</a></h2>

 *

 * Resource bundles can be deployed in modules in the following ways:

 *

 * <h3>Resource bundles together with an application</h3>

 *

 * Resource bundles can be deployed together with an application in the same

 * module.  In that case, the resource bundles are loaded

 * by code in the module by calling the {@link #getBundle(String)}

 * or {@link #getBundle(String, Locale)} method.

 *

 * <h3><a id="service-providers">Resource bundles as service providers</a></h3>

 *

 * Resource bundles can be deployed in one or more <em>service provider modules</em>

 * and they can be located using {@link ServiceLoader}.

 * A {@linkplain ResourceBundleProvider service} interface or class must be

 * defined. The caller module declares that it uses the service, the service

 * provider modules declare that they provide implementations of the service.

 * Refer to {@link ResourceBundleProvider} for developing resource bundle

 * services and deploying resource bundle providers.

 * The module obtaining the resource bundle can be a resource bundle

 * provider itself; in which case this module only locates the resource bundle

 * via service provider mechanism.

 *

 * <p>A {@linkplain ResourceBundleProvider resource bundle provider} can

 * provide resource bundles in any format such XML which replaces the need

 * of {@link Control ResourceBundle.Control}.

 *

 * <h3><a id="other-modules">Resource bundles in other modules and class path</a></h3>

 *

 * Resource bundles in a named module may be <em>encapsulated</em> so that

 * it cannot be located by code in other modules.  Resource bundles

 * in unnamed modules and class path are open for any module to access.

 * Resource bundle follows the resource encapsulation rules as specified

 * in {@link Module#getResourceAsStream(String)}.

 *

 * <p>The {@code getBundle} factory methods with no {@code Control} parameter

 * locate and load resource bundles from

 * {@linkplain ResourceBundleProvider service providers}.

 * It may continue the search as if calling {@link Module#getResourceAsStream(String)}

 * to find the named resource from a given module and calling

 * {@link ClassLoader#getResourceAsStream(String)}; refer to

 * the specification of the {@code getBundle} method for details.

 * Only non-encapsulated resource bundles of "{@code java.class}"

 * or "{@code java.properties}" format are searched.

 *

 * <p>If the caller module is a

 * <a href="{@docRoot}/java.base/java/util/spi/ResourceBundleProvider.html#obtain-resource-bundle">

 * resource bundle provider</a>, it does not fall back to the

 * class loader search.

 *

 * <h3>Resource bundles in automatic modules</h3>

 *

 * A common format of resource bundles is in {@linkplain PropertyResourceBundle

 * .properties} file format.  Typically {@code .properties} resource bundles

 * are packaged in a JAR file.  Resource bundle only JAR file can be readily

 * deployed as an <a href="{@docRoot}/java.base/java/lang/module/ModuleFinder.html#automatic-modules">

 * automatic module</a>.  For example, if the JAR file contains the

 * entry "{@code p/q/Foo_ja.properties}" and no {@code .class} entry,

 * when resolved and defined as an automatic module, no package is derived

 * for this module.  This allows resource bundles in {@code .properties}

 * format packaged in one or more JAR files that may contain entries

 * in the same directory and can be resolved successfully as

 * automatic modules.

 *

 * <h3>ResourceBundle.Control</h3>

 *

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

 * to perform the bundle loading process by the {@code getBundle}

 * factory methods that take a {@code ResourceBundle.Control}

 * 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> {@link ResourceBundle.Control} is designed for an application deployed

 * in an unnamed module, for example to support resource bundles in

 * non-standard formats or package localized resources in a non-traditional

 * convention. {@link ResourceBundleProvider} is the replacement for

 * {@code ResourceBundle.Control} when migrating to modules.

 * {@code UnsupportedOperationException} will be thrown when a factory

 * method that takes the {@code ResourceBundle.Control} parameter is called.

 *

 * <p><a id="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.

 *

 * <h2>Cache Management</h2>

 *

 * Resource bundle instances created by the {@code getBundle} 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} 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} 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.

 *

 * <h2>Example</h2>

 *

 * The following is a very simple example of a {@code ResourceBundle}

 * subclass, {@code MyResources}, that manages two resources (for a larger number of

 * resources you would probably use a {@code Map}).

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

 * a "parent-level" {@code ResourceBundle} 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}s. For example, you could have a set of bundles for

 * exception messages, {@code ExceptionResources}

 * ({@code ExceptionResources_fr}, {@code ExceptionResources_de}, ...),

 * and one for widgets, {@code WidgetResource} ({@code WidgetResources_fr},

 * {@code WidgetResources_de}, ...); 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() {

    }