com.ibm.icu.util

Class GlobalizationPreferences

public class GlobalizationPreferences extends Object implements Freezable

This convenience class provides a mechanism for bundling together different globalization preferences. It includes: The class will heuristically compute implicit, heuristic values for the above based on available data if explicit values are not supplied. These implicit values can be presented to users for confirmation, or replacement if the values are incorrect.

To reset any explicit field so that it will get heuristic values, pass in null. For example, myPreferences.setLocale(null);

All of the heuristics can be customized by subclasses, by overriding getTerritory(), guessCollator(), etc.

The class also supplies display names for languages, scripts, territories, currencies, timezones, etc. These are computed according to the locale/language preference list. Thus, if the preference is Breton; French; English, then the display name for a language will be returned in Breton if available, otherwise in French if available, otherwise in English.

The codes used to reference territory, currency, etc. are as defined elsewhere in ICU, and are taken from CLDR (which reflects RFC 3066bis usage, ISO 4217, and the TZ Timezone database identifiers).

This is at a prototype stage, and has not incorporated all the design changes that we would like yet; further feedback is welcome.

TODO:

Note:

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

Field Summary
static intBI_CHARACTER
Break iterator types
static intBI_LINE
Break iterator types
static intBI_SENTENCE
Break iterator types
static intBI_TITLE
Break iterator types
static intBI_WORD
Break iterator types
static intDF_FULL
Date Format types
static intDF_LONG
Date Format types
static intDF_MEDIUM
Date Format types
static intDF_NONE
Date Format types
static intDF_SHORT
Date Format types
static intID_CURRENCY
For selecting a choice of display names
static intID_CURRENCY_SYMBOL
For selecting a choice of display names
static intID_KEYWORD
For selecting a choice of display names
static intID_KEYWORD_VALUE
For selecting a choice of display names
static intID_LANGUAGE
For selecting a choice of display names
static intID_LOCALE
For selecting a choice of display names
static intID_SCRIPT
For selecting a choice of display names
static intID_TERRITORY
For selecting a choice of display names
static intID_TIMEZONE
For selecting a choice of display names
static intID_VARIANT
For selecting a choice of display names
static intNF_CURRENCY
Number Format types
static intNF_INTEGER
Number Format types
static intNF_NUMBER
Number Format types
static intNF_PERCENT
Number Format types
static intNF_SCIENTIFIC
Number Format types
Constructor Summary
GlobalizationPreferences()
Default constructor
Method Summary
ObjectcloneAsThawed()
Objectfreeze()
BreakIteratorgetBreakIterator(int type)
Get a copy of the break iterator for the specified type according to the settings.
CalendargetCalendar()
Get a copy of the calendar according to the settings.
CollatorgetCollator()
Get a copy of the collator according to the settings.
CurrencygetCurrency()
Get a copy of the currency computed according to the settings.
DateFormatgetDateFormat(int dateStyle, int timeStyle)
Gets a date format according to the current settings.
StringgetDisplayName(String id, int type)
Get the display name for an ID: language, script, territory, currency, timezone...
ULocalegetLocale(int index)
Convenience function for getting the locales in priority order
ListgetLocales()
Get a copy of the language/locale priority list
NumberFormatgetNumberFormat(int style)
Gets a number format according to the current settings.
ResourceBundlegetResourceBundle(String baseName)
Convenience function to get a ResourceBundle instance using the specified base name based on the language/locale priority list stored in this object.
ResourceBundlegetResourceBundle(String baseName, ClassLoader loader)
Convenience function to get a ResourceBundle instance using the specified base name and class loader based on the language/locale priority list stored in this object.
StringgetTerritory()
Gets the territory setting.
TimeZonegetTimeZone()
Get the timezone.
protected BreakIteratorguessBreakIterator(int type)
This function can be overridden by subclasses to use different heuristics.
protected CalendarguessCalendar()
This function can be overridden by subclasses to use different heuristics.
protected CollatorguessCollator()
This function can be overridden by subclasses to use different heuristics.
protected CurrencyguessCurrency()
This function can be overridden by subclasses to use different heuristics
protected DateFormatguessDateFormat(int dateStyle, int timeStyle)
This function can be overridden by subclasses to use different heuristics.
protected ListguessLocales()
This function can be overridden by subclasses to use different heuristics It MUST return a 'safe' value, one whose modification will not affect this object.
protected NumberFormatguessNumberFormat(int style)
This function can be overridden by subclasses to use different heuristics.
protected StringguessTerritory()
This function can be overridden by subclasses to use different heuristics.
protected TimeZoneguessTimeZone()
This function can be overridden by subclasses to use different heuristics.
booleanisFrozen()
protected ListprocessLocales(List inputLocales)
Process a language/locale priority list specified via setLocales.
GlobalizationPreferencesreset()
Restore the object to the initial state.
GlobalizationPreferencessetBreakIterator(int type, BreakIterator iterator)
Explicitly set the break iterator for this object.
GlobalizationPreferencessetCalendar(Calendar calendar)
Sets the calendar.
GlobalizationPreferencessetCollator(Collator collator)
Explicitly set the collator for this object.
GlobalizationPreferencessetCurrency(Currency currency)
Sets the currency code.
GlobalizationPreferencessetDateFormat(int dateStyle, int timeStyle, DateFormat format)
Set an explicit date format.
GlobalizationPreferencessetLocale(ULocale uLocale)
Convenience routine for setting the language/locale priority list from a single locale/language.
GlobalizationPreferencessetLocales(List inputLocales)
Sets the language/locale priority list.
GlobalizationPreferencessetLocales(ULocale[] uLocales)
Convenience routine for setting the language/locale priority list from an array.
GlobalizationPreferencessetLocales(String acceptLanguageString)
Convenience routine for setting the locale priority list from an Accept-Language string.
GlobalizationPreferencessetNumberFormat(int style, NumberFormat format)
Sets a number format explicitly.
GlobalizationPreferencessetTerritory(String territory)
Sets the territory, which is a valid territory according to for RFC 3066 (or successor).
GlobalizationPreferencessetTimeZone(TimeZone timezone)
Sets the timezone ID.

Field Detail

BI_CHARACTER

public static final int BI_CHARACTER

Deprecated: This API is ICU internal only

Break iterator types

UNKNOWN: ICU 3.6

BI_LINE

public static final int BI_LINE

Deprecated: This API is ICU internal only

Break iterator types

UNKNOWN: ICU 3.6

BI_SENTENCE

public static final int BI_SENTENCE

Deprecated: This API is ICU internal only

Break iterator types

UNKNOWN: ICU 3.6

BI_TITLE

public static final int BI_TITLE

Deprecated: This API is ICU internal only

Break iterator types

UNKNOWN: ICU 3.6

BI_WORD

public static final int BI_WORD

Deprecated: This API is ICU internal only

Break iterator types

UNKNOWN: ICU 3.6

DF_FULL

public static final int DF_FULL
Date Format types

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

DF_LONG

public static final int DF_LONG
Date Format types

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

DF_MEDIUM

public static final int DF_MEDIUM
Date Format types

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

DF_NONE

public static final int DF_NONE
Date Format types

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

DF_SHORT

public static final int DF_SHORT
Date Format types

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

ID_CURRENCY

public static final int ID_CURRENCY
For selecting a choice of display names

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

ID_CURRENCY_SYMBOL

public static final int ID_CURRENCY_SYMBOL
For selecting a choice of display names

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

ID_KEYWORD

public static final int ID_KEYWORD
For selecting a choice of display names

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

ID_KEYWORD_VALUE

public static final int ID_KEYWORD_VALUE
For selecting a choice of display names

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

ID_LANGUAGE

public static final int ID_LANGUAGE
For selecting a choice of display names

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

ID_LOCALE

public static final int ID_LOCALE
For selecting a choice of display names

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

ID_SCRIPT

public static final int ID_SCRIPT
For selecting a choice of display names

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

ID_TERRITORY

public static final int ID_TERRITORY
For selecting a choice of display names

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

ID_TIMEZONE

public static final int ID_TIMEZONE
For selecting a choice of display names

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

ID_VARIANT

public static final int ID_VARIANT
For selecting a choice of display names

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

NF_CURRENCY

public static final int NF_CURRENCY
Number Format types

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

NF_INTEGER

public static final int NF_INTEGER
Number Format types

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

NF_NUMBER

public static final int NF_NUMBER
Number Format types

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

NF_PERCENT

public static final int NF_PERCENT
Number Format types

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

NF_SCIENTIFIC

public static final int NF_SCIENTIFIC
Number Format types

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

Constructor Detail

GlobalizationPreferences

public GlobalizationPreferences()
Default constructor

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

Method Detail

cloneAsThawed

public Object cloneAsThawed()

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

freeze

public Object freeze()

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getBreakIterator

public BreakIterator getBreakIterator(int type)
Get a copy of the break iterator for the specified type according to the settings.

Parameters: type break type - BI_CHARACTER or BI_WORD, BI_LINE, BI_SENTENCE, BI_TITLE

Returns: break iterator explicit or implicit

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getCalendar

public Calendar getCalendar()
Get a copy of the calendar according to the settings.

Returns: calendar explicit or implicit.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getCollator

public Collator getCollator()
Get a copy of the collator according to the settings.

Returns: collator explicit or implicit.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getCurrency

public Currency getCurrency()
Get a copy of the currency computed according to the settings.

Returns: currency code, explicit or implicit.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getDateFormat

public DateFormat getDateFormat(int dateStyle, int timeStyle)
Gets a date format according to the current settings. If there is an explicit (non-null) date/time format set, a copy of that is returned. Otherwise, the language priority list is used. DF_NONE should be used for the style, where only the date or time format individually is being gotten.

Parameters: dateStyle DF_FULL, DF_LONG, DF_MEDIUM, DF_SHORT or DF_NONE timeStyle DF_FULL, DF_LONG, DF_MEDIUM, DF_SHORT or DF_NONE

Returns: a DateFormat, according to the above description

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getDisplayName

public String getDisplayName(String id, int type)
Get the display name for an ID: language, script, territory, currency, timezone... Uses the language priority list to do so.

Parameters: id language code, script code, ... type specifies the type of the ID: ID_LANGUAGE, etc.

Returns: the display name

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getLocale

public ULocale getLocale(int index)
Convenience function for getting the locales in priority order

Parameters: index The index (0..n) of the desired item.

Returns: desired item. null if index is out of range

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getLocales

public List getLocales()
Get a copy of the language/locale priority list

Returns: a copy of the language/locale priority list.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getNumberFormat

public NumberFormat getNumberFormat(int style)
Gets a number format according to the current settings. If there is an explicit (non-null) number format set, a copy of that is returned. Otherwise, the language priority list is used.

Parameters: style NF_NUMBER, NF_CURRENCY, NF_PERCENT, NF_SCIENTIFIC, NF_INTEGER

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getResourceBundle

public ResourceBundle getResourceBundle(String baseName)
Convenience function to get a ResourceBundle instance using the specified base name based on the language/locale priority list stored in this object.

Parameters: baseName the base name of the resource bundle, a fully qualified class name

Returns: a resource bundle for the given base name and locale based on the language/locale priority list stored in this object

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getResourceBundle

public ResourceBundle getResourceBundle(String baseName, ClassLoader loader)
Convenience function to get a ResourceBundle instance using the specified base name and class loader based on the language/locale priority list stored in this object.

Parameters: baseName the base name of the resource bundle, a fully qualified class name loader the class object from which to load the resource bundle

Returns: a resource bundle for the given base name and locale based on the language/locale priority list stored in this object

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getTerritory

public String getTerritory()
Gets the territory setting. If it wasn't explicitly set, it is computed from the general locale setting.

Returns: territory code, explicit or implicit.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getTimeZone

public TimeZone getTimeZone()
Get the timezone. It was either explicitly set, or is heuristically computed from other settings.

Returns: timezone, either implicitly or explicitly set

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

guessBreakIterator

protected BreakIterator guessBreakIterator(int type)
This function can be overridden by subclasses to use different heuristics. It MUST return a 'safe' value, one whose modification will not affect this object.

Parameters: type

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

guessCalendar

protected Calendar guessCalendar()
This function can be overridden by subclasses to use different heuristics. It MUST return a 'safe' value, one whose modification will not affect this object.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

guessCollator

protected Collator guessCollator()
This function can be overridden by subclasses to use different heuristics. It MUST return a 'safe' value, one whose modification will not affect this object.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

guessCurrency

protected Currency guessCurrency()
This function can be overridden by subclasses to use different heuristics

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

guessDateFormat

protected DateFormat guessDateFormat(int dateStyle, int timeStyle)
This function can be overridden by subclasses to use different heuristics. It MUST return a 'safe' value, one whose modification will not affect this object.

Parameters: dateStyle timeStyle

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

guessLocales

protected List guessLocales()
This function can be overridden by subclasses to use different heuristics It MUST return a 'safe' value, one whose modification will not affect this object.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

guessNumberFormat

protected NumberFormat guessNumberFormat(int style)
This function can be overridden by subclasses to use different heuristics. It MUST return a 'safe' value, one whose modification will not affect this object.

Parameters: style

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

guessTerritory

protected String guessTerritory()
This function can be overridden by subclasses to use different heuristics.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

guessTimeZone

protected TimeZone guessTimeZone()
This function can be overridden by subclasses to use different heuristics. It MUST return a 'safe' value, one whose modification will not affect this object.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

isFrozen

public boolean isFrozen()

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

processLocales

protected List processLocales(List inputLocales)
Process a language/locale priority list specified via setLocales. The input locale list may be expanded or re-ordered to represent the prioritized language/locale order actually used by this object by the algorithm exaplained below.

Step 1: Move later occurence of more specific locale before ealier occurence of less specific locale.
Before: en, fr_FR, en_US, en_GB
After: en_US, en_GB, en, fr_FR

Step 2: Append a fallback locale to each locale.
Before: en_US, en_GB, en, fr_FR
After: en_US, en, en_GB, en, en, fr_FR, fr

Step 3: Remove ealier occurence of duplicated locale entries.
Before: en_US, en, en_GB, en, en, fr_FR, fr
After: en_US, en_GB, en, fr_FR, fr

The final locale list is used to produce a default value for the appropriate territory, currency, timezone, etc. The list also represents the lookup order used in getResourceBundle for this object. A subclass may override this method to customize the algorithm used for populating the locale list.

Parameters: inputLocales The list of input locales

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

reset

public GlobalizationPreferences reset()
Restore the object to the initial state.

Returns: this, for chaining

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setBreakIterator

public GlobalizationPreferences setBreakIterator(int type, BreakIterator iterator)
Explicitly set the break iterator for this object.

Parameters: type break type - BI_CHARACTER or BI_WORD, BI_LINE, BI_SENTENCE, BI_TITLE iterator a break iterator

Returns: this, for chaining

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setCalendar

public GlobalizationPreferences setCalendar(Calendar calendar)
Sets the calendar. If this has not been set, uses default for territory.

Parameters: calendar arbitrary calendar

Returns: this, for chaining

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setCollator

public GlobalizationPreferences setCollator(Collator collator)
Explicitly set the collator for this object.

Parameters: collator

Returns: this, for chaining

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setCurrency

public GlobalizationPreferences setCurrency(Currency currency)
Sets the currency code. If this has not been set, uses default for territory.

Parameters: currency Valid ISO 4217 currency code.

Returns: this, for chaining

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setDateFormat

public GlobalizationPreferences setDateFormat(int dateStyle, int timeStyle, DateFormat format)
Set an explicit date format. Overrides the locale priority list for a particular combination of dateStyle and timeStyle. DF_NONE should be used if for the style, where only the date or time format individually is being set.

Parameters: dateStyle DF_FULL, DF_LONG, DF_MEDIUM, DF_SHORT or DF_NONE timeStyle DF_FULL, DF_LONG, DF_MEDIUM, DF_SHORT or DF_NONE format The date format

Returns: this, for chaining

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setLocale

public GlobalizationPreferences setLocale(ULocale uLocale)
Convenience routine for setting the language/locale priority list from a single locale/language.

Parameters: uLocale single locale

Returns: this, for chaining

See Also: GlobalizationPreferences

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setLocales

public GlobalizationPreferences setLocales(List inputLocales)
Sets the language/locale priority list. If other information is not (yet) available, this is used to to produce a default value for the appropriate territory, currency, timezone, etc. The user should be given the opportunity to correct those defaults in case they are incorrect.

Parameters: inputLocales list of locales in priority order, eg {"be", "fr"} for Breton first, then French if that fails.

Returns: this, for chaining

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setLocales

public GlobalizationPreferences setLocales(ULocale[] uLocales)
Convenience routine for setting the language/locale priority list from an array.

Parameters: uLocales list of locales in an array

Returns: this, for chaining

See Also: GlobalizationPreferences

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setLocales

public GlobalizationPreferences setLocales(String acceptLanguageString)
Convenience routine for setting the locale priority list from an Accept-Language string.

Parameters: acceptLanguageString Accept-Language list, as defined by Section 14.4 of the RFC 2616 (HTTP 1.1)

Returns: this, for chaining

See Also: GlobalizationPreferences

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setNumberFormat

public GlobalizationPreferences setNumberFormat(int style, NumberFormat format)
Sets a number format explicitly. Overrides the general locale settings.

Parameters: style NF_NUMBER, NF_CURRENCY, NF_PERCENT, NF_SCIENTIFIC, NF_INTEGER format The number format

Returns: this, for chaining

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setTerritory

public GlobalizationPreferences setTerritory(String territory)
Sets the territory, which is a valid territory according to for RFC 3066 (or successor). If not otherwise set, default currency and timezone values will be set from this. The user should be given the opportunity to correct those defaults in case they are incorrect.

Parameters: territory code

Returns: this, for chaining

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setTimeZone

public GlobalizationPreferences setTimeZone(TimeZone timezone)
Sets the timezone ID. If this has not been set, uses default for territory.

Parameters: timezone a valid TZID (see UTS#35).

Returns: this, for chaining

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

Copyright (c) 2007 IBM Corporation and others.