com.ibm.icu.text
Class TimeZoneNames

java.lang.Object
  com.ibm.icu.text.TimeZoneNames

All Implemented Interfaces:

Serializable

Deprecated. This API might change or be removed in a future release.

public abstract class TimeZoneNames
extends Object
implements Serializable

TimeZoneNames is an abstract class representing the time zone display name data model defined by UTS#35 Unicode Locale Data Markup Language (LDML). The model defines meta zone, which is used for storing a set of display names. A meta zone can be shared by multiple time zones. Also a time zone may have multiple meta zone historic mappings.

For example, people in the United States refer the zone used by the east part of North America as "Eastern Time". The tz database contains multiple time zones "America/New_York", "America/Detroit", "America/Montreal" and some others that belong to "Eastern Time". However, assigning different display names to these time zones does not make much sense for most of people.

In CLDR (which uses LDML for representing locale data), the display name "Eastern Time" is stored as long generic display name of a meta zone identified by the ID "America_Eastern". Then, there is another table maintaining the historic mapping to meta zones for each time zone. The time zones in the above example ("America/New_York", "America/Detroit"...) are mapped to the meta zone "America_Eastern".

Sometimes, a time zone is mapped to a different time zone in the past. For example, "America/Indiana/Knox" had been moving "Eastern Time" and "Central Time" back and forth. Therefore, it is necessary that time zone to meta zones mapping data are stored by date range.

Note:

TimeZoneFormat assumes an instance of TimeZoneNames is immutable. If you want to provide your own TimeZoneNames implementation and use it with TimeZoneFormat, you must follow the contract.

The methods in this class assume that time zone IDs are already canonicalized. For example, you may not get proper result returned by a method with time zone ID "America/Indiana/Indianapolis", because it's not a canonical time zone ID (the canonical time zone ID for the time zone is "America/Indianapolis". See TimeZone.getCanonicalID(String) about ICU canonical time zone IDs.

In CLDR, most of time zone display names except location names are provided through meta zones. But a time zone may have a specific name that is not shared with other time zones. For example, time zone "Europe/London" has English long name for standard time "Greenwich Mean Time", which is also shared with other time zones. However, the long name for daylight saving time is "British Summer Time", which is only used for "Europe/London".

getTimeZoneDisplayName(String, NameType) is designed for accessing a name only used by a single time zone. But is not necessarily mean that a subclass implementation use the same model with CLDR. A subclass implementation may provide time zone names only through getTimeZoneDisplayName(String, NameType), or only through getMetaZoneDisplayName(String, NameType), or both.

See Also:

Serialized Form

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

Nested Class Summary

static class	TimeZoneNames.Factory Deprecated. The super class of TimeZoneNames service factory classes.
static class	TimeZoneNames.MatchInfo Deprecated. This API might change or be removed in a future release.
static class	TimeZoneNames.NameType Deprecated. This API might change or be removed in a future release.

Constructor Summary

protected

TimeZoneNames() Deprecated. This API might change or be removed in a future release.

Method Summary

Collection<TimeZoneNames.MatchInfo>	find(String text, int start, EnumSet<TimeZoneNames.NameType> types) Deprecated. This API might change or be removed in a future release.
abstract Set<String>	getAvailableMetaZoneIDs() Deprecated. This API might change or be removed in a future release.
abstract Set<String>	getAvailableMetaZoneIDs(String tzID) Deprecated. This API might change or be removed in a future release.
String	getDisplayName(String tzID, TimeZoneNames.NameType type, long date) Deprecated. This API might change or be removed in a future release.
String	getExemplarLocationName(String tzID) Deprecated. This API might change or be removed in a future release.
static TimeZoneNames	getInstance(ULocale locale) Deprecated. This API might change or be removed in a future release.
abstract String	getMetaZoneDisplayName(String mzID, TimeZoneNames.NameType type) Deprecated. This API might change or be removed in a future release.
abstract String	getMetaZoneID(String tzID, long date) Deprecated. This API might change or be removed in a future release.
abstract String	getReferenceZoneID(String mzID, String region) Deprecated. This API might change or be removed in a future release.
abstract String	getTimeZoneDisplayName(String tzID, TimeZoneNames.NameType type) Deprecated. This API might change or be removed in a future release.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TimeZoneNames

protected TimeZoneNames()

Deprecated. This API might change or be removed in a future release.

Sole constructor for invocation by subclass constructors.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

Method Detail

getInstance

public static TimeZoneNames getInstance(ULocale locale)

Deprecated. This API might change or be removed in a future release.

Returns an instance of TimeZoneDisplayNames for the specified locale.

Parameters:

locale - The locale.

Returns:

An instance of TimeZoneDisplayNames

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getAvailableMetaZoneIDs

public abstract Set<String> getAvailableMetaZoneIDs()

Deprecated. This API might change or be removed in a future release.

Returns an immutable set of all available meta zone IDs.

Returns:

An immutable set of all available meta zone IDs.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getAvailableMetaZoneIDs

public abstract Set<String> getAvailableMetaZoneIDs(String tzID)

Deprecated. This API might change or be removed in a future release.

Returns an immutable set of all available meta zone IDs used by the given time zone.

Parameters:

tzID - The canonical time zone ID.

Returns:

An immutable set of all available meta zone IDs used by the given time zone.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getMetaZoneID

public abstract String getMetaZoneID(String tzID,
                                     long date)

Deprecated. This API might change or be removed in a future release.

Returns the meta zone ID for the given canonical time zone ID at the given date.

Parameters:

tzID - The canonical time zone ID.

date - The date.

Returns:

The meta zone ID for the given time zone ID at the given date. If the time zone does not have a corresponding meta zone at the given date or the implementation does not support meta zones, null is returned.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getReferenceZoneID

public abstract String getReferenceZoneID(String mzID,
                                          String region)

Deprecated. This API might change or be removed in a future release.

Returns the reference zone ID for the given meta zone ID for the region.

Parameters:

mzID - The meta zone ID.

region - The region.

Returns:

The reference zone ID ("golden zone" in the LDML specification) for the given time zone ID for the region. If the meta zone is unknown or the implementation does not support meta zones, null is returned.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getMetaZoneDisplayName

public abstract String getMetaZoneDisplayName(String mzID,
                                              TimeZoneNames.NameType type)

Deprecated. This API might change or be removed in a future release.

Returns the display name of the meta zone.

Parameters:

mzID - The meta zone ID.

type - The display name type. See TimeZoneNames.NameType.

Returns:

The display name of the meta zone. When this object does not have a localized display name for the given meta zone with the specified type or the implementation does not provide any display names associated with meta zones, null is returned.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getDisplayName

public final String getDisplayName(String tzID,
                                   TimeZoneNames.NameType type,
                                   long date)

Deprecated. This API might change or be removed in a future release.

Returns the display name of the time zone at the given date.

Note: This method calls the subclass's getTimeZoneDisplayName(String, NameType) first. When the result is null, this method calls getMetaZoneID(String, long) to get the meta zone ID mapped from the time zone, then calls getMetaZoneDisplayName(String, NameType).

Parameters:

tzID - The canonical time zone ID.

type - The display name type. See TimeZoneNames.NameType.

date - The date

Returns:

The display name for the time zone at the given date. When this object does not have a localized display name for the time zone with the specified type and date, null is returned.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getTimeZoneDisplayName

public abstract String getTimeZoneDisplayName(String tzID,
                                              TimeZoneNames.NameType type)

Deprecated. This API might change or be removed in a future release.

Returns the display name of the time zone. Unlike getDisplayName(String, NameType, long), this method does not get a name from a meta zone used by the time zone.

Parameters:

tzID - The canonical time zone ID.

type - The display name type. See TimeZoneNames.NameType.

Returns:

The display name for the time zone. When this object does not have a localized display name for the given time zone with the specified type, null is returned.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getExemplarLocationName

public String getExemplarLocationName(String tzID)

Deprecated. This API might change or be removed in a future release.

Returns the exemplar location name for the given time zone. When this object does not have a localized location name, the default implementation may still returns a programmatically generated name with the logic described below.

1. Check if the ID contains "/". If not, return null.
2. Check if the ID does not start with "Etc/" or "SystemV/". If it does, return null.
3. Extract a substring after the last occurrence of "/".
4. Replace "_" with " ".

For example, "New York" is returned for the time zone ID "America/New_York" when this object does not have the localized location name.

Parameters:

tzID - The canonical time zone ID

Returns:

The exemplar location name for the given time zone, or null when a localized location name is not available and the fallback logic described above cannot extract location from the ID.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

find

public Collection<TimeZoneNames.MatchInfo> find(String text,
                                                int start,
                                                EnumSet<TimeZoneNames.NameType> types)

Deprecated. This API might change or be removed in a future release.

Finds time zone name prefix matches for the input text at the given offset and returns a collection of the matches.

Parameters:

text - the text.

start - the starting offset within the text.

types - the set of name types, or null for all name types.

Returns:

A collection of matches.

See Also:

TimeZoneNames.NameType, TimeZoneNames.MatchInfo

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.