Index (Frames) | Index (No Frames) | Package | Package Tree | Tree
java.util

Class Locale

java.lang.Object
|
+--java.util.Locale

All Implemented Interfaces:

Serializable, Cloneable


public final class Locale

extends Object

implements Serializable, Cloneable

Locales represent a specific country and culture. Classes which can be passed a Locale object tailor their information for a given locale. For instance, currency number formatting is handled differently for the USA and France.

Locales are made up of a language code, a country code, and an optional set of variant strings. Language codes are represented by ISO 639:1988 w/ additions from ISO 639/RA Newsletter No. 1/1989 and a decision of the Advisory Committee of ISO/TC39 on August 8, 1997.

Country codes are represented by ISO 3166. Variant strings are vendor and browser specific. Standard variant strings include "POSIX" for POSIX, "WIN" for MS-Windows, and "MAC" for Macintosh. When there is more than one variant string, they must be separated by an underscore (U+005F).

The default locale is determined by the values of the system properties user.language, user.region, and user.variant, defaulting to "en". Note that the locale does NOT contain the conversion and formatting capabilities (for that, use ResourceBundle and java.text). Rather, it is an immutable tag object for identifying a given locale, which is referenced by these other classes when they must make locale-dependent decisions.

Since:Authors:See Also:

Field Summary

static java.util.LocaleCANADA

Locale which represents the English speaking portion of Canada.
static java.util.LocaleCANADA_FRENCH

Locale which represents the French speaking portion of Canada.
static java.util.LocaleCHINA

Locale which represents China.
static java.util.LocaleCHINESE

Locale which represents the Chinese language.
static java.util.LocaleENGLISH

Locale which represents the English language.
static java.util.LocaleFRANCE

Locale which represents France.
static java.util.LocaleFRENCH

Locale which represents the French language.
static java.util.LocaleGERMAN

Locale which represents the German language.
static java.util.LocaleGERMANY

Locale which represents Germany.
static java.util.LocaleITALIAN

Locale which represents the Italian language.
static java.util.LocaleITALY

Locale which represents Italy.
static java.util.LocaleJAPAN

Locale which represents Japan.
static java.util.LocaleJAPANESE

Locale which represents the Japanese language.
static java.util.LocaleKOREA

Locale which represents Korea.
static java.util.LocaleKOREAN

Locale which represents the Korean language.
static java.util.LocalePRC

Locale which represents the People's Republic of China.
static java.util.LocaleSIMPLIFIED_CHINESE

Locale which represents the Chinese language as used in China.
static java.util.LocaleTAIWAN

Locale which represents Taiwan.
static java.util.LocaleTRADITIONAL_CHINESE

Locale which represents the Chinese language as used in Taiwan.
static java.util.LocaleUK

Locale which represents the United Kingdom.
static java.util.LocaleUS

Locale which represents the United States.

Constructor Summary

Locale(java.lang.String language, java.lang.String country, java.lang.String variant)

Creates a new locale for the given language and country.
Locale(java.lang.String language, java.lang.String country)

Creates a new locale for the given language and country.
Locale(java.lang.String language)

Creates a new locale for a language.

Method Summary

java.lang.Objectclone()

Does the same as Object.clone() but does not throw a CloneNotSupportedException.
booleanequals(java.lang.Object obj)

Compares two locales.
static java.util.Locale[]getAvailableLocales()

Returns the list of available locales.
java.lang.StringgetCountry()

Returns the country code of this locale.
static java.util.LocalegetDefault()

Returns the default Locale.
java.lang.StringgetDisplayCountry()

Returns the country name of this locale localized to the default locale.
java.lang.StringgetDisplayCountry(java.util.Locale locale)

Gets the country name suitable for display to the user, formatted for a specified locale.
java.lang.StringgetDisplayLanguage()

Gets the country name suitable for display to the user, formatted for the default locale.
java.lang.StringgetDisplayLanguage(java.util.Locale locale)

Gets the language name suitable for display to the user, formatted for a specified locale.
java.lang.StringgetDisplayName()

Gets all local components suitable for display to the user, formatted for the default locale.
java.lang.StringgetDisplayName(java.util.Locale locale)

Gets all local components suitable for display to the user, formatted for a specified locale.
java.lang.StringgetDisplayVariant()

Returns the variant name of this locale localized to the default locale.
java.lang.StringgetDisplayVariant(java.util.Locale locale)

Returns the variant name of this locale localized to the given locale.
java.lang.StringgetISO3Country()

Returns the three-letter ISO country abbrevation of the locale.
java.lang.StringgetISO3Language()

Returns the three-letter ISO language abbrevation of this locale.
static java.lang.String[]getISOCountries()

Returns a list of all 2-letter uppercase country codes as defined in ISO 3166.
static java.lang.String[]getISOLanguages()

Returns a list of all 2-letter lowercase language codes as defined in ISO 639 (both old and new variant).
java.lang.StringgetLanguage()

Returns the language code of this locale.
java.lang.StringgetVariant()

Returns the variant code of this locale.
synchronized inthashCode()

Return the hash code for this locale.
static voidsetDefault(java.util.Locale newLocale)

Changes the default locale.
java.lang.StringtoString()

Gets the string representation of the current locale.

Field Details

CANADA

public static final Locale CANADA

Locale which represents the English speaking portion of Canada.


CANADA_FRENCH

public static final Locale CANADA_FRENCH

Locale which represents the French speaking portion of Canada.


CHINA

public static final Locale CHINA

Locale which represents China. Same as SIMPLIFIED_CHINESE Locale.


CHINESE

public static final Locale CHINESE

Locale which represents the Chinese language.


ENGLISH

public static final Locale ENGLISH

Locale which represents the English language.


FRANCE

public static final Locale FRANCE

Locale which represents France.


FRENCH

public static final Locale FRENCH

Locale which represents the French language.


GERMAN

public static final Locale GERMAN

Locale which represents the German language.


GERMANY

public static final Locale GERMANY

Locale which represents Germany.


ITALIAN

public static final Locale ITALIAN

Locale which represents the Italian language.


ITALY

public static final Locale ITALY

Locale which represents Italy.


JAPAN

public static final Locale JAPAN

Locale which represents Japan.


JAPANESE

public static final Locale JAPANESE

Locale which represents the Japanese language.


KOREA

public static final Locale KOREA

Locale which represents Korea.


KOREAN

public static final Locale KOREAN

Locale which represents the Korean language.


PRC

public static final Locale PRC

Locale which represents the People's Republic of China. Same as CHINA Locale.


SIMPLIFIED_CHINESE

public static final Locale SIMPLIFIED_CHINESE

Locale which represents the Chinese language as used in China.


TAIWAN

public static final Locale TAIWAN

Locale which represents Taiwan. Same as TRADITIONAL_CHINESE Locale.


TRADITIONAL_CHINESE

public static final Locale TRADITIONAL_CHINESE

Locale which represents the Chinese language as used in Taiwan. Same as TAIWAN Locale.


UK

public static final Locale UK

Locale which represents the United Kingdom.


US

public static final Locale US

Locale which represents the United States.


Constructor Details

Locale

public Locale(java.lang.String language)

Creates a new locale for a language.

Since:Parameters:

Throws:


Locale

public Locale(java.lang.String language, java.lang.String country)

Creates a new locale for the given language and country.

Parameters:

Throws:


Locale

public Locale(java.lang.String language, java.lang.String country, java.lang.String variant)

Creates a new locale for the given language and country.

Parameters:

Throws:


Method Details

clone

public Object clone()

Does the same as Object.clone() but does not throw a CloneNotSupportedException. Why anyone would use this method is a secret to me, since this class is immutable.

Returns:


equals

public boolean equals(java.lang.Object obj)

Compares two locales. To be equal, obj must be a Locale with the same language, country, and variant code.

Parameters:

Returns:


getAvailableLocales

public static Locale[] getAvailableLocales()

Returns the list of available locales.

Returns:


getCountry

public String getCountry()

Returns the country code of this locale.

Returns:


getDefault

public static Locale getDefault()

Returns the default Locale. The default locale is generally once set on start up and then never changed. Normally you should use this locale for everywhere you need a locale. The initial setting matches the default locale, the user has chosen.

Returns:


getDisplayCountry

public String getDisplayCountry()

Returns the country name of this locale localized to the default locale. If the localized is not found, the ISO code is returned. This has the same effect as
 getDisplayCountry(Locale.getDefault());
 

Returns:


getDisplayCountry

public String getDisplayCountry(java.util.Locale locale)

Gets the country name suitable for display to the user, formatted for a specified locale.

Parameters:

Returns:


getDisplayLanguage

public String getDisplayLanguage()

Gets the country name suitable for display to the user, formatted for the default locale. This has the same effect as
 getDisplayLanguage(Locale.getDefault());
 

Returns:


getDisplayLanguage

public String getDisplayLanguage(java.util.Locale locale)

Gets the language name suitable for display to the user, formatted for a specified locale.

Parameters:

Returns:


getDisplayName

public String getDisplayName()

Gets all local components suitable for display to the user, formatted for the default locale. For the language component, getDisplayLanguage is called. For the country component, getDisplayCountry is called. For the variant set component, getDisplayVariant is called.

The returned String will be one of the following forms:

 language (country, variant)
 language (country)
 language (variant)
 country (variant)
 language
 country
 variant
 

Returns:


getDisplayName

public String getDisplayName(java.util.Locale locale)

Gets all local components suitable for display to the user, formatted for a specified locale. For the language component, getDisplayLanguage(Locale) is called. For the country component, getDisplayCountry(Locale) is called. For the variant set component, getDisplayVariant(Locale) is called.

The returned String will be one of the following forms:

 language (country, variant)
 language (country)
 language (variant)
 country (variant)
 language
 country
 variant
 

Parameters:

Returns:


getDisplayVariant

public String getDisplayVariant()

Returns the variant name of this locale localized to the default locale. If the localized is not found, the variant code itself is returned. This has the same effect as
 getDisplayVariant(Locale.getDefault());
 

Returns:


getDisplayVariant

public String getDisplayVariant(java.util.Locale locale)

Returns the variant name of this locale localized to the given locale. If the localized is not found, the variant code itself is returned.

Parameters:

Returns:


getISO3Country

public String getISO3Country()

Returns the three-letter ISO country abbrevation of the locale.

Throws:


getISO3Language

public String getISO3Language()

Returns the three-letter ISO language abbrevation of this locale.

Throws:


getISOCountries

public static String[] getISOCountries()

Returns a list of all 2-letter uppercase country codes as defined in ISO 3166.

Returns:


getISOLanguages

public static String[] getISOLanguages()

Returns a list of all 2-letter lowercase language codes as defined in ISO 639 (both old and new variant).

Returns:


getLanguage

public String getLanguage()

Returns the language code of this locale. Some language codes have changed as ISO 639 has evolved; this returns the old name, even if you built the locale with the new one.

Returns:


getVariant

public String getVariant()

Returns the variant code of this locale.

Returns:


hashCode

public synchronized int hashCode()

Return the hash code for this locale. The hashcode is the logical xor of the hash codes of the language, the country and the variant. The hash code is precomputed, since Locales are often used in hash tables.

Returns:


setDefault

public static void setDefault(java.util.Locale newLocale)

Changes the default locale. Normally only called on program start up. Note that this doesn't change the locale for other programs. This has a security check, PropertyPermission("user.language", "write"), because of its potential impact to running code.

Parameters:

Throws:


toString

public final String toString()

Gets the string representation of the current locale. This consists of the language, the country, and the variant, separated by an underscore. The variant is listed only if there is a language or country. Examples: "en", "de_DE", "_GB", "en_US_WIN", "de__POSIX", "fr__MAC".

Returns:

See Also: