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

Author:

Jochen Hoenicke, Paul Fisher, Eric Blake (ebb9@email.byu.edu), Andrew John Hughes (gnu_andrew@member.fsf.org)

See Also:

ResourceBundle, Format, NumberFormat, Collator, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static Locale	ROOT The root locale, used as the base case in lookups by locale-sensitive operations.
static Locale	US Locale which represents the United States.

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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.
static Locale	getFallbackLocale(Locale locale) This method is used by the localized name lookup methods to retrieve the next locale to try.
String	getISO3Country() Returns the three-letter ISO country abbrevation of the locale.
String	getISO3Language() Returns the three-letter ISO language abbrevation of this locale.
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

getClass, notify, notifyAll, wait, wait, wait

Field Detail

ROOT

public static final Locale ROOT

The root locale, used as the base case in lookups by locale-sensitive operations.

US

public static final Locale US

Locale which represents the United States.

Constructor Detail

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

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,
              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

Method Detail

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:

the clone

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

getAvailableLocales

public static Locale[] getAvailableLocales()

Returns the list of available locales.

Returns:

the installed locales

getCountry

public String getCountry()

Returns the country code of this locale.

Returns:

country code portion of this locale, or an empty String

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

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:

• the display name in the default locale
• the display name in English
• the ISO code

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.

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:

• the display name in the default locale
• the display name in English
• the ISO code

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.

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

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:

• the display name in the default locale
• the display name in English
• the ISO code

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.

getFallbackLocale

public static Locale getFallbackLocale(Locale locale)

This method is used by the localized name lookup methods to retrieve the next locale to try. The next locale is derived from the supplied locale by applying the first applicable rule from the following:

1. If the variant contains a '_', then this and everything following it is trimmed.
2. If the variant is non-empty, it is converted to an empty string.
3. If the country is non-empty, it is converted to an empty string.
4. If the language is non-empty, it is converted to an empty string (forming ROOT)

The base fallback locale is ROOT.

Parameters:

locale - the locale for which a localized piece of data could not be obtained.

Returns:

the next fallback locale to try.

getISO3Country

public String getISO3Country()

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

Throws:

MissingResourceException - if the three-letter code is not known

getISO3Language

public String getISO3Language()

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

Throws:

MissingResourceException - if the three-letter code is not known

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

getVariant

public String getVariant()

Returns the variant code of this locale.

Returns:

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

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

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

java.lang.SecurityException - if permission is denied

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()