/*

 * Copyright (c) 1996, 2006, 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 - 1998 - 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.*;

import java.security.AccessController;

import java.text.MessageFormat;

import java.util.List;

import java.util.concurrent.ConcurrentHashMap;

import java.util.spi.LocaleNameProvider;

import java.util.spi.LocaleServiceProvider;

import sun.security.action.GetPropertyAction;

import sun.util.LocaleServiceProviderPool;

import sun.util.resources.LocaleData;

import sun.util.resources.OpenListResourceBundle;

/**

 *

 * A <code>Locale</code> object represents a specific geographical, political,

 * or cultural region. An operation that requires a <code>Locale</code> to perform

 * its task is called <em>locale-sensitive</em> and uses the <code>Locale</code>

 * to tailor information for the user. For example, displaying a number

 * is a locale-sensitive operation--the number should be formatted

 * according to the customs/conventions of the user's native country,

 * region, or culture.

 *

 * <P>

 * Create a <code>Locale</code> object using the constructors in this class:

 * <blockquote>

 * <pre>

 * Locale(String language)

 * Locale(String language, String country)

 * Locale(String language, String country, String variant)

 * </pre>

 * </blockquote>

 * The language argument is a valid <STRONG>ISO Language Code.</STRONG>

 * These codes are the lower-case, two-letter codes as defined by ISO-639.

 * You can find a full list of these codes at a number of sites, such as:

 * <BR><a href ="http://www.loc.gov/standards/iso639-2/php/English_list.php">

 * <code>http://www.loc.gov/standards/iso639-2/php/English_list.php</code></a>

 *

 * <P>

 * The country argument is a valid <STRONG>ISO Country Code.</STRONG> These

 * codes are the upper-case, two-letter codes as defined by ISO-3166.

 * You can find a full list of these codes at a number of sites, such as:

 * <BR><a href="http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html">

 * <code>http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html</code></a>

 *

 * <P>

 * The variant argument is a vendor or browser-specific code.

 * For example, use WIN for Windows, MAC for Macintosh, and POSIX for POSIX.

 * Where there are two variants, separate them with an underscore, and

 * put the most important one first. For example, a Traditional Spanish collation

 * might construct a locale with parameters for language, country and variant as:

 * "es", "ES", "Traditional_WIN".

 *

 * <P>

 * Because a <code>Locale</code> object is just an identifier for a region,

 * no validity check is performed when you construct a <code>Locale</code>.

 * If you want to see whether particular resources are available for the

 * <code>Locale</code> you construct, you must query those resources. For

 * example, ask the <code>NumberFormat</code> for the locales it supports

 * using its <code>getAvailableLocales</code> method.

 * <BR><STRONG>Note:</STRONG> When you ask for a resource for a particular

 * locale, you get back the best available match, not necessarily

 * precisely what you asked for. For more information, look at

 * {@link ResourceBundle}.

 *

 * <P>

 * The <code>Locale</code> class provides a number of convenient constants

 * that you can use to create <code>Locale</code> objects for commonly used

 * locales. For example, the following creates a <code>Locale</code> object

 * for the United States:

 * <blockquote>

 * <pre>

 * Locale.US

 * </pre>

 * </blockquote>

 *

 * <P>

 * Once you've created a <code>Locale</code> you can query it for information about

 * itself. Use <code>getCountry</code> to get the ISO Country Code and

 * <code>getLanguage</code> to get the ISO Language Code. You can

 * use <code>getDisplayCountry</code> to get the

 * name of the country suitable for displaying to the user. Similarly,

 * you can use <code>getDisplayLanguage</code> to get the name of

 * the language suitable for displaying to the user. Interestingly,

 * the <code>getDisplayXXX</code> methods are themselves locale-sensitive

 * and have two versions: one that uses the default locale and one

 * that uses the locale specified as an argument.

 *

 * <P>

 * The Java Platform provides a number of classes that perform locale-sensitive

 * operations. For example, the <code>NumberFormat</code> class formats

 * numbers, currency, or percentages in a locale-sensitive manner. Classes

 * such as <code>NumberFormat</code> have a number of convenience methods

 * for creating a default object of that type. For example, the

 * <code>NumberFormat</code> class provides these three convenience methods

 * for creating a default <code>NumberFormat</code> object:

 * <blockquote>

 * <pre>

 * NumberFormat.getInstance()

 * NumberFormat.getCurrencyInstance()

 * NumberFormat.getPercentInstance()

 * </pre>

 * </blockquote>

 * These methods have two variants; one with an explicit locale

 * and one without; the latter using the default locale.

 * <blockquote>

 * <pre>

 * NumberFormat.getInstance(myLocale)

 * NumberFormat.getCurrencyInstance(myLocale)

 * NumberFormat.getPercentInstance(myLocale)

 * </pre>

 * </blockquote>

 * A <code>Locale</code> is the mechanism for identifying the kind of object

 * (<code>NumberFormat</code>) that you would like to get. The locale is

 * <STRONG>just</STRONG> a mechanism for identifying objects,

 * <STRONG>not</STRONG> a container for the objects themselves.

 *

 * @see         ResourceBundle

 * @see         java.text.Format

 * @see         java.text.NumberFormat

 * @see         java.text.Collator

 * @author      Mark Davis

 * @since       1.1

 */

public final class Locale implements Cloneable, Serializable {

    // cache to store singleton Locales

    private final static ConcurrentHashMap<String, Locale> cache =

        new ConcurrentHashMap<String, Locale>(32);

    /** Useful constant for language.

     */

    static public final Locale ENGLISH = createSingleton("en__", "en", "");

    /** Useful constant for language.

     */

    static public final Locale FRENCH = createSingleton("fr__", "fr", "");

    /** Useful constant for language.

     */

    static public final Locale GERMAN = createSingleton("de__", "de", "");

    /** Useful constant for language.

     */

    static public final Locale ITALIAN = createSingleton("it__", "it", "");

    /** Useful constant for language.

     */

    static public final Locale JAPANESE = createSingleton("ja__", "ja", "");

    /** Useful constant for language.

     */

    static public final Locale KOREAN = createSingleton("ko__", "ko", "");

    /** Useful constant for language.

     */

    static public final Locale CHINESE = createSingleton("zh__", "zh", "");

    /** Useful constant for language.

     */

    static public final Locale SIMPLIFIED_CHINESE = createSingleton("zh_CN_", "zh", "CN");

    /** Useful constant for language.

     */

    static public final Locale TRADITIONAL_CHINESE = createSingleton("zh_TW_", "zh", "TW");

    /** Useful constant for country.

     */

    static public final Locale FRANCE = createSingleton("fr_FR_", "fr", "FR");

    /** Useful constant for country.

     */

    static public final Locale GERMANY = createSingleton("de_DE_", "de", "DE");

    /** Useful constant for country.

     */

    static public final Locale ITALY = createSingleton("it_IT_", "it", "IT");

    /** Useful constant for country.

     */

    static public final Locale JAPAN = createSingleton("ja_JP_", "ja", "JP");

    /** Useful constant for country.

     */

    static public final Locale KOREA = createSingleton("ko_KR_", "ko", "KR");

    /** Useful constant for country.

     */

    static public final Locale CHINA = SIMPLIFIED_CHINESE;

    /** Useful constant for country.

     */

    static public final Locale PRC = SIMPLIFIED_CHINESE;

    /** Useful constant for country.

     */

    static public final Locale TAIWAN = TRADITIONAL_CHINESE;

    /** Useful constant for country.

     */

    static public final Locale UK = createSingleton("en_GB_", "en", "GB");

    /** Useful constant for country.

     */

    static public final Locale US = createSingleton("en_US_", "en", "US");

    /** Useful constant for country.

     */

    static public final Locale CANADA = createSingleton("en_CA_", "en", "CA");

    /** Useful constant for country.

     */

    static public final Locale CANADA_FRENCH = createSingleton("fr_CA_", "fr", "CA");

    /**

     * Useful constant for the root locale.  The root locale is the locale whose

     * language, country, and variant are empty ("") strings.  This is regarded

     * as the base locale of all locales, and is used as the language/country

     * neutral locale for the locale sensitive operations.

     *

     * @since 1.6

     */

    static public final Locale ROOT = createSingleton("__", "", "");

    /** serialization ID

     */

    static final long serialVersionUID = 9149081749638150636L;

    /**

     * Display types for retrieving localized names from the name providers.

     */

    private static final int DISPLAY_LANGUAGE = 0;

    private static final int DISPLAY_COUNTRY  = 1;

    private static final int DISPLAY_VARIANT  = 2;

    /**

     * Construct a locale from language, country, variant.

     * NOTE:  ISO 639 is not a stable standard; some of the language codes it defines

     * (specifically iw, ji, and in) have changed.  This constructor accepts both the

     * old codes (iw, ji, and in) and the new codes (he, yi, and id), but all other

     * API on Locale will return only the OLD codes.

     * @param language lowercase two-letter ISO-639 code.

     * @param country uppercase two-letter ISO-3166 code.

     * @param variant vendor and browser specific code. See class description.

     * @exception NullPointerException thrown if any argument is null.

     */

    public Locale(String language, String country, String variant) {

        this.language = convertOldISOCodes(language);

        this.country = toUpperCase(country).intern();

        this.variant = variant.intern();

    }

    /**

     * Construct a locale from language, country.

     * NOTE:  ISO 639 is not a stable standard; some of the language codes it defines

     * (specifically iw, ji, and in) have changed.  This constructor accepts both the

     * old codes (iw, ji, and in) and the new codes (he, yi, and id), but all other

     * API on Locale will return only the OLD codes.

     * @param language lowercase two-letter ISO-639 code.

     * @param country uppercase two-letter ISO-3166 code.

     * @exception NullPointerException thrown if either argument is null.

     */

    public Locale(String language, String country) {

        this(language, country, "");

    }

    /**

     * Construct a locale from a language code.

     * NOTE:  ISO 639 is not a stable standard; some of the language codes it defines

     * (specifically iw, ji, and in) have changed.  This constructor accepts both the

     * old codes (iw, ji, and in) and the new codes (he, yi, and id), but all other

     * API on Locale will return only the OLD codes.

     * @param language lowercase two-letter ISO-639 code.

     * @exception NullPointerException thrown if argument is null.

     * @since 1.4

     */

    public Locale(String language) {

        this(language, "", "");

    }

    /**

     * Constructs a <code>Locale</code> using <code>language</code>

     * and <code>country</code>.  This constructor assumes that

     * <code>language</code> and <code>contry</code> are interned and

     * it is invoked by createSingleton only. (flag is just for

     * avoiding the conflict with the public constructors.

     */

    private Locale(String language, String country, boolean flag) {

        this.language = language;

        this.country = country;

        this.variant = "";

    }

    /**

     * Creates a <code>Locale</code> instance with the given

     * <code>language</code> and <code>counry</code> and puts the

     * instance under the given <code>key</code> in the cache. This

     * method must be called only when initializing the Locale

     * constants.

     */

    private static Locale createSingleton(String key, String language, String country) {

        Locale locale = new Locale(language, country, false);

        cache.put(key, locale);

        return locale;

    }

    /**

     * Returns a <code>Locale</code> constructed from the given

     * <code>language</code>, <code>country</code> and

     * <code>variant</code>. If the same <code>Locale</code> instance

     * is available in the cache, then that instance is

     * returned. Otherwise, a new <code>Locale</code> instance is

     * created and cached.

     *

     * @param language lowercase two-letter ISO-639 code.

     * @param country uppercase two-letter ISO-3166 code.

     * @param variant vendor and browser specific code. See class description.

     * @return the <code>Locale</code> instance requested

     * @exception NullPointerException if any argument is null.

     */

    static Locale getInstance(String language, String country, String variant) {

        if (language== null || country == null || variant == null) {

            throw new NullPointerException();

        }

        StringBuilder sb = new StringBuilder();

        sb.append(language).append('_').append(country).append('_').append(variant);

        String key = sb.toString();

        Locale locale = cache.get(key);

        if (locale == null) {

            locale = new Locale(language, country, variant);

            Locale l = cache.putIfAbsent(key, locale);

            if (l != null) {

                locale = l;

            }

        }

        return locale;

    }

    /**

     * Gets the current value of the default locale for this instance

     * of the Java Virtual Machine.

     * <p>

     * The Java Virtual Machine sets the default locale during startup

     * based on the host environment. It is used by many locale-sensitive

     * methods if no locale is explicitly specified.

     * It can be changed using the

     * {@link #setDefault(java.util.Locale) setDefault} method.

     *

     * @return the default locale for this instance of the Java Virtual Machine

     */

    public static Locale getDefault() {

        // do not synchronize this method - see 4071298

        // it's OK if more than one default locale happens to be created

        if (defaultLocale == null) {

            language = AccessController.doPrivileged(

            } else {

                country = AccessController.doPrivileged(

                variant = AccessController.doPrivileged(

            }

        }

    }

    /**

     * Sets the default locale for this instance of the Java Virtual Machine.

     * This does not affect the host locale.

     * <p>

     * If there is a security manager, its <code>checkPermission</code>

     * method is called with a <code>PropertyPermission("user.language", "write")</code>

     * permission before the default locale is changed.

     * <p>

     * The Java Virtual Machine sets the default locale during startup

     * based on the host environment. It is used by many locale-sensitive

     * methods if no locale is explicitly specified.

     * <p>

     * Since changing the default locale may affect many different areas

     * of functionality, this method should only be used if the caller

     * is prepared to reinitialize locale-sensitive code running

     * within the same Java Virtual Machine.

     *

     * @throws SecurityException

     *        if a security manager exists and its

     *        <code>checkPermission</code> method doesn't allow the operation.

     * @throws NullPointerException if <code>newLocale</code> is null