net.time4j.tz

Interface ZoneProvider

All Known Subinterfaces:

ExtZoneProvider

public interface ZoneProvider

SPI interface which encapsulates the timezone repository and provides all necessary data for a given timezone id.

Implementations are usually stateless and should normally not try to manage a cache. Instead Time4J uses its own cache. The fact that this interface is used per java.util.ServiceLoader requires a concrete implementation to offer a public no-arg constructor.

Since:

2.2

See Also:

ServiceLoader

Method Summary

Modifier and Type	Method and Description
java.util.Map<java.lang.String,java.lang.String>	getAliases() Gets an alias table whose keys represent alternative identifiers mapped to other aliases or finally canonical timezone IDs..
java.util.Set<java.lang.String>	getAvailableIDs() Gets all available and supported timezone identifiers.
java.lang.String	getDisplayName(java.lang.String zoneID, NameStyle style, java.util.Locale locale) Returns the name of this timezone suitable for presentation to users in given style and locale.
java.lang.String	getFallback() Determines if in case of a failed search another ZoneProvider should be called as alternative with possibly different rules.
java.lang.String	getLocation() Describes the location or source of the repository.
java.lang.String	getName() Gets the name of the underlying repository.
java.util.Set<java.lang.String>	getPreferredIDs(java.util.Locale locale, boolean smart) Gets a Set of preferred timezone IDs for given ISO-3166-country code.
java.lang.String	getVersion() Queries the version of the underlying repository.
TransitionHistory	load(java.lang.String zoneID) Loads an offset transition history for given timezone id.

Method Detail

getAvailableIDs

java.util.Set<java.lang.String> getAvailableIDs()

Gets all available and supported timezone identifiers.

Returns:

unmodifiable set of timezone ids

See Also:

TimeZone.getAvailableIDs()

getPreferredIDs

java.util.Set<java.lang.String> getPreferredIDs(java.util.Locale locale,
                                                boolean smart)

Gets a Set of preferred timezone IDs for given ISO-3166-country code.

This information is necessary to enable parsing of timezone names.

Parameters:

locale - ISO-3166-alpha-2-country to be evaluated

smart - if true then try to select zone ids such that there is only one preferred id per zone name

Returns:

unmodifiable set of preferred timezone ids

getAliases

java.util.Map<java.lang.String,java.lang.String> getAliases()

Gets an alias table whose keys represent alternative identifiers mapped to other aliases or finally canonical timezone IDs..

Example: "PST" => "America/Los_Angeles".

Returns:

map from all timezone aliases to canoncial ids

load

TransitionHistory load(java.lang.String zoneID)

Loads an offset transition history for given timezone id.

The argument never contains the provider name as prefix. It is instead the part after the "~"-char (if not absent).

Parameters:

zoneID - timezone id (i.e. "Europe/London")

Returns:

timezone history or null if there are no data

Throws:

java.lang.IllegalArgumentException - if given id is wrong

java.lang.IllegalStateException - if timezone database is broken

See Also:

getAvailableIDs(), getAliases(), TimeZone.getTimeZone(String)

getFallback

java.lang.String getFallback()

Determines if in case of a failed search another ZoneProvider should be called as alternative with possibly different rules.

The special name "DEFAULT" can be used to denote the default zone provider. Note that the fallback provider will only affect the rules but not the id or display names of a new timezone.

Returns:

name of alternative provider or empty if no fallback happens

See Also:

load(String)

getName

java.lang.String getName()

Gets the name of the underlying repository.

The Olson/IANA-repository (and any provider which makes use of these data (direct or indirect)) has the name "TZDB". The names "java.util.TimeZone" and "DEFAULT" are reserved and cannot be used.

Returns:

String

getLocation

java.lang.String getLocation()

Describes the location or source of the repository.

Returns:

String which refers to an URI or empty if unknown

getVersion

java.lang.String getVersion()

Queries the version of the underlying repository.

In most cases the version has the Olson format starting with a four-digit year number followed by a small letter in range a-z.

Returns:

String (for example "2011n") or empty if unknown

getDisplayName

java.lang.String getDisplayName(java.lang.String zoneID,
                                NameStyle style,
                                java.util.Locale locale)

Returns the name of this timezone suitable for presentation to users in given style and locale.

The first argument never contains the provider name as prefix. It is instead the part after the "~"-char (if not absent).

Parameters:

zoneID - timezone id (i.e. "Europe/London")

style - name style

locale - language setting

Returns:

localized timezone name for display purposes or empty if not supported

See Also:

java.util.TimeZone.getDisplayName(boolean,int,Locale)