/*

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

import java.util.spi.ResourceBundleControlProvider;

import sun.reflect.CallerSensitive;

import sun.reflect.Reflection;

import sun.util.locale.BaseLocale;

import sun.util.locale.LocaleObjectCache;

/**

*

* 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>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 <em>installed</em> {@link

* ResourceBundleControlProvider} implementations. Any installed providers are

* detected at the {@code ResourceBundle} class loading time. 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 installed for supporting the same base name,

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

*

* <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&lt;String&gt; getKeys() {

* return Collections.enumeration(keySet());

* }

*

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

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

* protected Set&lt;String&gt; handleKeySet() {

* return new HashSet&lt;String&gt;(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&lt;String&gt; handleKeySet() {

* return new HashSet&lt;String&gt;(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<>(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;

private static final List<ResourceBundleControlProvider> providers;

static {

List<ResourceBundleControlProvider> list = null;

ServiceLoader<ResourceBundleControlProvider> serviceLoaders

= ServiceLoader.loadInstalled(ResourceBundleControlProvider.class);

for (ResourceBundleControlProvider provider : serviceLoaders) {

if (list == null) {

list = new ArrayList<>();

}

list.add(provider);

}

providers = list;

}

/**

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

*/

private static ClassLoader getLoader(Class<?> caller) {

ClassLoader cl = caller == null ? null : caller.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;

}

/**

* A wrapper of Extension Class Loader

*/

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;

static {

// Find the extension class loader.

ClassLoader ld = ClassLoader.getSystemClassLoader();

ClassLoader parent;

while ((parent = ld.getParent()) != null) {

ld = parent;

}

loader = ld;

}

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

this.locale = locale;

if (loader == null) {

this.loaderRef = null;

} else {

loaderRef = new LoaderReference(loader, referenceQueue, this);

}

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;

}

ClassLoader getLoader() {

return (loaderRef != null) ? loaderRef.get() : null;

}

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;

}

//are refs (both non-null) or (both null)?

if (loaderRef == null) {

return otherEntry.loaderRef == null;

}

ClassLoader loader = loaderRef.get();

return (otherEntry.loaderRef != null)

// with a null reference we can no longer find

// out which class loader was referenced; so

// treat it as unequal

&& (loader != null)

&& (loader == otherEntry.loaderRef.get());

} catch ( NullPointerException | ClassCastException e) {

}

return false;

}

public int hashCode() {

return hashCodeCache;

}

private void calculateHashCode() {

hashCodeCache = name.hashCode() << 3;

hashCodeCache ^= locale.hashCode();

ClassLoader loader = getLoader();

if (loader != null) {

hashCodeCache ^= loader.hashCode();

}

}

public Object clone() {

try {

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

if (loaderRef != null) {

clone.loaderRef = new LoaderReference(loaderRef.get(),

referenceQueue, clone);

}

// Clear the reference to a Throwable

clone.cause = null;

return clone;

} catch (CloneNotSupportedException e) {

//this should never happen

throw new InternalError(e);

}

}

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 + ", ldr=" + getLoader()

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

}

}

/**

* The common interface to get a CacheKey in LoaderReference and

* BundleReference.

*/

private static interface CacheKeyReference {

public CacheKey getCacheKey();

}

/**

* References to class loaders are weak references, so that they can be

* garbage collected when nobody else is using them. The ResourceBundle

* class has no reason to keep class loaders alive.

*/

private static class LoaderReference extends WeakReference<ClassLoader>

implements CacheKeyReference {

private CacheKey cacheKey;

LoaderReference(ClassLoader referent, ReferenceQueue<Object> q, CacheKey key) {

super(referent, q);

cacheKey = key;

}

public CacheKey getCacheKey() {

return cacheKey;

}

}

/**

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

* collected when they have no hard references.

*/

private static class BundleReference extends SoftReference<ResourceBundle>

implements CacheKeyReference {

private CacheKey cacheKey;

BundleReference(ResourceBundle referent, ReferenceQueue<Object> 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

*/

@CallerSensitive

public static final ResourceBundle getBundle(String baseName)

{

return getBundleImpl(baseName, Locale.getDefault(),

getLoader(Reflection.getCallerClass()),

getDefaultControl(baseName));

}

/**

* 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

*/

@CallerSensitive

public static final ResourceBundle getBundle(String baseName,

Control control) {

return getBundleImpl(baseName, Locale.getDefault(),

getLoader(Reflection.getCallerClass()),

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

*/

@CallerSensitive

public static final ResourceBundle getBundle(String baseName,

Locale locale)

{

return getBundleImpl(baseName, locale,

getLoader(Reflection.getCallerClass()),

getDefaultControl(baseName));

}

/**

* 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

*/

@CallerSensitive

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

Control control) {

return getBundleImpl(baseName, targetLocale,

getLoader(Reflection.getCallerClass()),

control);

}

/**

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

* loader.

*

* <p>This method behaves the same as calling

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

* default instance of {@link Control} unless another {@link Control} is

* provided with the {@link ResourceBundleControlProvider} SPI. Refer to the

* description of <a href="#modify_default_behavior">modifying the default

* behavior</a>.

*

* <p><a name="default_behavior">The following describes the default

* behavior</a>.

*

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

*