|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--java.util.Locale
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:
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:Locale(String language, String country) Locale(String language, String country, String variant)
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. For more information, look at
ResourceBundle
.
The Locale
class provides a number of convenient constants
that you can use to create Locale
objects for commonly used
locales. For example, the following creates a Locale
object
for the United States:
Locale.US
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. You can
use getDisplayCountry
to get the
name of the country suitable for displaying to the user. Similarly,
you can use getDisplayLanguage
to get the name of
the language suitable for displaying to the user. Interestingly,
the getDisplayXXX
methods are themselves locale-sensitive
and have two versions: one that uses the default locale and one
that uses the locale specified as an argument.
The JDK provides a number of classes that perform locale-sensitive
operations. For example, the NumberFormat
class formats
numbers, currency, or percentages in a locale-sensitive manner. Classes
such as NumberFormat
have a number of convenience methods
for creating a default object of that type. For example, the
NumberFormat
class provides these three convenience methods
for creating a default NumberFormat
object:
These methods have two variants; one with an explicit locale and one without; the latter using the default locale.NumberFormat.getInstance() NumberFormat.getCurrencyInstance() NumberFormat.getPercentInstance()
ANumberFormat.getInstance(myLocale) NumberFormat.getCurrencyInstance(myLocale) NumberFormat.getPercentInstance(myLocale)
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.
Each class that performs locale-sensitive operations allows you to get 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, you can create a menu of all the collation objects suitable for a given language. Such classes must implement these three class methods:
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 one of the available locales.
ResourceBundle
,
Format
,
NumberFormat
,
java.text.Collator
, Serialized FormField Summary | |
static Locale |
CANADA
Useful constant for country. |
static Locale |
CANADA_FRENCH
Useful constant for country. |
static Locale |
CHINA
Useful constant for country. |
static Locale |
CHINESE
Useful constant for language. |
private static String |
compressedCtry2LangMapping
|
private static String |
compressedIsoCountries
|
private static String |
compressedIsoLanguages
|
private String |
country
|
private static Hashtable |
ctry2LangMapping
Table mapping ISO country codes to the ISO language codes of the languages spoken in those countries. |
private static Locale |
defaultLocale
|
static Locale |
ENGLISH
Useful constant for language. |
static Locale |
FRANCE
Useful constant for country. |
static Locale |
FRENCH
Useful constant for language. |
static Locale |
GERMAN
Useful constant for language. |
static Locale |
GERMANY
Useful constant for country. |
private int |
hashcode
Placeholder for the object's hash code. |
private static String[] |
isoCountries
List of all 2-letter country codes currently defined in ISO 3166. |
private static String[] |
isoLanguages
List of all 2-letter language codes currently defined in ISO 639. |
static Locale |
ITALIAN
Useful constant for language. |
static Locale |
ITALY
Useful constant for country. |
static Locale |
JAPAN
Useful constant for country. |
static Locale |
JAPANESE
Useful constant for language. |
static Locale |
KOREA
Useful constant for country. |
static Locale |
KOREAN
Useful constant for language. |
private String |
language
|
static Locale |
PRC
Useful constant for country. |
(package private) static long |
serialVersionUID
serialization ID |
static Locale |
SIMPLIFIED_CHINESE
Useful constant for language. |
static Locale |
TAIWAN
Useful constant for country. |
static Locale |
TRADITIONAL_CHINESE
Useful constant for language. |
static Locale |
UK
Useful constant for country. |
static Locale |
US
Useful constant for country. |
private String |
variant
|
Constructor Summary | |
Locale(String language,
String country)
Construct a locale from language, country. |
|
Locale(String language,
String country,
String variant)
Construct a locale from language, country, variant. |
Method Summary | |
(package private) static void |
|
Object |
clone()
Overrides Cloneable |
private static String[] |
composeList(java.text.MessageFormat format,
String[] list)
Given a list of strings, return a list shortened to three elements. |
boolean |
equals(Object obj)
Returns true if this Locale is equal to another object. |
private String |
findStringMatch(String[][] languages,
String desiredLanguage,
String fallbackLanguage)
|
private static String |
formatList(String[] patterns,
String[] stringList)
Format a list with an array of patterns. |
static Locale[] |
getAvailableLocales()
Returns a list of all installed locales. |
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()
Common method of getting the current default Locale. |
String |
getDisplayCountry()
Returns a name for the locale's country that is appropriate for display to the user. |
String |
getDisplayCountry(Locale inLocale)
Returns a name for the locale's country that is appropriate for display to the user. |
String |
getDisplayLanguage()
Returns a name for the locale's language that is appropriate for display to the user. |
String |
getDisplayLanguage(Locale inLocale)
Returns a name for the locale's language that is appropriate for display to the user. |
String |
getDisplayName()
Returns a name for the locale that is appropriate for display to the user. |
String |
getDisplayName(Locale inLocale)
Returns a name for the locale that is appropriate for display to the user. |
String |
getDisplayVariant()
Returns a name for the locale's variant code that is appropriate for display to the user. |
String |
getDisplayVariant(Locale inLocale)
Returns a name for the locale's variant code that is appropriate for display to the user. |
private String[] |
getDisplayVariantArray(ResourceBundle bundle)
Return an array of the display names of the variant. |
String |
getISO3Country()
Returns a three-letter abbreviation for this locale's country. |
String |
getISO3Language()
Returns a three-letter abbreviation for this locale's language. |
static String[] |
getISOCountries()
Returns a list of all 2-letter country codes defined in ISO 3166. |
static String[] |
getISOLanguages()
Returns a list of all 2-letter language codes defined in ISO 639. |
String |
getLanguage()
Returns the language code for this locale, which will either be the empty string or a lowercase ISO 639 code. |
(package private) static String[] |
getLanguagesForCountry(String country)
Given an ISO country code, returns an array of Strings containing the ISO codes of the languages spoken in that country. |
String |
getVariant()
Returns the variant code for this locale. |
int |
hashCode()
Override hashCode. |
private void |
readObject(ObjectInputStream in)
|
static void |
setDefault(Locale newLocale)
Sets the default locale for the whole JVM. |
private String |
toLowerCase(String str)
|
String |
toString()
Getter for the programmatic name of the entire locale, with the language, country and variant separated by underbars. |
private String |
toUpperCase(String str)
|
private void |
writeObject(ObjectOutputStream out)
|
Methods inherited from class java.lang.Object |
finalize,
getClass,
notify,
notifyAll,
registerNatives,
wait,
wait,
wait |
Field Detail |
public static final Locale ENGLISH
public static final Locale FRENCH
public static final Locale GERMAN
public static final Locale ITALIAN
public static final Locale JAPANESE
public static final Locale KOREAN
public static final Locale CHINESE
public static final Locale SIMPLIFIED_CHINESE
public static final Locale TRADITIONAL_CHINESE
public static final Locale FRANCE
public static final Locale GERMANY
public static final Locale ITALY
public static final Locale JAPAN
public static final Locale KOREA
public static final Locale CHINA
public static final Locale PRC
public static final Locale TAIWAN
public static final Locale UK
public static final Locale US
public static final Locale CANADA
public static final Locale CANADA_FRENCH
static final long serialVersionUID
private String language
getLanguage()
private String country
getCountry()
private String variant
getVariant()
private int hashcode
private static Locale defaultLocale
private static String[] isoLanguages
private static final String compressedIsoLanguages
private static String[] isoCountries
private static final String compressedIsoCountries
private static Hashtable ctry2LangMapping
private static final String compressedCtry2LangMapping
Constructor Detail |
public Locale(String language, String country, String variant)
language
- lowercase two-letter ISO-639 code.country
- uppercase two-letter ISO-3166 code.variant
- vendor and browser specific code. See class description.public Locale(String language, String country)
language
- lowercase two-letter ISO-639 code.country
- uppercase two-letter ISO-3166 code.Method Detail |
public static Locale getDefault()
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.
public static void setDefault(Locale newLocale)
setDefault
does not reset the host locale.
If there is a security manager, its checkPermission
method is called with a PropertyPermission("user.language", "write")
permission.
newLocale
- The new default Locale.checkPermission
method doesn't allow the operation.SecurityManager.checkPermission(java.security.Permission)
,
PropertyPermission
public static Locale[] getAvailableLocales()
public static String[] getISOCountries()
public static String[] getISOLanguages()
static String[] getLanguagesForCountry(String country)
public String getLanguage()
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()) ...
getDisplayLanguage()
public String getCountry()
getDisplayCountry()
public String getVariant()
getDisplayVariant()
public final String toString()
getDisplayName()
public String getISO3Language() throws MissingResourceException
public String getISO3Country() throws MissingResourceException
public final String getDisplayLanguage()
public String getDisplayLanguage(Locale inLocale)
public final String getDisplayCountry()
public String getDisplayCountry(Locale inLocale)
public final String getDisplayVariant()
public String getDisplayVariant(Locale inLocale)
public final String getDisplayName()
language (country, variant)depending on which fields are specified in the locale. If the language, country, and variant fields are all empty, this function returns the empty string.language (country)
language (variant)
country (variant)
language
country
variant
public String getDisplayName(Locale inLocale)
language (country, variant)depending on which fields are specified in the locale. If the language, country, and variant fields are all empty, this function returns the empty string.language (country)
language (variant)
country (variant)
language
country
variant
public Object clone()
public int hashCode()
public boolean equals(Object obj)
static void()
private String[] getDisplayVariantArray(ResourceBundle bundle)
bundle
- the ResourceBundle to use to get the display namesprivate static String formatList(String[] patterns, String[] stringList)
patterns
- an array of three patterns. The first pattern is not
used. The second pattern should create a MessageFormat taking 0-3 arguments
and formatting them into a list. The third pattern should take 2 arguments
and is used by composeList. If patterns is null, then a the list is
formatted by concatenation with the delimiter ','.stringList
- the list of strings to be formatted.private static String[] composeList(java.text.MessageFormat format, String[] list)
format
- a format which takes two argumentslist
- a list of stringsprivate void writeObject(ObjectOutputStream out) throws IOException
private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException
private String toLowerCase(String str)
private String toUpperCase(String str)
private String findStringMatch(String[][] languages, String desiredLanguage, String fallbackLanguage)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |