PDAP Public Review Draft

java.util
Class Locale

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

public final class Locale
extends java.lang.Object

A Locale object represents a specific geographical, political, or cultural region. An operation that requires a Locale to perform its task is called locale-sensitive and uses the Locale to tailor information for the user. For example, displaying a number is a locale-sensitive operation--the number should be formatted according to the customs/conventions of the user's native country, region, or culture.

You create a Locale object using one of the two constructors in this class:

 Locale(String language, String country)
 Locale(String language, String country, String variant)
 
The first argument to both constructors is a valid ISO Language Code. These codes are the lower-case two-letter codes as defined by ISO-639. 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

The second argument to both constructors is a valid ISO Country Code. These codes are the upper-case two-letter codes as defined by ISO-3166. 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

The second constructor requires a third argument--the Variant. The Variant codes are vendor and browser-specific. For example, use WIN for Windows, MAC for Macintosh, and POSIX for POSIX. Where there are two variants, separate them with an underscore, and put the most important one first. For example, a Traditional Spanish collation might construct a locale with parameters for language, country and variant as: "es", "ES", "Traditional_WIN".

Because a Locale object is just an identifier for a region, no validity check is performed when you construct a Locale. 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 supports using its getAvailableLocales method.
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.

Once you've created a Locale you can query it for information about itself. Use getCountry to get the ISO Country Code and getLanguage to get the ISO Language Code.

The Java 2 platform provides a number of classes that perform locale-sensitive operations. These methods have two variants; one with an explicit locale and one without; the latter using the default locale. A Locale is the mechanism for identifying the kind of object (NumberFormat) that you would like to get. The locale is just a mechanism for identifying objects, not a container for the objects themselves.

 
 CDLC AWT Support Building Block:
    - Removed all language and country Locale objects provided for convenience.
    - Removed setDefault() method since since the Locale for the KVM is not supported.
    - Removed getDisplay*() methods since they utilize resource bundling mechanism not
 supported in CLDC.
    - Removed getISO*() methods due to footprint constraints of CLDC.
 
 

Since:
JDK1.1

Constructor Summary
Locale(java.lang.String language, java.lang.String country)
          Construct a locale from language, country.
Locale(java.lang.String language, java.lang.String country, java.lang.String variant)
          Construct a locale from language, country, variant.
 
Method Summary
 boolean equals(java.lang.Object obj)
          Returns true if this Locale is equal to another object.
static Locale[] getAvailableLocales()
          Returns a list of all installed locales.
 java.lang.String getCountry()
          Returns the country/region code for this locale, which will either be the empty string or an upercase ISO 3166 2-letter code.
static Locale getDefault()
          Gets the current value of the default locale for this instance of the Java Virtual Machine.
 java.lang.String getLanguage()
          Returns the language code for this locale, which will either be the empty string or a lowercase ISO 639 code.
 java.lang.String getVariant()
          Returns the variant code for this locale.
 int hashCode()
          Override hashCode.
 java.lang.String toString()
          Getter for the programmatic name of the entire locale, with the language, country and variant separated by underbars.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Locale

public Locale(java.lang.String language,
              java.lang.String country,
              java.lang.String variant)
Construct a locale from language, country, variant. NOTE: ISO 639 is not a stable standard; some of the language codes it defines (specifically iw, ji, and in) have changed. This constructor accepts both the old codes (iw, ji, and in) and the new codes (he, yi, and id), but all other API on Locale will return only the OLD codes.
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(java.lang.String language,
              java.lang.String country)
Construct a locale from language, country. To create a locale that only identifies a language, use "" for the country. NOTE: ISO 639 is not a stable standard; some of the language codes it defines (specifically iw, ji, and in) have changed. This constructor accepts both the old codes (iw, ji, and in) and the new codes (he, yi, and id), but all other API on Locale will return only the OLD codes.
Parameters:
language - lowercase two-letter ISO-639 code.
country - uppercase two-letter ISO-3166 code.
Method Detail

getDefault

public static Locale getDefault()
Gets the current value of the default locale for this instance of the Java Virtual Machine.

The Java Virtual Machine sets the default locale during startup based on the host environment. It is used by many locale-sensitive methods if no locale is explicitly specified.

Returns:
the default locale for this instance of the Java Virtual Machine

getAvailableLocales

public static Locale[] getAvailableLocales()
Returns a list of all installed locales.

getLanguage

public java.lang.String getLanguage()
Returns the language code for this locale, which will either be the empty string or a lowercase ISO 639 code.

NOTE: ISO 639 is not a stable standard-- some languages' codes have changed. Locale's constructor recognizes both the new and the old codes for the languages whose codes have changed, but this function always returns the old code. If you want to check for a specific language whose code has changed, don't do

 if (locale.getLanguage().equals("he")
    ...
 
Instead, do
 if (locale.getLanguage().equals(new Locale("he", "", "").getLanguage())
    ...

getCountry

public java.lang.String getCountry()
Returns the country/region code for this locale, which will either be the empty string or an upercase ISO 3166 2-letter code.

getVariant

public java.lang.String getVariant()
Returns the variant code for this locale.

toString

public final java.lang.String toString()
Getter for the programmatic name of the entire locale, with the language, country and variant separated by underbars. Language is always lower case, and country is always upper case. If the language is missing, the string will begin with an underbar. If both the language and country fields are missing, this function will return the empty string, even if the variant field is filled in (you can't have a locale with just a variant-- the variant must accompany a valid language or country code). Examples: "en", "de_DE", "_GB", "en_US_WIN", "de__POSIX", "fr_MAC"
Overrides:
toString in class java.lang.Object

hashCode

public int hashCode()
Override hashCode. Since Locales are often used in hashtables, caches the value for speed.
Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)
Returns true if this Locale is equal to another object. A Locale is deemed equal to another Locale with identical language, country, and variant, and unequal to all other objects.
Overrides:
equals in class java.lang.Object
Returns:
true if this Locale is equal to the specified object.

PDAP 1.0 Spec, Rev. 0.16