ULocale (icu4j)

Overview

Package

Class

Use

Tree

Serialized

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.ibm.icu.util
Class ULocale

java.lang.Object
  com.ibm.icu.util.ULocale

All Implemented Interfaces:: Serializable

public final class ULocale
extends Object
implements Serializable
extends Object
implements Serializable

[icu enhancement] ICU's replacement for java.util.Locale. Methods, fields, and other functionality specific to ICU are labeled '[icu]'.

A class analogous to Locale that provides additional support for ICU protocol. In ICU 3.0 this class is enhanced to support RFC 3066 language identifiers.

Many classes and services in ICU follow a factory idiom, in which a factory method or object responds to a client request with an object. The request includes a locale (the requested locale), and the returned object is constructed using data for that locale. The system may lack data for the requested locale, in which case the locale fallback mechanism will be invoked until a populated locale is found (the valid locale). Furthermore, even when a populated locale is found (the valid locale), further fallback may be required to reach a locale containing the specific data required by the service (the actual locale).

ULocale performs 'normalization' and 'canonicalization' of locale ids. Normalization 'cleans up' ICU locale ids as follows:

language, script, country, variant, and keywords are properly cased
(lower, title, upper, upper, and lower case respectively)
hyphens used as separators are converted to underscores
three-letter language and country ids are converted to two-letter equivalents where available
surrounding spaces are removed from keywords and values
if there are multiple keywords, they are put in sorted order

Canonicalization additionally performs the following:

POSIX ids are converted to ICU format IDs
'grandfathered' 3066 ids are converted to ICU standard form
'PREEURO' and 'EURO' variants are converted to currency keyword form, with the currency id appropriate to the country of the locale (for PREEURO) or EUR (for EURO).

All ULocale constructors automatically normalize the locale id. To handle POSIX ids, canonicalize can be called to convert the id to canonical form, or the canonicalInstance factory method can be called.

This class provides selectors VALID_LOCALE and ACTUAL_LOCALE intended for use in methods named getLocale(). These methods exist in several ICU classes, including Calendar, Currency, UFormat, BreakIterator, Collator, DateFormatSymbols, and DecimalFormatSymbols and their subclasses, if any. Once an object of one of these classes has been created, getLocale() may be called on it to determine the valid and actual locale arrived at during the object's construction.

Note: The actual locale is returned correctly, but the valid locale is not, in most cases.

Author:: weiv, Alan Liu, Ram Viswanadha
See Also:: Locale, Serialized Form
Status:: Stable ICU 2.8.

Nested Class Summary
`static class`	`ULocale.Builder` `Builder` is used to build instances of `ULocale` from values configured by the setters.
`static class`	`ULocale.Category` Enum for locale categories.
`static class`	`ULocale.Type` Opaque selector enum for `getLocale()`.

Field Summary
`static ULocale.Type`	`ACTUAL_LOCALE` [icu] Selector for `getLocale()` indicating the locale of the resource containing the data.
`static ULocale`	`CANADA` Useful constant for country/region.
`static ULocale`	`CANADA_FRENCH` Useful constant for country/region.
`static ULocale`	`CHINA` Useful constant for country/region.
`static ULocale`	`CHINESE` Useful constant for language.
`static ULocale`	`ENGLISH` Useful constant for language.
`static ULocale`	`FRANCE` Useful constant for country/region.
`static ULocale`	`FRENCH` Useful constant for language.
`static ULocale`	`GERMAN` Useful constant for language.
`static ULocale`	`GERMANY` Useful constant for country/region.
`static ULocale`	`ITALIAN` Useful constant for language.
`static ULocale`	`ITALY` Useful constant for country/region.
`static ULocale`	`JAPAN` Useful constant for country/region.
`static ULocale`	`JAPANESE` Useful constant for language.
`static ULocale`	`KOREA` Useful constant for country/region.
`static ULocale`	`KOREAN` Useful constant for language.
`static ULocale`	`PRC` Useful constant for country/region.
`static char`	`PRIVATE_USE_EXTENSION` [icu] The key for the private use locale extension ('x').
`static ULocale`	`ROOT` The root ULocale.
`static ULocale`	`SIMPLIFIED_CHINESE` Useful constant for language.
`static ULocale`	`TAIWAN` Useful constant for country/region.
`static ULocale`	`TRADITIONAL_CHINESE` Useful constant for language.
`static ULocale`	`UK` Useful constant for country/region.
`static char`	`UNICODE_LOCALE_EXTENSION` [icu] The key for Unicode locale extension ('u').
`static ULocale`	`US` Useful constant for country/region.
`static ULocale.Type`	`VALID_LOCALE` [icu] Selector for `getLocale()` indicating the most specific locale for which any data exists.

Constructor Summary
`ULocale(String localeID)` [icu] Constructs a ULocale from a RFC 3066 locale ID.
`ULocale(String a, String b)` Convenience overload of ULocale(String, String, String) for compatibility with java.util.Locale.
`ULocale(String a, String b, String c)` Constructs a ULocale from a localeID constructed from the three 'fields' a, b, and c.

Method Summary
`static ULocale`	`acceptLanguage(String acceptLanguageList, boolean[] fallback)` [icu] Based on a HTTP formatted list of acceptable locales, determine an available locale for the user.
`static ULocale`	`acceptLanguage(String acceptLanguageList, ULocale[] availableLocales, boolean[] fallback)` [icu] Based on a HTTP formatted list of acceptable locales, determine an available locale for the user.
`static ULocale`	`acceptLanguage(ULocale[] acceptLanguageList, boolean[] fallback)` [icu] Based on an ordered array of acceptable locales, determine an available locale for the user.
`static ULocale`	`acceptLanguage(ULocale[] acceptLanguageList, ULocale[] availableLocales, boolean[] fallback)` [icu] Based on a list of acceptable locales, determine an available locale for the user.
`static ULocale`	`addLikelySubtags(ULocale loc)` [icu] Adds the likely subtags for a provided locale ID, per the algorithm described in the following CLDR technical report: http://www.unicode.org/reports/tr35/#Likely_Subtags If the provided ULocale instance is already in the maximal form, or there is no data available available for maximization, it will be returned.
`static String`	`canonicalize(String localeID)` [icu] Returns the canonical name for the specified locale ID.
`Object`	`clone()` This is for compatibility with Locale-- in actuality, since ULocale is immutable, there is no reason to clone it, so this API returns 'this'.
`static ULocale`	`createCanonical(String nonCanonicalID)` [icu] Creates a ULocale from the id by first canonicalizing the id.
`boolean`	`equals(Object obj)` Returns true if the other object is another ULocale with the same full name, or is a String localeID that matches the full name.
`static ULocale`	`forLanguageTag(String languageTag)` [icu] Returns a locale for the specified IETF BCP 47 language tag string.
`static ULocale`	`forLocale(Locale loc)` [icu] Returns a ULocale object for a `Locale`.
`static ULocale[]`	`getAvailableLocales()` [icu] Note: Unlike the Locale API, this returns an array of `ULocale`, not `Locale`.
`String`	`getBaseName()` [icu] Returns the (normalized) base name for this locale.
`static String`	`getBaseName(String localeID)` [icu] Returns the (normalized) base name for the specified locale.
`String`	`getCharacterOrientation()` [icu] Returns this locale's layout orientation for characters.
`String`	`getCountry()` Returns the country/region code for this locale, which will either be the empty string or an uppercase ISO 3166 2-letter code.
`static String`	`getCountry(String localeID)` Returns the country/region code for this locale, which will either be the empty string or an uppercase ISO 3166 2-letter code.
`static ULocale`	`getDefault()` Returns the current default ULocale.
`static ULocale`	`getDefault(ULocale.Category category)` Returns the current default ULocale for the specified category.
`String`	`getDisplayCountry()` Returns this locale's country localized for display in the default `DISPLAY` locale.
`static String`	`getDisplayCountry(String localeID, String displayLocaleID)` Returns a locale's country localized for display in the provided locale.
`static String`	`getDisplayCountry(String localeID, ULocale displayLocale)` Returns a locale's country localized for display in the provided locale.
`String`	`getDisplayCountry(ULocale displayLocale)` Returns this locale's country localized for display in the provided locale.
`static String`	`getDisplayKeyword(String keyword)` [icu] Returns a keyword localized for display in the default `DISPLAY` locale.
`static String`	`getDisplayKeyword(String keyword, String displayLocaleID)` [icu] Returns a keyword localized for display in the specified locale.
`static String`	`getDisplayKeyword(String keyword, ULocale displayLocale)` [icu] Returns a keyword localized for display in the specified locale.
`String`	`getDisplayKeywordValue(String keyword)` [icu] Returns a keyword value localized for display in the default `DISPLAY` locale.
`static String`	`getDisplayKeywordValue(String localeID, String keyword, String displayLocaleID)` [icu] Returns a keyword value localized for display in the specified locale.
`static String`	`getDisplayKeywordValue(String localeID, String keyword, ULocale displayLocale)` [icu] Returns a keyword value localized for display in the specified locale.
`String`	`getDisplayKeywordValue(String keyword, ULocale displayLocale)` [icu] Returns a keyword value localized for display in the specified locale.
`String`	`getDisplayLanguage()` Returns this locale's language localized for display in the default `DISPLAY` locale.
`static String`	`getDisplayLanguage(String localeID, String displayLocaleID)` Returns a locale's language localized for display in the provided locale.
`static String`	`getDisplayLanguage(String localeID, ULocale displayLocale)` Returns a locale's language localized for display in the provided locale.
`String`	`getDisplayLanguage(ULocale displayLocale)` [icu] Returns this locale's language localized for display in the provided locale.
`String`	`getDisplayLanguageWithDialect()` [icu] Returns this locale's language localized for display in the default `DISPLAY` locale.
`static String`	`getDisplayLanguageWithDialect(String localeID, String displayLocaleID)` [icu] Returns a locale's language localized for display in the provided locale.
`static String`	`getDisplayLanguageWithDialect(String localeID, ULocale displayLocale)` [icu] Returns a locale's language localized for display in the provided locale.
`String`	`getDisplayLanguageWithDialect(ULocale displayLocale)` [icu] Returns this locale's language localized for display in the provided locale.
`String`	`getDisplayName()` Returns this locale name localized for display in the default `DISPLAY` locale.
`static String`	`getDisplayName(String localeID, String displayLocaleID)` Returns the locale ID localized for display in the provided locale.
`static String`	`getDisplayName(String localeID, ULocale displayLocale)` Returns the locale ID localized for display in the provided locale.
`String`	`getDisplayName(ULocale displayLocale)` Returns this locale name localized for display in the provided locale.
`String`	`getDisplayNameWithDialect()` [icu] Returns this locale name localized for display in the default `DISPLAY` locale.
`static String`	`getDisplayNameWithDialect(String localeID, String displayLocaleID)` [icu] Returns the locale ID localized for display in the provided locale.
`static String`	`getDisplayNameWithDialect(String localeID, ULocale displayLocale)` [icu] Returns the locale ID localized for display in the provided locale.
`String`	`getDisplayNameWithDialect(ULocale displayLocale)` [icu] Returns this locale name localized for display in the provided locale.
`String`	`getDisplayScript()` [icu] Returns this locale's script localized for display in the default `DISPLAY` locale.
`static String`	`getDisplayScript(String localeID, String displayLocaleID)` [icu] Returns a locale's script localized for display in the provided locale.
`static String`	`getDisplayScript(String localeID, ULocale displayLocale)` [icu] Returns a locale's script localized for display in the provided locale.
`String`	`getDisplayScript(ULocale displayLocale)` [icu] Returns this locale's script localized for display in the provided locale.
`String`	`getDisplayVariant()` Returns this locale's variant localized for display in the default `DISPLAY` locale.
`static String`	`getDisplayVariant(String localeID, String displayLocaleID)` Returns a locale's variant localized for display in the provided locale.
`static String`	`getDisplayVariant(String localeID, ULocale displayLocale)` Returns a locale's variant localized for display in the provided locale.
`String`	`getDisplayVariant(ULocale displayLocale)` Returns this locale's variant localized for display in the provided locale.
`String`	`getExtension(char key)` [icu] Returns the extension (or private use) value associated with the specified key, or null if there is no extension associated with the key.
`Set<Character>`	`getExtensionKeys()` [icu] Returns the set of extension keys associated with this locale, or the empty set if it has no extensions.
`ULocale`	`getFallback()` [icu] Returns the fallback locale for this locale.
`static String`	`getFallback(String localeID)` [icu] Returns the fallback locale for the specified locale, which might be the empty string.
`String`	`getISO3Country()` Returns a three-letter abbreviation for this locale's country/region.
`static String`	`getISO3Country(String localeID)` Returns a three-letter abbreviation for this locale's country/region.
`String`	`getISO3Language()` Returns a three-letter abbreviation for this locale's language.
`static String`	`getISO3Language(String localeID)` 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.
`Iterator<String>`	`getKeywords()` [icu] Returns an iterator over keywords for this locale.
`static Iterator<String>`	`getKeywords(String localeID)` [icu] Returns an iterator over keywords for the specified locale.
`String`	`getKeywordValue(String keywordName)` [icu] Returns the value for a keyword in this locale.
`static String`	`getKeywordValue(String localeID, String keywordName)` [icu] Returns the value for a keyword in the specified locale.
`String`	`getLanguage()` Returns the language code for this locale, which will either be the empty string or a lowercase ISO 639 code.
`static String`	`getLanguage(String localeID)` Returns the language code for the locale ID, which will either be the empty string or a lowercase ISO 639 code.
`String`	`getLineOrientation()` [icu] Returns this locale's layout orientation for lines.
`String`	`getName()` [icu] Returns the (normalized) full name for this locale.
`static String`	`getName(String localeID)` [icu] Returns the (normalized) full name for the specified locale.
`String`	`getScript()` [icu] Returns the script code for this locale, which might be the empty string.
`static String`	`getScript(String localeID)` [icu] Returns the script code for the specified locale, which might be the empty string.
`Set<String>`	`getUnicodeLocaleAttributes()` [icu] Returns the set of unicode locale attributes associated with this locale, or the empty set if it has no attributes.
`Set<String>`	`getUnicodeLocaleKeys()` [icu] Returns the set of Unicode locale keys defined by this locale, or the empty set if this locale has none.
`String`	`getUnicodeLocaleType(String key)` [icu] Returns the Unicode locale type associated with the specified Unicode locale key for this locale.
`String`	`getVariant()` Returns the variant code for this locale, which might be the empty string.
`static String`	`getVariant(String localeID)` Returns the variant code for the specified locale, which might be the empty string.
`int`	`hashCode()` Returns the hashCode.
`static ULocale`	`minimizeSubtags(ULocale loc)` [icu] Minimizes the subtags for a provided locale ID, per the algorithm described in the following CLDR technical report: http://www.unicode.org/reports/tr35/#Likely_Subtags If the provided ULocale instance is already in the minimal form, or there is no data available for minimization, it will be returned.
`static void`	`setDefault(ULocale.Category category, ULocale newLocale)` Sets the default `ULocale` for the specified `Category`.
`static void`	`setDefault(ULocale newLocale)` [icu] Sets the default ULocale.
`ULocale`	`setKeywordValue(String keyword, String value)` Given a keyword and a value, return a new locale with an updated keyword and value.
`static String`	`setKeywordValue(String localeID, String keyword, String value)` Given a locale id, a keyword, and a value, return a new locale id with an updated keyword and value.
`String`	`toLanguageTag()` [icu] Returns a well-formed IETF BCP 47 language tag representing this locale.
`Locale`	`toLocale()` [icu] Converts this ULocale object to a `Locale`.
`String`	`toString()` Returns a string representation of this object.

Methods inherited from class java.lang.Object
`finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

ENGLISH

public static final ULocale ENGLISH

Useful constant for language.

Status:: Stable ICU 3.0.

FRENCH

public static final ULocale FRENCH

Useful constant for language.

Status:: Stable ICU 3.0.

GERMAN

public static final ULocale GERMAN

Useful constant for language.

Status:: Stable ICU 3.0.

ITALIAN

public static final ULocale ITALIAN

Useful constant for language.

Status:: Stable ICU 3.0.

JAPANESE

public static final ULocale JAPANESE

Useful constant for language.

Status:: Stable ICU 3.0.

KOREAN

public static final ULocale KOREAN

Useful constant for language.

Status:: Stable ICU 3.0.

CHINESE

public static final ULocale CHINESE

Useful constant for language.

Status:: Stable ICU 3.0.

SIMPLIFIED_CHINESE

public static final ULocale SIMPLIFIED_CHINESE

Useful constant for language.

Status:: Stable ICU 3.0.

TRADITIONAL_CHINESE

public static final ULocale TRADITIONAL_CHINESE

Useful constant for language.

Status:: Stable ICU 3.0.