All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class java.util.Locale

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

public final class Locale
extends Object
implements Cloneable, Serializable

The goal of an international architecture is to enable programmers to create globalized programs, coded independently of the country and language of the user. Specific language- and country-specific text and behavior (internationally-sensitive API for collation, dates, times, numbers, currencies, and so on) can then be added later--independent of the code--to produce localized programs for different countries.

Programmers may want the international behavior to be precisely the same across all platforms. Or they may want the international behavior to be the same as other programs on the same host. The international architecture allows this by always providing an abstract base class that will support both host and portable implementations:

Host objects are tied to the particular platform implementation. Typically they cannot be programmatically built or modified, and cannot be serialized for streaming to other systems. They are typically tied directly to a host locale and are not implemented in the Java language.
Portable objects typically can be programmatically built from data, can be modified, and can be streamed to other systems. They can be shared between locales, or might not be associated with any particular locale.
Each abstract base classhas statics that allow you to create one or more types of objects for a given locale (or for the default locale, if you don't specify one explicitly). For example, from NumberFormat you can create a default number format, a currency format or a percent format.

In the Java international architecture, a locale is the mechanism for identifying the kind of object (e.g. NumberFormat) that you would like to get. The locale is just a mechanism for identifying objects, not a container for the objects themselves.

Classes that are accessed by locale will have a number of convenience methods, such as the following.

     NumberFormat.getDefault()
     NumberFormat.getDefaultCurrency()

These methods will have two variants; one with an explicit locale and one without; the latter using the default locale.

     NumberFormat.getDefault(myLocale)
     NumberFormat.getDefaultCurrency(myLocale)

From each such class, you can query the display names according to an available localization, and use that to present to the user, such as in a menu.

Each type of international class allows you to enumerate all the available objects of that type. You can sift through these objects by language, country, or variant, and use the display names to present a menu to the user (for example, a menu of all the collation objects suitable for a given language).

All base classes that provide static functions that create objects for Locales must do this by implementing three statics:

 public static Locale[] getAvailableLocales()
 public static String getDisplayName(Locale objectLocale,
                                     Locale displayLocale)
 public static final String getDisplayName(Locale objectLocale)
 // getDisplayName will throw MissingResourceException if the locale
 // is not in the available Locales.

NOTE: No validity check is performed when you construct a locale, since it is just a name. If you want to see whether particular resources are available for the locale you construct, you must query those resources. For example, ask the NumberFormat for the locales it has objects for.

NOTE: When you ask for a resource for a particular locale, you get back the best available match, not necessarily precisely what you asked for. For more information, look at ResourceBundle.

ISO Language Codes. The country codes are the lower-case two-letter codes as defined by ISO-639. This should only be used programmatically. To show to a user, use getDisplayLanguage(). You can find a full list of these codes at a number of sites, such as:
http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt

ISO Country Codes. The country codes are the upper-case two-letter codes as defined by ISO-3166. This should only be used programmatically. To show to a user, use getDisplayCountry(). You can find a full list of these codes at a number of sites, such as:
http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

Variants. The Variant codes are vendor and browser-specific. Use WIN for Windows, MAC for Macintosh, and POSIX for POSIX. Remember that if the Variant is not found, the more generic version will be used. That is, if you ask for "EN", "US", "MAC", and there is no Macintosh version (the code may not even be running on a Macintosh), then "EN", "US" will be used. Where there are two variants, separate them with an underscore, and put the most important one first. For example, a Traditional Spanish collation might be referenced, with "ES", "ES", "Traditional_WIN".

See Also:: ResourceBundle, Format, NumberFormat, Collation

CANADA: Useful constant for country.
CANADA_FRENCH: Useful constant for country.
CHINA
CHINESE: Useful constant for language.
ENGLISH: Useful constant for language.
FRANCE: Useful constant for country.
FRENCH: Useful constant for language.
GERMAN: Useful constant for language.
GERMANY: Useful constant for country.
ITALIAN: Useful constant for language.
ITALY: Useful constant for country.
JAPAN: Useful constant for country.
JAPANESE: Useful constant for language.
KOREA: Useful constant for country.
KOREAN: Useful constant for language.
PRC
SCHINESE
TAIWAN
TCHINESE
UK: Useful constant for country.
US: Useful constant for country.

Locale(String, String): Construct a locale from language, country.
Locale(String, String, String): Construct a locale from language, country, variant.

clone(): Overrides Cloneable
equals(Object): Compares two Objects for equality.
getCountry(): Getter for programmatic name of field, an uppercased two-letter ISO-3166 code.
getDefault(): Common methods of getting the current default Locale.
getDisplayCountry(): Getter for display of field to user.
getDisplayCountry(Locale): Getter for display of field to user.
getDisplayLanguage(): Getter for display of field to user.
getDisplayLanguage(Locale): Getter for display of field to user.
getDisplayName(): Getter for display of the entire locale to user.
getDisplayName(Locale): Getter for display of the entire locale to user.
getDisplayVariant(): Getter for display of field to user.
getDisplayVariant(Locale): Getter for display of field to user If the localized name is not found, returns the variant code.
getISO3Country(): Getter for the three-letter ISO country abbreviation of the locale.
getISO3Language(): Getter for the three-letter ISO language abbreviation of the locale.
getLanguage(): Getter for programmatic name of field, an uppercased two-letter ISO-639 code.
getVariant(): Getter for programmatic name of field.
hashCode(): Override hashCode.
setDefault(Locale): Sets the default.
toString(): Getter for the programmatic name of the entire locale, with the language, country and variant separated by underbars.

ENGLISH

  public final static Locale ENGLISH

Useful constant for language.

FRENCH

  public final static Locale FRENCH

Useful constant for language.

GERMAN

  public final static Locale GERMAN

Useful constant for language.

ITALIAN

  public final static Locale ITALIAN

Useful constant for language.

JAPANESE

  public final static Locale JAPANESE

Useful constant for language.

KOREAN

  public final static Locale KOREAN

Useful constant for language.

CHINESE

  public final static Locale CHINESE

Useful constant for language.

SCHINESE

  public final static Locale SCHINESE

TCHINESE

  public final static Locale TCHINESE

FRANCE

  public final static Locale FRANCE

Useful constant for country.

GERMANY

  public final static Locale GERMANY

Useful constant for country.

ITALY

  public final static Locale ITALY

Useful constant for country.

JAPAN

  public final static Locale JAPAN

Useful constant for country.

KOREA

  public final static Locale KOREA

Useful constant for country.

CHINA

  public final static Locale CHINA

PRC

  public final static Locale PRC

TAIWAN

  public final static Locale TAIWAN

  public final static Locale UK

Useful constant for country.

  public final static Locale US

Useful constant for country.

CANADA

  public final static Locale CANADA

Useful constant for country.

CANADA_FRENCH

  public final static Locale CANADA_FRENCH

Useful constant for country.

Locale

  public Locale(String language,
                String country,
                String variant)

Construct a locale from language, country, variant.

Parameters:: language - lowercase two-letter ISO-639 code.; country - uppercase two-letter ISO-3166 code.; variant - vendor and browser specific code. See class description.

Locale

  public Locale(String language,
                String country)

Construct a locale from language, country.

Parameters:: language - uppercase two-letter ISO-639 code.; country - uppercase two-letter ISO-3166 code.

getDefault

  public static synchronized Locale getDefault()

Common methods of getting the current default Locale. Used for the presentation: menus, dialogs, etc. Generally set once when your applet or application is initialized, then never reset. (If you do reset the default locale, you probably want to reload your GUI, so that the change is reflected in your interface.)

More advanced programs will allow users to use different locales for different fields, e.g. in a spreadsheet.
Note that the initial setting will match the host system.

setDefault

  public static synchronized void setDefault(Locale newLocale)

Sets the default. Normally set once at the beginning of applet or application, then never reset. setDefault does not reset the host locale.

Parameters:: newLocale - Locale to set to.

getLanguage

  public String getLanguage()

Getter for programmatic name of field, an uppercased two-letter ISO-639 code.

See Also:: getDisplayLanguage

getCountry

  public String getCountry()

Getter for programmatic name of field, an uppercased two-letter ISO-3166 code.

See Also:: getDisplayCountry

getVariant

  public String getVariant()

Getter for programmatic name of field.

See Also:: getDisplayVariant

toString

  public final String toString()

Getter for the programmatic name of the entire locale, with the language, country and variant separated by underbars. If a field is missing, at most one underbar will occur. Example: "EN", "DE_DE", "EN_US_WIN", "DE_POSIX", "FR_MAC"

Overrides:: toString in class Object
See Also:: getDisplayName

getISO3Language

  public String getISO3Language() throws MissingResourceException

Getter for the three-letter ISO language abbreviation of the locale.

Throws: MissingResourceException: Throws MissingResourceException if the three-letter language abbreviation is not available for this locale.

getISO3Country

  public String getISO3Country() throws MissingResourceException

Getter for the three-letter ISO country abbreviation of the locale.

Throws: MissingResourceException: Throws MissingResourceException if the three-letter language abbreviation is not available for this locale.

getDisplayLanguage

  public final String getDisplayLanguage()

Getter for display of field to user. If the localized name is not found, returns the ISO code. The desired user language is from the default locale.

getDisplayLanguage

  public String getDisplayLanguage(Locale inLocale)

Getter for display of field to user. If the localized name is not found, returns the ISO codes. Example: "English (UK)", "Deutch", "Germany"

Parameters:: inLocale - specifies the desired user language.

getDisplayCountry

  public final String getDisplayCountry()

Getter for display of field to user. If the localized name is not found, returns the ISO code. The default locale is used for the presentation language.

getDisplayCountry

  public String getDisplayCountry(Locale inLocale)

Getter for display of field to user. If the localized name is not found, returns the ISO code.

Parameters:: inLocale - specifies the desired user language.

getDisplayVariant

  public final String getDisplayVariant()

Getter for display of field to user. If the localized name is not found, returns the variant code. The default locale is used for the presentation language.

getDisplayVariant

  public String getDisplayVariant(Locale inLocale)

Getter for display of field to user If the localized name is not found, returns the variant code.

Parameters:: inLocale - specifies the desired user language.

getDisplayName

  public final String getDisplayName()

Getter for display of the entire locale to user. If the localized name is not found, uses the ISO codes. The default locale is used for the presentation language.

getDisplayName

  public String getDisplayName(Locale inLocale)

Getter for display of the entire locale to user. If the localized name is not found, uses the ISO codes

Parameters:: inLocale - specifies the desired user language.

clone

  public Object clone()

Overrides Cloneable

Overrides:: clone in class Object

hashCode

  public synchronized int hashCode()

Override hashCode. Since Locales are often used in hashtables, caches the value for speed.

Overrides:: hashCode in class Object

equals

  public boolean equals(Object obj)

Compares two Objects for equality.

Overrides:: equals in class Object

All Packages  Class Hierarchy  This Package  Previous  Next  Index