Source Home >> Java Source 1.6.0 >> java.util.Locale V 0.09

0001/*
0002 * @(#)Locale.java	1.89 06/03/06
0003 *
0004 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
0005 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
0006 */
0007
0008/*
0009 * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved
0010 * (C) Copyright IBM Corp. 1996 - 1998 - All Rights Reserved
0011 *
0012 * The original version of this source code and documentation
0013 * is copyrighted and owned by Taligent, Inc., a wholly-owned
0014 * subsidiary of IBM. These materials are provided under terms
0015 * of a License Agreement between Taligent and Sun. This technology
0016 * is protected by multiple US and International patents.
0017 *
0018 * This notice and attribution to Taligent may not be removed.
0019 * Taligent is a registered trademark of Taligent, Inc.
0020 *
0021 */
0022
0023package java.util;
0024
0025import java.io.*;
0026import java.security.AccessController;
0027import java.text.MessageFormat;
0028import java.util.List;
0029import java.util.concurrent.ConcurrentHashMap;
0030import java.util.spi.LocaleNameProvider;
0031import java.util.spi.LocaleServiceProvider;
0032import sun.security.action.GetPropertyAction;
0033import sun.util.LocaleServiceProviderPool;
0034import sun.util.resources.LocaleData;
0035import sun.util.resources.OpenListResourceBundle;
0036
0037/**
0038 *
0039 * A <code>Locale</code> object represents a specific geographical, political,
0040 * or cultural region. An operation that requires a <code>Locale</code> to perform
0041 * its task is called <em>locale-sensitive</em> and uses the <code>Locale</code>
0042 * to tailor information for the user. For example, displaying a number
0043 * is a locale-sensitive operation--the number should be formatted
0044 * according to the customs/conventions of the user's native country,
0045 * region, or culture.
0046 *
0047 * <P>
0048 * Create a <code>Locale</code> object using the constructors in this class:
0049 * <blockquote>
0050 * <pre>
0051 * Locale(String language)
0052 * Locale(String language, String country)
0053 * Locale(String language, String country, String variant)
0054 * </pre>
0055 * </blockquote>
0056 * The language argument is a valid <STRONG>ISO Language Code.</STRONG>
0057 * These codes are the lower-case, two-letter codes as defined by ISO-639.
0058 * You can find a full list of these codes at a number of sites, such as:
0059 * <BR><a href ="http://www.loc.gov/standards/iso639-2/englangn.html">
0060 * <code>http://www.loc.gov/standards/iso639-2/englangn.html</code></a>
0061 *
0062 * <P>
0063 * The country argument is a valid <STRONG>ISO Country Code.</STRONG> These
0064 * codes are the upper-case, two-letter codes as defined by ISO-3166.
0065 * You can find a full list of these codes at a number of sites, such as:
0066 * <BR><a href="http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html">
0067 * <code>http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html</code></a>
0068 *
0069 * <P>
0070 * The variant argument is a vendor or browser-specific code.
0071 * For example, use WIN for Windows, MAC for Macintosh, and POSIX for POSIX.
0072 * Where there are two variants, separate them with an underscore, and
0073 * put the most important one first. For example, a Traditional Spanish collation
0074 * might construct a locale with parameters for language, country and variant as:
0075 * "es", "ES", "Traditional_WIN".
0076 *
0077 * <P>
0078 * Because a <code>Locale</code> object is just an identifier for a region,
0079 * no validity check is performed when you construct a <code>Locale</code>.
0080 * If you want to see whether particular resources are available for the
0081 * <code>Locale</code> you construct, you must query those resources. For
0082 * example, ask the <code>NumberFormat</code> for the locales it supports
0083 * using its <code>getAvailableLocales</code> method.
0084 * <BR><STRONG>Note:</STRONG> When you ask for a resource for a particular
0085 * locale, you get back the best available match, not necessarily
0086 * precisely what you asked for. For more information, look at
0087 * {@link ResourceBundle}.
0088 *
0089 * <P>
0090 * The <code>Locale</code> class provides a number of convenient constants
0091 * that you can use to create <code>Locale</code> objects for commonly used
0092 * locales. For example, the following creates a <code>Locale</code> object
0093 * for the United States:
0094 * <blockquote>
0095 * <pre>
0096 * Locale.US
0097 * </pre>
0098 * </blockquote>
0099 *
0100 * <P>
0101 * Once you've created a <code>Locale</code> you can query it for information about
0102 * itself. Use <code>getCountry</code> to get the ISO Country Code and
0103 * <code>getLanguage</code> to get the ISO Language Code. You can
0104 * use <code>getDisplayCountry</code> to get the
0105 * name of the country suitable for displaying to the user. Similarly,
0106 * you can use <code>getDisplayLanguage</code> to get the name of
0107 * the language suitable for displaying to the user. Interestingly,
0108 * the <code>getDisplayXXX</code> methods are themselves locale-sensitive
0109 * and have two versions: one that uses the default locale and one
0110 * that uses the locale specified as an argument.
0111 *
0112 * <P>
0113 * The Java Platform provides a number of classes that perform locale-sensitive
0114 * operations. For example, the <code>NumberFormat</code> class formats
0115 * numbers, currency, or percentages in a locale-sensitive manner. Classes
0116 * such as <code>NumberFormat</code> have a number of convenience methods
0117 * for creating a default object of that type. For example, the
0118 * <code>NumberFormat</code> class provides these three convenience methods
0119 * for creating a default <code>NumberFormat</code> object:
0120 * <blockquote>
0121 * <pre>
0122 * NumberFormat.getInstance()
0123 * NumberFormat.getCurrencyInstance()
0124 * NumberFormat.getPercentInstance()
0125 * </pre>
0126 * </blockquote>
0127 * These methods have two variants; one with an explicit locale
0128 * and one without; the latter using the default locale.
0129 * <blockquote>
0130 * <pre>
0131 * NumberFormat.getInstance(myLocale)
0132 * NumberFormat.getCurrencyInstance(myLocale)
0133 * NumberFormat.getPercentInstance(myLocale)
0134 * </pre>
0135 * </blockquote>
0136 * A <code>Locale</code> is the mechanism for identifying the kind of object
0137 * (<code>NumberFormat</code>) that you would like to get. The locale is
0138 * <STRONG>just</STRONG> a mechanism for identifying objects,
0139 * <STRONG>not</STRONG> a container for the objects themselves.
0140 *
0141 * @see         ResourceBundle
0142 * @see         java.text.Format
0143 * @see         java.text.NumberFormat
0144 * @see         java.text.Collator
0145 * @author      Mark Davis
0146 * @since       1.1
0147 */
0148
0149public final class Locale implements Cloneable, Serializable {
0150
0151    // cache to store singleton Locales
0152    private final static ConcurrentHashMap<String, Locale> cache =
0153	new ConcurrentHashMap<String, Locale>(32);
0154
0155    /** Useful constant for language.
0156     */
0157    static public final Locale ENGLISH = createSingleton("en__", "en", "");
0158
0159    /** Useful constant for language.
0160     */
0161    static public final Locale FRENCH = createSingleton("fr__", "fr", "");
0162
0163    /** Useful constant for language.
0164     */
0165    static public final Locale GERMAN = createSingleton("de__", "de", "");
0166
0167    /** Useful constant for language.
0168     */
0169    static public final Locale ITALIAN = createSingleton("it__", "it", "");
0170
0171    /** Useful constant for language.
0172     */
0173    static public final Locale JAPANESE = createSingleton("ja__", "ja", "");
0174
0175    /** Useful constant for language.
0176     */
0177    static public final Locale KOREAN = createSingleton("ko__", "ko", "");
0178
0179    /** Useful constant for language.
0180     */
0181    static public final Locale CHINESE = createSingleton("zh__", "zh", "");
0182
0183    /** Useful constant for language.
0184     */
0185    static public final Locale SIMPLIFIED_CHINESE = createSingleton("zh_CN_", "zh", "CN");
0186
0187    /** Useful constant for language.
0188     */
0189    static public final Locale TRADITIONAL_CHINESE = createSingleton("zh_TW_", "zh", "TW");
0190
0191    /** Useful constant for country.
0192     */
0193    static public final Locale FRANCE = createSingleton("fr_FR_", "fr", "FR");
0194
0195    /** Useful constant for country.
0196     */
0197    static public final Locale GERMANY = createSingleton("de_DE_", "de", "DE");
0198
0199    /** Useful constant for country.
0200     */
0201    static public final Locale ITALY = createSingleton("it_IT_", "it", "IT");
0202
0203    /** Useful constant for country.
0204     */
0205    static public final Locale JAPAN = createSingleton("ja_JP_", "ja", "JP");
0206
0207    /** Useful constant for country.
0208     */
0209    static public final Locale KOREA = createSingleton("ko_KR_", "ko", "KR");
0210
0211    /** Useful constant for country.
0212     */
0213    static public final Locale CHINA = SIMPLIFIED_CHINESE;
0214
0215    /** Useful constant for country.
0216     */
0217    static public final Locale PRC = SIMPLIFIED_CHINESE;
0218
0219    /** Useful constant for country.
0220     */
0221    static public final Locale TAIWAN = TRADITIONAL_CHINESE;
0222
0223    /** Useful constant for country.
0224     */
0225    static public final Locale UK = createSingleton("en_GB_", "en", "GB");
0226
0227    /** Useful constant for country.
0228     */
0229    static public final Locale US = createSingleton("en_US_", "en", "US");
0230
0231    /** Useful constant for country.
0232     */
0233    static public final Locale CANADA = createSingleton("en_CA_", "en", "CA");
0234
0235    /** Useful constant for country.
0236     */
0237    static public final Locale CANADA_FRENCH = createSingleton("fr_CA_", "fr", "CA");
0238
0239    /**
0240     * Useful constant for the root locale.  The root locale is the locale whose
0241     * language, country, and variant are empty ("") strings.  This is regarded
0242     * as the base locale of all locales, and is used as the language/country 
0243     * neutral locale for the locale sensitive operations.
0244     *
0245     * @since 1.6
0246     */
0247    static public final Locale ROOT = createSingleton("__", "", "");
0248
0249    /** serialization ID
0250     */
0251    static final long serialVersionUID = 9149081749638150636L;
0252
0253    /**
0254     * Display types for retrieving localized names from the name providers.
0255     */
0256    private static final int DISPLAY_LANGUAGE = 0;
0257    private static final int DISPLAY_COUNTRY  = 1;
0258    private static final int DISPLAY_VARIANT  = 2;
0259
0260    /**
0261     * Construct a locale from language, country, variant.
0262     * NOTE:  ISO 639 is not a stable standard; some of the language codes it defines
0263     * (specifically iw, ji, and in) have changed.  This constructor accepts both the
0264     * old codes (iw, ji, and in) and the new codes (he, yi, and id), but all other 
0265     * API on Locale will return only the OLD codes. 
0266     * @param language lowercase two-letter ISO-639 code.
0267     * @param country uppercase two-letter ISO-3166 code.
0268     * @param variant vendor and browser specific code. See class description.
0269     * @exception NullPointerException thrown if any argument is null.
0270     */
0271    public Locale(String language, String country, String variant) {
0272        this.language = convertOldISOCodes(language);
0273        this.country = toUpperCase(country).intern();
0274        this.variant = variant.intern();
0275    }
0276
0277    /**
0278     * Construct a locale from language, country.
0279     * NOTE:  ISO 639 is not a stable standard; some of the language codes it defines
0280     * (specifically iw, ji, and in) have changed.  This constructor accepts both the
0281     * old codes (iw, ji, and in) and the new codes (he, yi, and id), but all other 
0282     * API on Locale will return only the OLD codes. 
0283     * @param language lowercase two-letter ISO-639 code.
0284     * @param country uppercase two-letter ISO-3166 code.
0285     * @exception NullPointerException thrown if either argument is null.
0286     */
0287    public Locale(String language, String country) {
0288        this(language, country, "");
0289    }
0290
0291    /**
0292     * Construct a locale from a language code.
0293     * NOTE:  ISO 639 is not a stable standard; some of the language codes it defines
0294     * (specifically iw, ji, and in) have changed.  This constructor accepts both the
0295     * old codes (iw, ji, and in) and the new codes (he, yi, and id), but all other 
0296     * API on Locale will return only the OLD codes. 
0297     * @param language lowercase two-letter ISO-639 code.
0298     * @exception NullPointerException thrown if argument is null.
0299     * @since 1.4
0300     */
0301    public Locale(String language) {
0302        this(language, "", "");
0303    }
0304
0305    /**
0306     * Constructs a <code>Locale</code> using <code>language</code>
0307     * and <code>country</code>.  This constructor assumes that
0308     * <code>language</code> and <code>contry</code> are interned and
0309     * it is invoked by createSingleton only. (flag is just for
0310     * avoiding the conflict with the public constructors.
0311     */
0312    private Locale(String language, String country, boolean flag) {
0313	this.language = language;
0314	this.country = country;
0315	this.variant = "";
0316    }
0317
0318    /**
0319     * Creates a <code>Locale</code> instance with the given
0320     * <code>language</code> and <code>counry</code> and puts the
0321     * instance under the given <code>key</code> in the cache. This
0322     * method must be called only when initializing the Locale
0323     * constants.
0324     */
0325    private static Locale createSingleton(String key, String language, String country) {
0326	Locale locale = new Locale(language, country, false);
0327	cache.put(key, locale);
0328	return locale;
0329    }
0330
0331    /**
0332     * Returns a <code>Locale</code> constructed from the given
0333     * <code>language</code>, <code>country</code> and
0334     * <code>variant</code>. If the same <code>Locale</code> instance
0335     * is available in the cache, then that instance is
0336     * returned. Otherwise, a new <code>Locale</code> instance is
0337     * created and cached.
0338     *
0339     * @param language lowercase two-letter ISO-639 code.
0340     * @param country uppercase two-letter ISO-3166 code.
0341     * @param variant vendor and browser specific code. See class description.
0342     * @return the <code>Locale</code> instance requested
0343     * @exception NullPointerException if any argument is null.
0344     */
0345    static Locale getInstance(String language, String country, String variant) {
0346        if (language== null || country == null || variant == null) {
0347            throw new NullPointerException();
0348        }
0349
0350	StringBuilder sb = new StringBuilder();
0351	sb.append(language).append('_').append(country).append('_').append(variant);
0352	String key = sb.toString();
0353	Locale locale = cache.get(key);
0354	if (locale == null) {
0355	    locale = new Locale(language, country, variant);
0356	    Locale l = cache.putIfAbsent(key, locale);
0357	    if (l != null) {
0358		locale = l;
0359	    }
0360	}
0361	return locale;
0362    }
0363
0364    /**
0365     * Gets the current value of the default locale for this instance
0366     * of the Java Virtual Machine.
0367     * <p>
0368     * The Java Virtual Machine sets the default locale during startup
0369     * based on the host environment. It is used by many locale-sensitive
0370     * methods if no locale is explicitly specified.
0371     * It can be changed using the
0372     * {@link #setDefault(java.util.Locale) setDefault} method.
0373     *
0374     * @return the default locale for this instance of the Java Virtual Machine
0375     */
0376    public static Locale getDefault() {
0377        // do not synchronize this method - see 4071298
0378        // it's OK if more than one default locale happens to be created
0379        if (defaultLocale == null) {
0380            String language, region, country, variant;
0381            language = (String) AccessController.doPrivileged(
0382                            new GetPropertyAction("user.language", "en"));
0383            // for compatibility, check for old user.region property
0384            region = (String) AccessController.doPrivileged(
0385                            new GetPropertyAction("user.region"));
0386            if (region != null) {
0387                // region can be of form country, country_variant, or _variant
0388                int i = region.indexOf('_');
0389                if (i >= 0) {
0390                    country = region.substring(0, i);
0391                    variant = region.substring(i + 1);
0392                } else {
0393                    country = region;
0394                    variant = "";
0395                }
0396            } else {
0397                country = (String) AccessController.doPrivileged(
0398                                new GetPropertyAction("user.country", ""));
0399                variant = (String) AccessController.doPrivileged(
0400                                new GetPropertyAction("user.variant", ""));
0401            }
0402            defaultLocale = getInstance(language, country, variant);
0403        }
0404        return defaultLocale;
0405    }
0406
0407    /**
0408     * Sets the default locale for this instance of the Java Virtual Machine.
0409     * This does not affect the host locale.
0410     * <p>
0411     * If there is a security manager, its <code>checkPermission</code>
0412     * method is called with a <code>PropertyPermission("user.language", "write")</code>
0413     * permission before the default locale is changed.
0414     * <p>
0415     * The Java Virtual Machine sets the default locale during startup
0416     * based on the host environment. It is used by many locale-sensitive
0417     * methods if no locale is explicitly specified.
0418     * <p>
0419     * Since changing the default locale may affect many different areas
0420     * of functionality, this method should only be used if the caller
0421     * is prepared to reinitialize locale-sensitive code running
0422     * within the same Java Virtual Machine.
0423     *
0424     * @throws SecurityException
0425     *        if a security manager exists and its
0426     *        <code>checkPermission</code> method doesn't allow the operation.
0427     * @throws NullPointerException if <code>newLocale</code> is null
0428     * @param newLocale the new default locale
0429     * @see SecurityManager#checkPermission
0430     * @see java.util.PropertyPermission
0431     */
0432    public static synchronized void setDefault(Locale newLocale) {
0433        if (newLocale == null)
0434            throw new NullPointerException("Can't set default locale to NULL");
0435
0436        SecurityManager sm = System.getSecurityManager();
0437        if (sm != null) sm.checkPermission(new PropertyPermission
0438                        ("user.language", "write"));
0439            defaultLocale = newLocale;
0440    }
0441
0442    /**
0443     * Returns an array of all installed locales.
0444     * The returned array represents the union of locales supported 
0445     * by the Java runtime environment and by installed 
0446     * {@link java.util.spi.LocaleServiceProvider LocaleServiceProvider}
0447     * implementations.  It must contain at least a <code>Locale</code>
0448     * instance equal to {@link java.util.Locale#US Locale.US}.
0449     *
0450     * @return An array of installed locales.
0451     */
0452    public static Locale[] getAvailableLocales() {
0453        return LocaleServiceProviderPool.getAllAvailableLocales();
0454    }
0455
0456    /**
0457     * Returns a list of all 2-letter country codes defined in ISO 3166.
0458     * Can be used to create Locales.
0459     */
0460    public static String[] getISOCountries() {
0461        if (isoCountries == null) {
0462            isoCountries = getISO2Table(LocaleISOData.isoCountryTable);
0463        }
0464        String[] result = new String[isoCountries.length];
0465        System.arraycopy(isoCountries, 0, result, 0, isoCountries.length);
0466        return result;
0467    }
0468
0469    /**
0470     * Returns a list of all 2-letter language codes defined in ISO 639.
0471     * Can be used to create Locales.
0472     * [NOTE:  ISO 639 is not a stable standard-- some languages' codes have changed.
0473     * The list this function returns includes both the new and the old codes for the
0474     * languages whose codes have changed.]
0475     */
0476    public static String[] getISOLanguages() {
0477        if (isoLanguages == null) {
0478            isoLanguages = getISO2Table(LocaleISOData.isoLanguageTable);
0479        }
0480        String[] result = new String[isoLanguages.length];
0481        System.arraycopy(isoLanguages, 0, result, 0, isoLanguages.length);
0482        return result;
0483    }
0484
0485    private static final String[] getISO2Table(String table) {
0486	int len = table.length() / 5;
0487	String[] isoTable = new String[len];
0488	for (int i = 0, j = 0; i < len; i++, j += 5) {
0489	    isoTable[i] = table.substring(j, j + 2);
0490	}
0491	return isoTable;
0492    }
0493
0494    /**
0495     * Returns the language code for this locale, which will either be the empty string
0496     * or a lowercase ISO 639 code.
0497     * <p>NOTE:  ISO 639 is not a stable standard-- some languages' codes have changed.
0498     * Locale's constructor recognizes both the new and the old codes for the languages
0499     * whose codes have changed, but this function always returns the old code.  If you 
0500     * want to check for a specific language whose code has changed, don't do <pre> 
0501     * if (locale.getLanguage().equals("he")) 
0502     *    ... 
0503     * </pre>Instead, do<pre> 
0504     * if (locale.getLanguage().equals(new Locale("he", "", "").getLanguage())) 
0505     *    ...</pre>
0506     * @see #getDisplayLanguage
0507     */
0508    public String getLanguage() {
0509        return language;
0510    }
0511
0512    /**
0513     * Returns the country/region code for this locale, which will
0514     * either be the empty string or an uppercase ISO 3166 2-letter code.
0515     * @see #getDisplayCountry
0516     */
0517    public String getCountry() {
0518        return country;
0519    }
0520
0521    /**
0522     * Returns the variant code for this locale.
0523     * @see #getDisplayVariant
0524     */
0525    public String getVariant() {
0526        return variant;
0527    }
0528
0529    /**
0530     * Getter for the programmatic name of the entire locale,
0531     * with the language, country and variant separated by underbars.
0532     * Language is always lower case, and country is always upper case.
0533     * If the language is missing, the string will begin with an underbar.
0534     * If both the language and country fields are missing, this function
0535     * will return the empty string, even if the variant field is filled in
0536     * (you can't have a locale with just a variant-- the variant must accompany
0537     * a valid language or country code).
0538     * Examples: "en", "de_DE", "_GB", "en_US_WIN", "de__POSIX", "fr__MAC"
0539     * @see #getDisplayName
0540     */
0541    public final String toString() {
0542        boolean l = language.length() != 0;
0543        boolean c = country.length() != 0;
0544        boolean v = variant.length() != 0;
0545        StringBuilder result = new StringBuilder(language);
0546        if (c||(l&&v)) {
0547            result.append('_').append(country); // This may just append '_'
0548        }
0549        if (v&&(l||c)) {
0550            result.append('_').append(variant);
0551        }
0552        return result.toString();
0553    }
0554
0555    /**
0556     * Returns a three-letter abbreviation for this locale's language.  If the locale
0557     * doesn't specify a language, this will be the empty string.  Otherwise, this will
0558     * be a lowercase ISO 639-2/T language code.
0559     * The ISO 639-2 language codes can be found on-line at
0560     * <a href="http://www.loc.gov/standards/iso639-2/englangn.html">
0561     * <code>http://www.loc.gov/standards/iso639-2/englangn.html</code>.</a>
0562     * @exception MissingResourceException Throws MissingResourceException if the
0563     * three-letter language abbreviation is not available for this locale.
0564     */
0565    public String getISO3Language() throws MissingResourceException {
0566	String language3 = getISO3Code(language, LocaleISOData.isoLanguageTable);
0567        if (language3 == null) {
0568            throw new MissingResourceException("Couldn't find 3-letter language code for "
0569                    + language, "FormatData_" + toString(), "ShortLanguage");
0570        }
0571        return language3;
0572    }
0573
0574    /**
0575     * Returns a three-letter abbreviation for this locale's country.  If the locale
0576     * doesn't specify a country, this will be the empty string.  Otherwise, this will
0577     * be an uppercase ISO 3166 3-letter country code.
0578     * The ISO 3166-2 country codes can be found on-line at
0579     * <a href="http://www.davros.org/misc/iso3166.txt">
0580     * <code>http://www.davros.org/misc/iso3166.txt</code>.</a>
0581     * @exception MissingResourceException Throws MissingResourceException if the
0582     * three-letter country abbreviation is not available for this locale.
0583     */
0584    public String getISO3Country() throws MissingResourceException {
0585	String country3 = getISO3Code(country, LocaleISOData.isoCountryTable);
0586        if (country3 == null) {
0587            throw new MissingResourceException("Couldn't find 3-letter country code for "
0588                    + country, "FormatData_" + toString(), "ShortCountry");
0589        }
0590	return country3;
0591    }
0592
0593    private static final String getISO3Code(String iso2Code, String table) {
0594	int codeLength = iso2Code.length();
0595        if (codeLength == 0) {
0596            return "";
0597        }
0598
0599	int tableLength = table.length();
0600        int index = tableLength;
0601	if (codeLength == 2) {
0602	    char c1 = iso2Code.charAt(0);
0603	    char c2 = iso2Code.charAt(1);
0604	    for (index = 0; index < tableLength; index += 5) {
0605		if (table.charAt(index) == c1
0606		    && table.charAt(index + 1) == c2) {
0607		    break;
0608		}
0609	    }
0610	}
0611        return index < tableLength ? table.substring(index + 2, index + 5) : null;
0612    }
0613
0614    /**
0615     * Returns a name for the locale's language that is appropriate for display to the
0616     * user.
0617     * If possible, the name returned will be localized for the default locale.
0618     * For example, if the locale is fr_FR and the default locale
0619     * is en_US, getDisplayLanguage() will return "French"; if the locale is en_US and
0620     * the default locale is fr_FR, getDisplayLanguage() will return "anglais".
0621     * If the name returned cannot be localized for the default locale,
0622     * (say, we don't have a Japanese name for Croatian),
0623     * this function falls back on the English name, and uses the ISO code as a last-resort
0624     * value.  If the locale doesn't specify a language, this function returns the empty string.
0625     */
0626    public final String getDisplayLanguage() {
0627        return getDisplayLanguage(getDefault());
0628    }
0629
0630    /**
0631     * Returns a name for the locale's language that is appropriate for display to the
0632     * user.
0633     * If possible, the name returned will be localized according to inLocale.
0634     * For example, if the locale is fr_FR and inLocale
0635     * is en_US, getDisplayLanguage() will return "French"; if the locale is en_US and
0636     * inLocale is fr_FR, getDisplayLanguage() will return "anglais".
0637     * If the name returned cannot be localized according to inLocale,
0638     * (say, we don't have a Japanese name for Croatian),
0639     * this function falls back on the English name, and finally
0640     * on the ISO code as a last-resort value.  If the locale doesn't specify a language,
0641     * this function returns the empty string.
0642     *
0643     * @exception NullPointerException if <code>inLocale</code> is <code>null</code>
0644     */
0645    public String getDisplayLanguage(Locale inLocale) {
0646        return getDisplayString(language, inLocale, DISPLAY_LANGUAGE);
0647    }
0648
0649    /**
0650     * Returns a name for the locale's country that is appropriate for display to the
0651     * user.
0652     * If possible, the name returned will be localized for the default locale.
0653     * For example, if the locale is fr_FR and the default locale
0654     * is en_US, getDisplayCountry() will return "France"; if the locale is en_US and
0655     * the default locale is fr_FR, getDisplayCountry() will return "Etats-Unis".
0656     * If the name returned cannot be localized for the default locale,
0657     * (say, we don't have a Japanese name for Croatia),
0658     * this function falls back on the English name, and uses the ISO code as a last-resort
0659     * value.  If the locale doesn't specify a country, this function returns the empty string.
0660     */
0661    public final String getDisplayCountry() {
0662        return getDisplayCountry(getDefault());
0663    }
0664
0665    /**
0666     * Returns a name for the locale's country that is appropriate for display to the
0667     * user.
0668     * If possible, the name returned will be localized according to inLocale.
0669     * For example, if the locale is fr_FR and inLocale
0670     * is en_US, getDisplayCountry() will return "France"; if the locale is en_US and
0671     * inLocale is fr_FR, getDisplayCountry() will return "Etats-Unis".
0672     * If the name returned cannot be localized according to inLocale.
0673     * (say, we don't have a Japanese name for Croatia),
0674     * this function falls back on the English name, and finally
0675     * on the ISO code as a last-resort value.  If the locale doesn't specify a country,
0676     * this function returns the empty string.
0677     *
0678     * @exception NullPointerException if <code>inLocale</code> is <code>null</code>
0679     */
0680    public String getDisplayCountry(Locale inLocale) {
0681        return getDisplayString(country, inLocale, DISPLAY_COUNTRY);
0682    }
0683    
0684    private String getDisplayString(String code, Locale inLocale, int type) {
0685        if (code.length() == 0) {
0686            return "";
0687        }
0688
0689        if (inLocale == null) {
0690            throw new NullPointerException();
0691        }
0692
0693        try {
0694            OpenListResourceBundle bundle = LocaleData.getLocaleNames(inLocale);
0695            String key = (type == DISPLAY_VARIANT ? "%%"+code : code);
0696            String result = null;
0697
0698            // Check whether a provider can provide an implementation that's closer 
0699            // to the requested locale than what the Java runtime itself can provide.
0700            LocaleServiceProviderPool pool =
0701                LocaleServiceProviderPool.getPool(LocaleNameProvider.class);
0702            if (pool.hasProviders()) {
0703                result = pool.getLocalizedObject(
0704                                    LocaleNameGetter.INSTANCE,
0705                                    inLocale, bundle, key,
0706                                    type, code);
0707            }
0708
0709            if (result == null) {
0710                result = bundle.getString(key);
0711            }
0712
0713            if (result != null) {
0714                return result;
0715            }
0716        }
0717        catch (Exception e) {
0718            // just fall through
0719        }
0720        return code;
0721    }
0722
0723    /**
0724     * Returns a name for the locale's variant code that is appropriate for display to the
0725     * user.  If possible, the name will be localized for the default locale.  If the locale
0726     * doesn't specify a variant code, this function returns the empty string.
0727     */
0728    public final String getDisplayVariant() {
0729        return getDisplayVariant(getDefault());
0730    }
0731
0732    /**
0733     * Returns a name for the locale's variant code that is appropriate for display to the
0734     * user.  If possible, the name will be localized for inLocale.  If the locale
0735     * doesn't specify a variant code, this function returns the empty string.
0736     *
0737     * @exception NullPointerException if <code>inLocale</code> is <code>null</code>
0738     */
0739    public String getDisplayVariant(Locale inLocale) {
0740        if (variant.length() == 0)
0741            return "";
0742
0743        OpenListResourceBundle bundle = LocaleData.getLocaleNames(inLocale);
0744
0745        String names[] = getDisplayVariantArray(bundle, inLocale);
0746
0747        // Get the localized patterns for formatting a list, and use
0748        // them to format the list.
0749        String listPattern = null;
0750        String listCompositionPattern = null;
0751        try {
0752            listPattern = bundle.getString("ListPattern");
0753            listCompositionPattern = bundle.getString("ListCompositionPattern");
0754        } catch (MissingResourceException e) {
0755        }
0756        return formatList(names, listPattern, listCompositionPattern);
0757    }
0758
0759    /**
0760     * Returns a name for the locale that is appropriate for display to the
0761     * user.  This will be the values returned by getDisplayLanguage(), getDisplayCountry(),
0762     * and getDisplayVariant() assembled into a single string.  The display name will have
0763     * one of the following forms:<p><blockquote>
0764     * language (country, variant)<p>
0765     * language (country)<p>
0766     * language (variant)<p>
0767     * country (variant)<p>
0768     * language<p>
0769     * country<p>
0770     * variant<p></blockquote>
0771     * depending on which fields are specified in the locale.  If the language, country,
0772     * and variant fields are all empty, this function returns the empty string.
0773     */
0774    public final String getDisplayName() {
0775        return getDisplayName(getDefault());
0776    }
0777
0778    /**
0779     * Returns a name for the locale that is appropriate for display to the
0780     * user.  This will be the values returned by getDisplayLanguage(), getDisplayCountry(),
0781     * and getDisplayVariant() assembled into a single string.  The display name will have
0782     * one of the following forms:<p><blockquote>
0783     * language (country, variant)<p>
0784     * language (country)<p>
0785     * language (variant)<p>
0786     * country (variant)<p>
0787     * language<p>
0788     * country<p>
0789     * variant<p></blockquote>
0790     * depending on which fields are specified in the locale.  If the language, country,
0791     * and variant fields are all empty, this function returns the empty string.
0792     *
0793     * @exception NullPointerException if <code>inLocale</code> is <code>null</code>
0794     */
0795    public String getDisplayName(Locale inLocale) {
0796        OpenListResourceBundle bundle = LocaleData.getLocaleNames(inLocale);
0797
0798        String languageName = getDisplayLanguage(inLocale);
0799        String countryName = getDisplayCountry(inLocale);
0800        String[] variantNames = getDisplayVariantArray(bundle, inLocale);
0801
0802        // Get the localized patterns for formatting a display name.
0803        String displayNamePattern = null;
0804        String listPattern = null;
0805        String listCompositionPattern = null;
0806        try {
0807            displayNamePattern = bundle.getString("DisplayNamePattern");
0808            listPattern = bundle.getString("ListPattern");
0809            listCompositionPattern = bundle.getString("ListCompositionPattern");
0810        } catch (MissingResourceException e) {
0811        }
0812
0813        // The display name consists of a main name, followed by qualifiers.
0814        // Typically, the format is "MainName (Qualifier, Qualifier)" but this
0815        // depends on what pattern is stored in the display locale.
0816        String   mainName       = null;
0817        String[] qualifierNames = null;
0818
0819        // The main name is the language, or if there is no language, the country.
0820        // If there is neither language nor country (an anomalous situation) then
0821        // the display name is simply the variant's display name.
0822        if (languageName.length() != 0) {
0823            mainName = languageName;
0824            if (countryName.length() != 0) {
0825                qualifierNames = new String[variantNames.length + 1];
0826                System.arraycopy(variantNames, 0, qualifierNames, 1, variantNames.length);
0827                qualifierNames[0] = countryName;
0828            }
0829            else qualifierNames = variantNames;
0830        }
0831        else if (countryName.length() != 0) {
0832            mainName = countryName;
0833            qualifierNames = variantNames;
0834        }
0835        else {
0836            return formatList(variantNames, listPattern, listCompositionPattern);
0837        }
0838
0839        // Create an array whose first element is the number of remaining
0840        // elements.  This serves as a selector into a ChoiceFormat pattern from
0841        // the resource.  The second and third elements are the main name and
0842        // the qualifier; if there are no qualifiers, the third element is
0843        // unused by the format pattern.
0844        Object[] displayNames = {
0845            new Integer(qualifierNames.length != 0 ? 2 : 1),
0846            mainName,
0847            // We could also just call formatList() and have it handle the empty
0848            // list case, but this is more efficient, and we want it to be
0849            // efficient since all the language-only locales will not have any
0850            // qualifiers.
0851            qualifierNames.length != 0 ? formatList(qualifierNames, listPattern, listCompositionPattern) : null
0852        };
0853
0854        if (displayNamePattern != null) {
0855            return new MessageFormat(displayNamePattern).format(displayNames);
0856        }
0857        else {
0858            // If we cannot get the message format pattern, then we use a simple
0859            // hard-coded pattern.  This should not occur in practice unless the
0860            // installation is missing some core files (FormatData etc.).
0861            StringBuilder result = new StringBuilder();
0862            result.append((String)displayNames[1]);
0863            if (displayNames.length > 2) {
0864                result.append(" (");
0865                result.append((String)displayNames[2]);
0866                result.append(')');
0867            }
0868            return result.toString();
0869        }
0870    }
0871
0872    /**
0873     * Overrides Cloneable
0874     */
0875    public Object clone()
0876    {
0877        try {
0878            Locale that = (Locale)super.clone();
0879            return that;
0880        } catch (CloneNotSupportedException e) {
0881            throw new InternalError();
0882        }
0883    }
0884
0885    /**
0886     * Override hashCode.
0887     * Since Locales are often used in hashtables, caches the value
0888     * for speed.
0889     */
0890    public int hashCode() {
0891        int hc = hashCodeValue;
0892        if (hc == 0) {
0893	    hc = (language.hashCode() << 8) ^ country.hashCode() ^ (variant.hashCode() << 4);
0894            hashCodeValue = hc;
0895        }
0896        return hc;
0897    }
0898
0899    // Overrides
0900
0901    /**
0902     * Returns true if this Locale is equal to another object.  A Locale is
0903     * deemed equal to another Locale with identical language, country,
0904     * and variant, and unequal to all other objects.
0905     *
0906     * @return true if this Locale is equal to the specified object.
0907     */
0908
0909    public boolean equals(Object obj) {
0910        if (this == obj)                      // quick check
0911            return true;
0912        if (!(obj instanceof Locale))
0913            return false;
0914        Locale other = (Locale) obj;
0915	return language == other.language
0916            && country == other.country
0917            && variant == other.variant;
0918    }
0919
0920    // ================= privates =====================================
0921
0922    // XXX instance and class variables. For now keep these separate, since it is
0923    // faster to match. Later, make into single string.
0924
0925    /**
0926     * @serial
0927     * @see #getLanguage
0928     */
0929    private final String language;
0930
0931    /**
0932     * @serial
0933     * @see #getCountry
0934     */
0935    private final String country;
0936
0937    /**
0938     * @serial
0939     * @see #getVariant
0940     */
0941    private final String variant;
0942
0943    /**
0944     * Placeholder for the object's hash code.  Always -1.
0945     * @serial
0946     */
0947    private volatile int hashcode = -1;        // lazy evaluate
0948
0949    /**
0950     * Calculated hashcode to fix 4518797.
0951     */
0952    private transient volatile int hashCodeValue = 0;
0953
0954    private static Locale defaultLocale = null;
0955
0956    /**
0957     * Return an array of the display names of the variant.
0958     * @param bundle the ResourceBundle to use to get the display names
0959     * @return an array of display names, possible of zero length.
0960     */
0961    private String[] getDisplayVariantArray(OpenListResourceBundle bundle, Locale inLocale) {
0962        // Split the variant name into tokens separated by '_'.
0963        StringTokenizer tokenizer = new StringTokenizer(variant, "_");
0964        String[] names = new String[tokenizer.countTokens()];
0965
0966        // For each variant token, lookup the display name.  If
0967        // not found, use the variant name itself.
0968        for (int i=0; i<names.length; ++i) {
0969            names[i] = getDisplayString(tokenizer.nextToken(), 
0970                                inLocale, DISPLAY_VARIANT); 
0971        }
0972
0973        return names;
0974    }
0975
0976    /**
0977     * Format a list using given pattern strings.
0978     * If either of the patterns is null, then a the list is
0979     * formatted by concatenation with the delimiter ','.
0980     * @param stringList the list of strings to be formatted.
0981     * @param listPattern should create a MessageFormat taking 0-3 arguments
0982     * and formatting them into a list.
0983     * @param listCompositionPattern should take 2 arguments
0984     * and is used by composeList.
0985     * @return a string representing the list.
0986     */
0987    private static String formatList(String[] stringList, String listPattern, String listCompositionPattern) {
0988        // If we have no list patterns, compose the list in a simple,
0989        // non-localized way.
0990        if (listPattern == null || listCompositionPattern == null) {
0991            StringBuffer result = new StringBuffer();
0992            for (int i=0; i<stringList.length; ++i) {
0993                if (i>0) result.append(',');
0994                result.append(stringList[i]);
0995            }
0996            return result.toString();
0997        }
0998
0999        // Compose the list down to three elements if necessary
1000        if (stringList.length > 3) {
1001            MessageFormat format = new MessageFormat(listCompositionPattern);
1002            stringList = composeList(format, stringList);
1003        }
1004
1005        // Rebuild the argument list with the list length as the first element
1006        Object[] args = new Object[stringList.length + 1];
1007        System.arraycopy(stringList, 0, args, 1, stringList.length);
1008        args[0] = new Integer(stringList.length);
1009
1010        // Format it using the pattern in the resource
1011        MessageFormat format = new MessageFormat(listPattern);
1012        return format.format(args);
1013    }
1014
1015    /**
1016     * Given a list of strings, return a list shortened to three elements.
1017     * Shorten it by applying the given format to the first two elements
1018     * recursively.
1019     * @param format a format which takes two arguments
1020     * @param list a list of strings
1021     * @return if the list is three elements or shorter, the same list;
1022     * otherwise, a new list of three elements.
1023     */
1024    private static String[] composeList(MessageFormat format, String[] list) {
1025        if (list.length <= 3) return list;
1026
1027        // Use the given format to compose the first two elements into one
1028        String[] listItems = { list[0], list[1] };
1029        String newItem = format.format(listItems);
1030
1031        // Form a new list one element shorter
1032        String[] newList = new String[list.length-1];
1033        System.arraycopy(list, 2, newList, 1, newList.length-1);
1034        newList[0] = newItem;
1035
1036        // Recurse
1037        return composeList(format, newList);
1038    }
1039
1040    /**
1041     * Replace the deserialized Locale object with a newly
1042     * created object. Newer language codes are replaced with older ISO 
1043     * codes. The country and variant codes are replaced with internalized 
1044     * String copies. 
1045     */
1046    private Object readResolve() throws java.io.ObjectStreamException {
1047        return getInstance(language, country, variant);
1048    }
1049
1050    private static volatile String[] isoLanguages = null;
1051
1052    private static volatile String[] isoCountries = null;
1053
1054    /*
1055     * Locale needs its own, locale insensitive version of toLowerCase to
1056     * avoid circularity problems between Locale and String.
1057     * The most straightforward algorithm is used. Look at optimizations later.
1058     */
1059    private String toLowerCase(String str) {
1060	char[] buf = new char[str.length()];
1061        for (int i = 0; i < buf.length; i++) {
1062	    buf[i] = Character.toLowerCase(str.charAt(i));
1063        }
1064        return new String( buf );
1065    }
1066
1067    /*
1068     * Locale needs its own, locale insensitive version of toUpperCase to
1069     * avoid circularity problems between Locale and String.
1070     * The most straightforward algorithm is used. Look at optimizations later.
1071     */
1072    private String toUpperCase(String str) {
1073	char[] buf = new char[str.length()];
1074        for (int i = 0; i < buf.length; i++) {
1075	    buf[i] = Character.toUpperCase(str.charAt(i));
1076        }
1077        return new String( buf );
1078    }
1079
1080    private String convertOldISOCodes(String language) { 
1081        // we accept both the old and the new ISO codes for the languages whose ISO 
1082        // codes have changed, but we always store the OLD code, for backward compatibility 
1083        language = toLowerCase(language).intern(); 
1084        if (language == "he") { 
1085            return "iw"; 
1086        } else if (language == "yi") { 
1087            return "ji"; 
1088        } else if (language == "id") { 
1089            return "in"; 
1090        } else { 
1091            return language; 
1092        }
1093    }
1094
1095    /**
1096     * Obtains a localized locale names from a LocaleNameProvider
1097     * implementation.
1098     */
1099    private static class LocaleNameGetter 
1100        implements LocaleServiceProviderPool.LocalizedObjectGetter<LocaleNameProvider, String> {
1101        private static final LocaleNameGetter INSTANCE = new LocaleNameGetter();
1102
1103        public String getObject(LocaleNameProvider localeNameProvider,
1104                                Locale locale, 
1105                                String key,
1106                                Object... params) {
1107            assert params.length == 2;
1108            int type = (Integer)params[0];
1109            String code = (String)params[1];
1110
1111            switch(type) {
1112            case DISPLAY_LANGUAGE:
1113		return localeNameProvider.getDisplayLanguage(code, locale);
1114            case DISPLAY_COUNTRY:
1115		return localeNameProvider.getDisplayCountry(code, locale);
1116            case DISPLAY_VARIANT:
1117		return localeNameProvider.getDisplayVariant(code, locale);
1118            default:
1119                assert false; // shouldn't happen
1120            }
1121
1122            return null;
1123        }
1124    }
1125}