    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.getInstance()
         NumberFormat.getDefaultCurrency()

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

         NumberFormat.getInstance(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
  Useful constant for country.
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
  Useful constant for country.
SIMPLIFIED_CHINESE
  Useful constant for language.
TAIWAN
  Useful constant for country.
TRADITIONAL_CHINESE
  Useful constant for language.
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 lowercased 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.

SIMPLIFIED_CHINESE

      public final static Locale SIMPLIFIED_CHINESE

  Useful constant for language.

TRADITIONAL_CHINESE

      public final static Locale TRADITIONAL_CHINESE

  Useful constant for language.

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

  Useful constant for country.

PRC

      public final static Locale PRC

  Useful constant for country.

TAIWAN

      public final static Locale TAIWAN

  Useful constant for country.

UK

      public final static Locale UK

  Useful constant for country.

US

      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 - lowercase 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 lowercased 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