/* * Copyright (c) 1996, 2018, 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 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. * *

* This allows you to write programs that can: *

be easily localized, or translated, into different languages *
handle multiple locales at once *
be easily modified later to support even more locales *

* *

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

* 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 * String that's used on a button for canceling operations. * In "MyResources" the String may contain "Cancel" and in * "MyResources_de" it may contain "Abbrechen". * *

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

* When your program needs a locale-specific object, it loads * the ResourceBundle class using the * {@link #getBundle(java.lang.String, java.util.Locale) getBundle} * method: *

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

* *

* Resource bundles contain key/value pairs. The keys uniquely * identify a locale-specific object in the bundle. Here's an * example of a ListResourceBundle that contains * two key/value pairs: *

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

* Keys are always Strings. * In this example, the keys are "OkKey" and "CancelKey". * In the above example, the values * are also Strings--"OK" and "Cancel"--but * they don't have to be. The values can be any type of object. * *

* You retrieve an object from resource bundle using the appropriate * getter method. Because "OkKey" and "CancelKey" * are both strings, you would use getString to retrieve them: *

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

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

* Besides getString, ResourceBundle also provides * a method for getting string arrays, getStringArray, * as well as a generic getObject method for any other * type of object. When using getObject, you'll * have to cast the result to the appropriate type. For example: *

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

* *

* The Java Platform provides two subclasses of ResourceBundle, * ListResourceBundle and PropertyResourceBundle, * that provide a fairly simple way to create resources. * As you saw briefly in a previous example, ListResourceBundle * manages its resource as a list of key/value pairs. * PropertyResourceBundle uses a properties file to manage * its resources. * *

* If ListResourceBundle or PropertyResourceBundle * do not suit your needs, you can write your own ResourceBundle * subclass. Your subclasses must override two methods: handleGetObject * and getKeys(). * *

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

Resource Bundles and Named Modules

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

Resource bundles together with an application

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

Resource bundles as service providers

* * Resource bundles can be deployed in one or more service provider modules * 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. * *

A {@linkplain ResourceBundleProvider resource bundle provider} can * provide resource bundles in any format such XML which replaces the need * of {@link Control ResourceBundle.Control}. * *

Resource bundles in other modules and class path

* * Resource bundles in a named module may be encapsulated 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)}. * *

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

If the caller module is a * * resource bundle provider, it does not fall back to the * class loader search. * *

Resource bundles in automatic modules

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

ResourceBundle.Control

* * The {@link ResourceBundle.Control} class provides information necessary * to perform the bundle loading process by the getBundle * factory methods that take a 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. * *

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

For the {@code getBundle} factory * methods that take no {@link Control} instance, their default behavior 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. * *

Cache Management

* * Resource bundle instances created by the getBundle factory * methods are cached by default, and the factory methods return the same * resource bundle instance multiple times if it has been * cached. 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) 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. * *

Example

* * The following is a very simple example of a ResourceBundle * subclass, MyResources, that manages two resources (for a larger number of * resources you would probably use a Map). * Notice that you don't need to supply a value if * a "parent-level" ResourceBundle handles the same * key with the same value (as for the okKey below). *

 * // 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"));
 *     }
 * }
 *

* You do not have to restrict yourself to using a single family of * ResourceBundles. For example, you could have a set of bundles for * exception messages, ExceptionResources * (ExceptionResources_fr, ExceptionResources_de, ...), * and one for widgets, WidgetResource (WidgetResources_fr, * 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 bundleClass) { return ResourceBundleProviderHelper.newResourceBundle(bundleClass); } }); } /** constant indicating that no resource bundle exists */ private static final ResourceBundle NONEXISTENT_BUNDLE = new ResourceBundle() { public Enumeration 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 cacheList = new ConcurrentHashMap<>(INITIAL_CACHE_SIZE); /** * Queue for reference objects referring to class loaders or bundles. */ private static final ReferenceQueue

Locale	Resource bundle
Locale("fr", "CH")	MyResources_fr_CH.class, parent MyResources_fr.properties, parent MyResources.class
Locale("fr", "FR")	MyResources_fr.properties, parent MyResources.class
Locale("de", "DE")	MyResources_en.properties, parent MyResources.class
Locale("en", "US")	MyResources_en.properties, parent MyResources.class
Locale("es", "ES")	MyResources_es_ES.class, parent MyResources.class

Index	`Locale`	`format`
1	`Locale("de", "DE")`	`java.class`
2	`Locale("de", "DE")`	`java.properties`
3	`Locale("de")`	`java.class`
4	`Locale("de")`	`java.properties`
5	`Locale("")`	`java.class`
6	`Locale("")`	`java.properties`