FileDocCategorySizeDatePackage
Locale.javaAPI DocAndroid 1.5 API32111Wed May 06 22:41:04 BST 2009java.util

Locale

public final class Locale extends Object implements Serializable, Cloneable
{@code Locale} represents a language/country/variant combination. It is an identifier which dictates particular conventions for the presentation of information. The language codes are two letter lowercase codes as defined by ISO-639. The country codes are three letter uppercase codes as defined by ISO-3166. The variant codes are unspecified.
see
ResourceBundle
since
Android 1.0

Fields Summary
private static final long
serialVersionUID
private static Locale[]
availableLocales
private static Locale
defaultLocale
public static final Locale
CANADA
Locale constant for en_CA.
public static final Locale
CANADA_FRENCH
Locale constant for fr_CA.
public static final Locale
CHINA
Locale constant for zh_CN.
public static final Locale
CHINESE
Locale constant for zh.
public static final Locale
ENGLISH
Locale constant for en.
public static final Locale
FRANCE
Locale constant for fr_FR.
public static final Locale
FRENCH
Locale constant for fr.
public static final Locale
GERMAN
Locale constant for de.
public static final Locale
GERMANY
Locale constant for de_DE.
public static final Locale
ITALIAN
Locale constant for it.
public static final Locale
ITALY
Locale constant for it_IT.
public static final Locale
JAPAN
Locale constant for ja_JP.
public static final Locale
JAPANESE
Locale constant for ja.
public static final Locale
KOREA
Locale constant for ko_KR.
public static final Locale
KOREAN
Locale constant for ko.
public static final Locale
PRC
Locale constant for zh_CN.
public static final Locale
SIMPLIFIED_CHINESE
Locale constant for zh_CN.
public static final Locale
TAIWAN
Locale constant for zh_TW.
public static final Locale
TRADITIONAL_CHINESE
Locale constant for zh_TW.
public static final Locale
UK
Locale constant for en_GB.
public static final Locale
US
Locale constant for en_US.
private static final PropertyPermission
setLocalePermission
private transient String
countryCode
private transient String
languageCode
private transient String
variantCode
private static final ObjectStreamField[]
serialPersistentFields
Constructors Summary
private Locale()
Constructs a default which is used during static initialization of the default for the platform.

        languageCode = "en"; //$NON-NLS-1$
        countryCode = "US"; //$NON-NLS-1$
        variantCode = ""; //$NON-NLS-1$
public Locale(String language)
Constructs a new {@code Locale} using the specified language.

param
language the language this {@code Locale} represents.
since
Android 1.0

        this(language, "", "");  //$NON-NLS-1$//$NON-NLS-2$
public Locale(String language, String country)
Constructs a new {@code Locale} using the specified language and country codes.

param
language the language this {@code Locale} represents.
param
country the country this {@code Locale} represents.
since
Android 1.0

        this(language, country, ""); //$NON-NLS-1$
public Locale(String language, String country, String variant)
Constructs a new {@code Locale} using the specified language, country, and variant codes.

param
language the language this {@code Locale} represents.
param
country the country this {@code Locale} represents.
param
variant the variant this {@code Locale} represents.
throws
NullPointerException if {@code language}, {@code country}, or {@code variant} is {@code null}.
since
Android 1.0

        if (language == null || country == null || variant == null) {
            throw new NullPointerException();
        }
        languageCode = Util.toASCIILowerCase(language);
        // Map new language codes to the obsolete language
        // codes so the correct resource bundles will be used.
        if (languageCode.equals("he")) {//$NON-NLS-1$
            languageCode = "iw"; //$NON-NLS-1$
        } else if (languageCode.equals("id")) {//$NON-NLS-1$
            languageCode = "in"; //$NON-NLS-1$
        } else if (languageCode.equals("yi")) {//$NON-NLS-1$
            languageCode = "ji"; //$NON-NLS-1$
        }

        // countryCode is defined in ASCII character set
        countryCode = Util.toASCIIUpperCase(country);

        variantCode = variant;
Methods Summary
public java.lang.Objectclone()
Returns a new {@code Locale} with the same language, country and variant codes as this {@code Locale}.

return
a shallow copy of this {@code Locale}.
see
java.lang.Cloneable
since
Android 1.0

        try {
            return super.clone();
        } catch (CloneNotSupportedException e) {
            return null;
        }
public booleanequals(java.lang.Object object)
Compares the specified object to this {@code Locale} and returns whether they are equal. The object must be an instance of {@code Locale} and have the same language, country and variant.

param
object the object to compare with this object.
return
{@code true} if the specified object is equal to this {@code Locale}, {@code false} otherwise.
see
#hashCode
since
Android 1.0

        if (object == this) {
            return true;
        }
        if (object instanceof Locale) {
            Locale o = (Locale) object;
            return languageCode.equals(o.languageCode)
                    && countryCode.equals(o.countryCode)
                    && variantCode.equals(o.variantCode);
        }
        return false;
static java.util.Locale[]find()

        String[] locales = Resources.getAvailableLocales();
        ArrayList<Locale> temp = new ArrayList<Locale>();
        for (int i = 0; i < locales.length; i++) {
            String s = locales[i];
            int first = s.indexOf('_");
            int second = s.indexOf('_", first + 1);
            
            if (first == -1) {
                // Language only
                temp.add(new Locale(s));
            } else if (second == -1) {
                // Language and country
                temp.add(new Locale(s.substring(0, first), s.substring(first + 1)));
            } else {
                // Language and country and variant
                temp.add(new Locale(s.substring(0, first), s.substring(first + 1, second), s.substring(second + 1)));
            }
        }
        Locale[] result = new Locale[temp.size()];
        return temp.toArray(result);
public static java.util.Locale[]getAvailableLocales()
Gets the list of installed {@code Locale}. At least a {@code Locale} that is equal to {@code Locale.US} must be contained in this array.

return
an array of {@code Locale}s.
since
Android 1.0

        if (availableLocales == null) {
            // BEGIN android-removed
            // availableLocales = AccessController
            //         .doPrivileged(new PrivilegedAction<Locale[]>() {
            //             public Locale[] run() {
            //                 return find("org/apache/harmony/luni/internal/locale/Locale_"); //$NON-NLS-1$
            //             }
            //         });
            // END android-removed
            
            // BEGIN android-added
            availableLocales = find();
            // END android-added
        }
        return availableLocales.clone();
static java.util.ResourceBundlegetBundle(java.lang.String clName, java.util.Locale locale)

        return AccessController.doPrivileged(new PrivilegedAction<ResourceBundle>() {
                    public ResourceBundle run() {
                        return ResourceBundle.getBundle("org.apache.harmony.luni.internal.locale." //$NON-NLS-1$
                                + clName, locale);
                    }
                });
public java.lang.StringgetCountry()
Gets the country code for this {@code Locale} or an empty string of no country was set.

return
a country code.
since
Android 1.0

        return countryCode;
public static java.util.LocalegetDefault()
Gets the default {@code Locale}.

return
the default {@code Locale}.
since
Android 1.0

        return defaultLocale;
public final java.lang.StringgetDisplayCountry()
Gets the full country name in the default {@code Locale} for the country code of this {@code Locale}. If there is no matching country name, the country code is returned.

return
a country name.
since
Android 1.0

        return getDisplayCountry(getDefault());
public java.lang.StringgetDisplayCountry(java.util.Locale locale)
Gets the full country name in the specified {@code Locale} for the country code of this {@code Locale}. If there is no matching country name, the country code is returned.

param
locale the {@code Locale} for which the display name is retrieved.
return
a country name.
since
Android 1.0

        if (countryCode.length() == 0) {
            return countryCode;
        }
        try {
            // First try the specified locale
            ResourceBundle bundle = getBundle("Country", locale); //$NON-NLS-1$
            // BEGIN android-changed
            String result = bundle.getString(this.toString());
            // END android-changed
            if (result != null) {
                return result;
            }
            // Now use the default locale
            if (locale != Locale.getDefault()) {
                bundle = getBundle("Country", Locale.getDefault()); //$NON-NLS-1$
            }
            return bundle.getString(countryCode);
        } catch (MissingResourceException e) {
            return countryCode;
        }
public final java.lang.StringgetDisplayLanguage()
Gets the full language name in the default {@code Locale} for the language code of this {@code Locale}. If there is no matching language name, the language code is returned.

return
a language name.
since
Android 1.0

        return getDisplayLanguage(getDefault());
public java.lang.StringgetDisplayLanguage(java.util.Locale locale)
Gets the full language name in the specified {@code Locale} for the language code of this {@code Locale}. If there is no matching language name, the language code is returned.

param
locale the {@code Locale} for which the display name is retrieved.
return
a language name.
since
Android 1.0

        if (languageCode.length() == 0) {
            return languageCode;
        }
        try {
            // First try the specified locale
            ResourceBundle bundle = getBundle("Language", locale); //$NON-NLS-1$
            // BEGIN android-changed
            String result = bundle.getString(this.toString());
            // END android-changed
            if (result != null) {
                return result;
            }
            // Now use the default locale
            if (locale != Locale.getDefault()) {
                bundle = getBundle("Language", Locale.getDefault()); //$NON-NLS-1$
            }
            return bundle.getString(languageCode);
        } catch (MissingResourceException e) {
            return languageCode;
        }
public final java.lang.StringgetDisplayName()
Gets the full language, country, and variant names in the default {@code Locale} for the codes of this {@code Locale}.

return
a {@code Locale} name.
since
Android 1.0

        return getDisplayName(getDefault());
public java.lang.StringgetDisplayName(java.util.Locale locale)
Gets the full language, country, and variant names in the specified Locale for the codes of this {@code Locale}.

param
locale the {@code Locale} for which the display name is retrieved.
return
a {@code Locale} name.
since
Android 1.0

        int count = 0;
        StringBuffer buffer = new StringBuffer();
        if (languageCode.length() > 0) {
            buffer.append(getDisplayLanguage(locale));
            count++;
        }
        if (countryCode.length() > 0) {
            if (count == 1) {
                buffer.append(" ("); //$NON-NLS-1$
            }
            buffer.append(getDisplayCountry(locale));
            count++;
        }
        if (variantCode.length() > 0) {
            if (count == 1) {
                buffer.append(" ("); //$NON-NLS-1$
            } else if (count == 2) {
                buffer.append(","); //$NON-NLS-1$
            }
            buffer.append(getDisplayVariant(locale));
            count++;
        }
        if (count > 1) {
            buffer.append(")"); //$NON-NLS-1$
        }
        return buffer.toString();
public final java.lang.StringgetDisplayVariant()
Gets the full variant name in the default {@code Locale} for the variant code of this {@code Locale}. If there is no matching variant name, the variant code is returned.

return
a variant name.
since
Android 1.0

        return getDisplayVariant(getDefault());
public java.lang.StringgetDisplayVariant(java.util.Locale locale)
Gets the full variant name in the specified {@code Locale} for the variant code of this {@code Locale}. If there is no matching variant name, the variant code is returned.

param
locale the {@code Locale} for which the display name is retrieved.
return
a variant name.
since
Android 1.0

        if (variantCode.length() == 0) {
            return variantCode;
        }
// BEGIN android-removed
//         ResourceBundle bundle;
//         try {
//             bundle = getBundle("Variant", locale); //$NON-NLS-1$
//         } catch (MissingResourceException e) {
//             return variantCode.replace('_', ',');
//         }
// 
//         StringBuffer result = new StringBuffer();
//         StringTokenizer tokens = new StringTokenizer(variantCode, "_"); //$NON-NLS-1$
//         while (tokens.hasMoreTokens()) {
//             String code, variant = tokens.nextToken();
//             try {
//                 code = bundle.getString(variant);
//             } catch (MissingResourceException e) {
//                 code = variant;
//             }
//             result.append(code);
//             if (tokens.hasMoreTokens()) {
//                 result.append(',');
//             }
//         }
//         return result.toString();
// END android-removed
// BEGIN android-added
        try {
            // First try the specified locale
            ResourceBundle bundle = getBundle("Variant", locale); //$NON-NLS-1$
            String result = bundle.getString(this.toString());
            if (result != null) {
                return result;
            }
            // Now use the default locale
            if (locale != Locale.getDefault()) {
                bundle = getBundle("Variant", Locale.getDefault()); //$NON-NLS-1$
            }
            return bundle.getString(variantCode);
        } catch (MissingResourceException e) {
            return variantCode;
        }
// END android-added
public java.lang.StringgetISO3Country()
Gets the three letter ISO country code which corresponds to the country code for this {@code Locale}.

return
a three letter ISO language code.
exception
MissingResourceException when there is no matching three letter ISO country code.
since
Android 1.0

        if (countryCode.length() == 0) {
            return ""; //$NON-NLS-1$
        }
        ResourceBundle bundle = getBundle("ISO3Countries", this); //$NON-NLS-1$
        // BEGIN android-changed
        return bundle.getString(this.toString());
        // END android-changed
public java.lang.StringgetISO3Language()
Gets the three letter ISO language code which corresponds to the language code for this {@code Locale}.

return
a three letter ISO language code.
exception
MissingResourceException when there is no matching three letter ISO language code.
since
Android 1.0

        if (languageCode.length() == 0) {
            return ""; //$NON-NLS-1$
        }
        ResourceBundle bundle = getBundle("ISO3Languages", this); //$NON-NLS-1$
        // BEGIN android-changed
        return bundle.getString(this.toString());
        // END android-changed
public static java.lang.String[]getISOCountries()
Gets the list of two letter ISO country codes which can be used as the country code for a {@code Locale}.

return
an array of strings.
since
Android 1.0

        // BEGIN android-removed
        // ListResourceBundle bundle = new Country();
        // 
        // // To initialize the table
        // Enumeration<String> keys = bundle.getKeys();
        // int size = bundle.table.size();
        // String[] result = new String[size];
        // int index = 0;
        // while (keys.hasMoreElements()) {
        //     String element = keys.nextElement();
        //     result[index++] = element;
        // }
        // return result;
        // END android-removed
        
        // BEGIN android-added
        return Resources.getISOCountries();
        // END android-added
public static java.lang.String[]getISOLanguages()
Gets the list of two letter ISO language codes which can be used as the language code for a {@code Locale}.

return
an array of strings.
since
Android 1.0

        // BEGIN android-removed
        // ListResourceBundle bundle = new Language();
        // Enumeration<String> keys = bundle.getKeys(); // to initialize the table
        // String[] result = new String[bundle.table.size()];
        // int index = 0;
        // while (keys.hasMoreElements()) {
        //     result[index++] = keys.nextElement();
        // }
        // return result;
        // END android-removed
        
        // BEGIN android-added
        return Resources.getISOLanguages();
        // END android-added
public java.lang.StringgetLanguage()
Gets the language code for this {@code Locale} or the empty string of no language was set.

return
a language code.
since
Android 1.0

        return languageCode;
public java.lang.StringgetVariant()
Gets the variant code for this {@code Locale} or an empty {@code String} of no variant was set.

return
a variant code.
since
Android 1.0

        return variantCode;
public synchronized inthashCode()
Returns an integer hash code for the receiver. Objects which are equal return the same value for this method.

return
the receiver's hash.
see
#equals
since
Android 1.0

        return countryCode.hashCode() + languageCode.hashCode()
                + variantCode.hashCode();
private voidreadObject(java.io.ObjectInputStream stream)

        ObjectInputStream.GetField fields = stream.readFields();
        countryCode = (String) fields.get("country", "");  //$NON-NLS-1$//$NON-NLS-2$
        languageCode = (String) fields.get("language", "");  //$NON-NLS-1$//$NON-NLS-2$
        variantCode = (String) fields.get("variant", "");  //$NON-NLS-1$//$NON-NLS-2$
public static synchronized voidsetDefault(java.util.Locale locale)
Sets the default {@code Locale} to the specified {@code Locale}.

param
locale the new default {@code Locale}.
exception
SecurityException if there is a {@code SecurityManager} in place which does not allow this operation.
since
Android 1.0

        if (locale != null) {
            SecurityManager security = System.getSecurityManager();
            if (security != null) {
                security.checkPermission(setLocalePermission);
            }
            defaultLocale = locale;
        } else {
            throw new NullPointerException();
        }
public final java.lang.StringtoString()
Returns the string representation of this {@code Locale}. It consists of the language followed by the country and at the end the variant. They are separated by underscores. If the language is missing the string begins with an underscore. If the country is missing there are 2 underscores between the language and the variant. the variant alone canot be defined without a language and/or a country (in this case this method would return the empty string). Examples: "en", "en_US", "_US", "en__POSIX", "en_US_POSIX"

return
the string representation of this {@code Locale}.
since
Android 1.0

        StringBuilder result = new StringBuilder();
        result.append(languageCode);
        if (countryCode.length() > 0) {
            result.append('_");
            result.append(countryCode);
        }
        if (variantCode.length() > 0 && result.length() > 0 ) {
            if (0 == countryCode.length()) {
                result.append("__"); //$NON-NLS-1$
            } else {
                result.append('_");
            }
            result.append(variantCode);
        }
        return result.toString();
private voidwriteObject(java.io.ObjectOutputStream stream)

 //$NON-NLS-1$

          
        ObjectOutputStream.PutField fields = stream.putFields();
        fields.put("country", countryCode); //$NON-NLS-1$
        fields.put("hashcode", -1); //$NON-NLS-1$
        fields.put("language", languageCode); //$NON-NLS-1$
        fields.put("variant", variantCode); //$NON-NLS-1$
        stream.writeFields();