java.util
Class Locale

java.lang.Object
  extended by 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.country (or user.region), and user.variant, defaulting to "en_US". 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:
1.1
See Also:
ResourceBundle, Format, NumberFormat, Collator, Serialized Form

Field Summary
static Locale CANADA
          Locale which represents the English speaking portion of Canada.
static Locale CANADA_FRENCH
          Locale which represents the French speaking portion of Canada.
static Locale CHINA
          Locale which represents China.
static Locale CHINESE
          Locale which represents the Chinese language.
static Locale ENGLISH
          Locale which represents the English language.
static Locale FRANCE
          Locale which represents France.
static Locale FRENCH
          Locale which represents the French language.
static Locale GERMAN
          Locale which represents the German language.
static Locale GERMANY
          Locale which represents Germany.
static Locale ITALIAN
          Locale which represents the Italian language.
static Locale ITALY
          Locale which represents Italy.
static Locale JAPAN
          Locale which represents Japan.
static Locale JAPANESE
          Locale which represents the Japanese language.
static Locale KOREA
          Locale which represents Korea.
static Locale KOREAN
          Locale which represents the Korean language.
static Locale PRC
          Locale which represents the People's Republic of China.
static Locale ROOT
          The root locale, used as the base case in lookups by locale-sensitive operations.
static Locale SIMPLIFIED_CHINESE
          Locale which represents the Chinese language as used in China.
static Locale TAIWAN
          Locale which represents Taiwan.
static Locale TRADITIONAL_CHINESE
          Locale which represents the Chinese language as used in Taiwan.
static Locale UK
          Locale which represents the United Kingdom.
static Locale US
          Locale which represents the United States.
 
Constructor Summary
Locale(String language)
          Creates a new locale for a language.
Locale(String language, String country)
          Creates a new locale for the given language and country.
Locale(String language, String country, String variant)
          Creates a new locale for the given language and country.
 
Method Summary
 Object clone()
          Does the same as Object.clone() but does not throw a CloneNotSupportedException.
 boolean equals(Object obj)
          Compares two locales.
static Locale[] getAvailableLocales()
          Returns the list of available locales.
 String getCountry()
          Returns the country code of this locale.
static Locale getDefault()
          Returns the default Locale.
 String getDisplayCountry()
          Returns the country name of this locale localized to the default locale.
 String getDisplayCountry(Locale inLocale)
           Gets the name of the country specified by this locale, in a form suitable for display to the user.
 String getDisplayLanguage()
          Gets the country name suitable for display to the user, formatted for the default locale.
 String getDisplayLanguage(Locale inLocale)
           Gets the name of the language specified by this locale, in a form suitable for display to the user.
 String getDisplayName()
          Gets all local components suitable for display to the user, formatted for the default locale.
 String getDisplayName(Locale locale)
          Gets all local components suitable for display to the user, formatted for a specified locale.
 String getDisplayVariant()
          Returns the variant name of this locale localized to the default locale.
 String getDisplayVariant(Locale inLocale)
           Gets the name of the variant specified by this locale, in a form suitable for display to the user.
 String getISO3Country()
          Returns the three-letter ISO country abbrevation of the locale.
 String getISO3Language()
          Returns the three-letter ISO language abbrevation of this locale.
static String[] getISOCountries()
          Returns a list of all 2-letter uppercase country codes as defined in ISO 3166.
static String[] getISOLanguages()
          Returns a list of all 2-letter lowercase language codes as defined in ISO 639 (both old and new variant).
 String getLanguage()
          Returns the language code of this locale.
 String getVariant()
          Returns the variant code of this locale.
 int hashCode()
          Return the hash code for this locale.
static void setDefault(Locale newLocale)
          Changes the default locale.
 String toString()
          Gets the string representation of the current locale.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

ENGLISH

public static final Locale ENGLISH
Locale which represents the English language.


FRENCH

public static final Locale FRENCH
Locale which represents the French language.


GERMAN

public static final Locale GERMAN
Locale which represents the German language.


ITALIAN

public static final Locale ITALIAN
Locale which represents the Italian language.


JAPANESE

public static final Locale JAPANESE
Locale which represents the Japanese language.


KOREAN

public static final Locale KOREAN
Locale which represents the Korean language.


CHINESE

public static final Locale CHINESE
Locale which represents the Chinese language.


SIMPLIFIED_CHINESE

public static final Locale SIMPLIFIED_CHINESE
Locale which represents the Chinese language as used in China.


TRADITIONAL_CHINESE

public static final Locale TRADITIONAL_CHINESE
Locale which represents the Chinese language as used in Taiwan. Same as TAIWAN Locale.


FRANCE

public static final Locale FRANCE
Locale which represents France.


GERMANY

public static final Locale GERMANY
Locale which represents Germany.


ITALY

public static final Locale ITALY
Locale which represents Italy.


JAPAN

public static final Locale JAPAN
Locale which represents Japan.


KOREA

public static final Locale KOREA
Locale which represents Korea.


CHINA

public static final Locale CHINA
Locale which represents China. Same as SIMPLIFIED_CHINESE Locale.


PRC

public static final Locale PRC
Locale which represents the People's Republic of China. Same as CHINA Locale.


TAIWAN

public static final Locale TAIWAN
Locale which represents Taiwan. Same as TRADITIONAL_CHINESE 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.


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.


ROOT

public static final Locale ROOT
The root locale, used as the base case in lookups by locale-sensitive operations.

Constructor Detail

Locale

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

Parameters:
language - lowercase two-letter ISO-639 A2 language code
country - uppercase two-letter ISO-3166 A2 contry code
variant - vendor and browser specific
Throws:
NullPointerException - if any argument is null

Locale

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

Parameters:
language - lowercase two-letter ISO-639 A2 language code
country - uppercase two-letter ISO-3166 A2 country code
Throws:
NullPointerException - if either argument is null

Locale

public Locale(String language)
Creates a new locale for a language.

Parameters:
language - lowercase two-letter ISO-639 A2 language code
Throws:
NullPointerException - if either argument is null
Since:
1.4
Method Detail

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:
the default locale for this virtual machine

setDefault

public static void setDefault(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:
newLocale - the new default locale
Throws:
NullPointerException - if newLocale is null
SecurityException - if permission is denied

getAvailableLocales

public static Locale[] getAvailableLocales()
Returns the list of available locales.

Returns:
the installed locales

getISOCountries

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

Returns:
a list of acceptable country codes

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:
a list of acceptable language codes

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:
language code portion of this locale, or an empty String

getCountry

public String getCountry()
Returns the country code of this locale.

Returns:
country code portion of this locale, or an empty String

getVariant

public String getVariant()
Returns the variant code of this locale.

Returns:
the variant code portion of this locale, or an empty String

toString

public 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".

Overrides:
toString in class Object
Returns:
the string representation of this Locale
See Also:
getDisplayName()

getISO3Language

public String getISO3Language()
Returns the three-letter ISO language abbrevation of this locale.

Throws:
MissingResourceException - if the three-letter code is not known

getISO3Country

public String getISO3Country()
Returns the three-letter ISO country abbrevation of the locale.

Throws:
MissingResourceException - if the three-letter code is not known

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:
the language name of this locale localized to the default locale, with the ISO code as backup

getDisplayLanguage

public String getDisplayLanguage(Locale inLocale)

Gets the name of the language specified by this locale, in a form suitable for display to the user. If possible, the display name will be localized to the specified locale. For example, if the locale instance is Locale.GERMANY, and the specified locale is Locale.UK, the result would be 'German'. Using the German locale would instead give 'Deutsch'. If the display name can not be localized to the supplied locale, it will fall back on other output in the following order:

If the language is unspecified by this locale, then the empty string is returned.

Parameters:
inLocale - the locale to use for formatting the display string.
Returns:
the language name of this locale localized to the given locale, with the default locale, English and the ISO code as backups.
Throws:
NullPointerException - if the supplied locale is null.

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:
the country name of this locale localized to the given locale, with the ISO code as backup

getDisplayCountry

public String getDisplayCountry(Locale inLocale)

Gets the name of the country specified by this locale, in a form suitable for display to the user. If possible, the display name will be localized to the specified locale. For example, if the locale instance is Locale.GERMANY, and the specified locale is Locale.UK, the result would be 'Germany'. Using the German locale would instead give 'Deutschland'. If the display name can not be localized to the supplied locale, it will fall back on other output in the following order:

If the country is unspecified by this locale, then the empty string is returned.

Parameters:
inLocale - the locale to use for formatting the display string.
Returns:
the country name of this locale localized to the given locale, with the default locale, English and the ISO code as backups.
Throws:
NullPointerException - if the supplied locale is null.

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:
the variant code of this locale localized to the given locale, with the ISO code as backup

getDisplayVariant

public String getDisplayVariant(Locale inLocale)

Gets the name of the variant specified by this locale, in a form suitable for display to the user. If possible, the display name will be localized to the specified locale. For example, if the locale instance is a revised variant, and the specified locale is Locale.UK, the result would be 'REVISED'. Using the German locale would instead give 'Revidiert'. If the display name can not be localized to the supplied locale, it will fall back on other output in the following order:

If the variant is unspecified by this locale, then the empty string is returned.

Parameters:
inLocale - the locale to use for formatting the display string.
Returns:
the variant name of this locale localized to the given locale, with the default locale, English and the ISO code as backups.
Throws:
NullPointerException - if the supplied locale is null.

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:
String version of this locale, suitable for display to the user

getDisplayName

public String getDisplayName(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:
locale - locale to use for formatting
Returns:
String version of this locale, suitable for display to the user

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.

Overrides:
clone in class Object
Returns:
the clone
See Also:
Cloneable

hashCode

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

Overrides:
hashCode in class Object
Returns:
the hashcode
See Also:
Object.equals(Object), System.identityHashCode(Object)

equals

public boolean equals(Object obj)
Compares two locales. To be equal, obj must be a Locale with the same language, country, and variant code.

Overrides:
equals in class Object
Parameters:
obj - the other locale
Returns:
true if obj is equal to this
See Also:
Object.hashCode()