net.time4j.tz

Class Timezone

java.lang.Object

net.time4j.tz.Timezone

All Implemented Interfaces:

Serializable

public abstract class Timezone
extends Object
implements Serializable

Loads and keeps timezone data including the rules.

Timezones are identified by keys which have canonical forms as documented in TZID. If the keys don't specify any provider (no char "~") then the timezone data and rules will be looked up using the default ZoneModelProvider. This default provider is loaded by java.util.ServiceLoader if its name is equal to "TZDB" and its version string is not empty but of the highest value (lexicographically). If no such provider can be found then Time4J uses the platform provider based on the public API of java.util.TimeZone which does not expose its transition history however.

Note: The concept of timezones is strongly based on the idea to avoid any unrounded amounts of seconds or subseconds. Timezones were historically first introduced by british railway companies to guarantee fixed departure timetables. Consequently ISO-8601 only knows timezone offsets in full minutes. The widely used TZDB-repository of IANA knows in extreme case offsets in full seconds which is also allowed by Time4J. Although the Time4J-library recognizes fractional offsets based on the geographical longitude, its Timezone-API will always ignore any fractional parts.

Author:

Meno Hochschild

Concurrency:

All static methods are thread-safe while this class is immutable as long as the underlying timezone data are.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Timezone.Cache Offers some static methods for the configuration of the timezone cache.

Field Summary

Fields

Modifier and Type	Field and Description
static TransitionStrategy	DEFAULT_CONFLICT_STRATEGY This standard strategy which is also used by the JDK-class java.util.GregorianCalendar subtracts the next defined offset from any local timestamp in order to calculate the global time while pushing forward an invalid local time.
static TransitionStrategy	STRICT_MODE In addition to the standard strategy, this strategy ensures the use of valid local timestamps.

Method Summary

Modifier and Type	Method and Description
void	dump(Appendable buffer) Creates a dump of this timezone and writes it to the given buffer.
static List<TZID>	getAvailableIDs() Gets all available timezone IDs.
static List<TZID>	getAvailableIDs(String provider) Gets all available timezone IDs for given ZoneModelProvider.
abstract ZonalOffset	getDaylightSavingOffset(UnixTime ut) Calculates the dst-offset for given global timestamp.
String	getDisplayName(NameStyle style, Locale locale) Returns the name of this timezone suitable for presentation to users in given style and locale.
static String	getDisplayName(TZID tzid, NameStyle style, Locale locale) Returns the name of a timezone suitable for presentation to users in given style and locale.
abstract TransitionHistory	getHistory() Gets the underlying offset transitions and rules if available.
abstract TZID	getID() Gets the associated timezone identifier.
abstract ZonalOffset	getOffset(GregorianDate localDate, WallTime localTime) Calculates the offset for given local timestamp.
abstract ZonalOffset	getOffset(UnixTime ut) Calculates the total offset for given global timestamp.
static Set<TZID>	getPreferredIDs(Locale locale, boolean smart, String provider) Gets a provider-specific Set of preferred timezone IDs for given ISO-3166-country code.
static String	getProviderInfo() Describes all registered ZoneModelProvider-instances with name and optionally location and version.
static Set<String>	getRegisteredProviders() Yields the names of all registered ZoneModelProvider-instances.
abstract ZonalOffset	getStandardOffset(UnixTime ut) Calculates the standard offset for given global timestamp.
abstract TransitionStrategy	getStrategy() Gets the strategy for resolving local timestamps.
static String	getVersion(String provider) Tries to get the version of given registered zone model provider.
abstract boolean	isDaylightSaving(UnixTime ut) Queries if given global timestamp matches daylight saving time in this timezone?
abstract boolean	isFixed() Determines if this timezone has no offset transitions and always uses a fixed offset.
abstract boolean	isInvalid(GregorianDate localDate, WallTime localTime) Evaluates if given local timestamp is invalid due to a gap on the local timeline.
static Timezone	of(String tzid) Gets the timezone for given identifier.
static Timezone	of(String tzid, TransitionHistory history) Creates a new synthetic timezone based only on given data.
static Timezone	of(String tzid, TZID fallback) Tries to load the timezone with the first given identifer else with given alternative identifier.
static Timezone	of(TZID tzid) Gets the timezone for given identifier.
static Timezone	ofSystem() Gets the system timezone.
static boolean	registerProvider(ZoneModelProvider provider) Registers manually the given zone model provider.
abstract Timezone	with(TransitionStrategy strategy) Creates a copy of this timezone which uses given strategy for resolving local timestamps.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CONFLICT_STRATEGY

public static final TransitionStrategy DEFAULT_CONFLICT_STRATEGY

This standard strategy which is also used by the JDK-class java.util.GregorianCalendar subtracts the next defined offset from any local timestamp in order to calculate the global time while pushing forward an invalid local time.

Equivalent to GapResolver.PUSH_FORWARD.and(OverlapResolver.LATER_OFFSET).

See Also:

getOffset(GregorianDate,WallTime)

STRICT_MODE

public static final TransitionStrategy STRICT_MODE

In addition to the standard strategy, this strategy ensures the use of valid local timestamps.

Equivalent to GapResolver.ABORT.and(OverlapResolver.LATER_OFFSET).

Method Detail

getAvailableIDs

public static List<TZID> getAvailableIDs()

Gets all available timezone IDs.

Returns:

unmodifiable list of available timezone ids in ascending order

getAvailableIDs

public static List<TZID> getAvailableIDs(String provider)

Gets all available timezone IDs for given ZoneModelProvider.

Note that this method will return an empty list if given provider name does not refer to any registered provider. If the name is equal to "DEFAULT" then the default ZoneModelProvider will be queried.

Parameters:

provider - the registered zone model provider whose ids are searched

Returns:

unmodifiable list of available timezone ids in ascending order

Throws:

IllegalArgumentException - if the provider argument is empty

Since:

2.2

See Also:

ZoneModelProvider.getName(), ZoneModelProvider.getAvailableIDs()

getPreferredIDs

public static Set<TZID> getPreferredIDs(Locale locale,
                                        boolean smart,
                                        String provider)

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

This information is necessary to enable parsing of timezone names. If the given provider does not denote a valid registered zone model provider then this method will produce an empty set. if given provider name is "DEFAULT" then the default zone name provider will be queried.

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

provider - the registered zone model provider whose preferred ids are queried

Returns:

unmodifiable set of preferred timezone ids

Throws:

IllegalArgumentException - if the provider argument is empty

Since:

2.2

See Also:

ZoneModelProvider.getSpecificZoneNameRepository(), ZoneNameProvider.getPreferredIDs(Locale, boolean)

ofSystem

public static Timezone ofSystem()

Gets the system timezone.

The underlying algorithm to determine the system timezone is primarily based on the system property "user.timezone" then on the method java.util.TimeZone.getDefault(). If the system property "net.time4j.allow.system.tz.override" is set to "true" then the system timezone can be changed by a combined approach of java.util.TimeZone.setDefault() and the method Timezone.Cache.refresh(). Otherwise this class will determine the system timezone only for one time while being loaded.

Note: If the system timezone cannot be determined (for example due to a wrong property value for "user.timezone") then this method will fall back to UTC timezone..

Returns:

default timezone data of system

See Also:

java.util.TimeZone.getDefault()

of

public static Timezone of(TZID tzid)

Gets the timezone for given identifier.

Queries the underlying ZoneModelProvider.

Parameters:

tzid - timezone id as interface

Returns:

timezone data

Throws:

IllegalArgumentException - if given timezone cannot be loaded

of

public static Timezone of(String tzid)

Gets the timezone for given identifier.

Queries the underlying ZoneModelProvider.

Parameters:

tzid - timezone id as String

Returns:

timezone data

Throws:

IllegalArgumentException - if given timezone cannot be loaded

of

public static Timezone of(String tzid,
                          TZID fallback)

Tries to load the timezone with the first given identifer else with given alternative identifier.

If the timezone cannot be loaded with first identifier then this method will load the timezone using the alternative. In case of failure, this method will finally load the system timezone. In contrast to of(TZID), this method never throws any exception.

Queries the underlying ZoneModelProvider.

Parameters:

tzid - preferred timezone id

fallback - alternative timezone id

Returns:

timezone data

of

public static Timezone of(String tzid,
                          TransitionHistory history)

Creates a new synthetic timezone based only on given data.

Parameters:

tzid - timezone id

history - history of offset transitions

Returns:

new instance of timezone data

Throws:

IllegalArgumentException - if a fixed zonal offset is combined with a non-empty history

Since:

2.2

getID

public abstract TZID getID()

Gets the associated timezone identifier.

Returns:

timezone id

See Also:

java.util.TimeZone.getID()

getOffset

public abstract ZonalOffset getOffset(UnixTime ut)

Calculates the total offset for given global timestamp.

Note: The returned offset has never any subsecond part, normally not even seconds but full minutes or hours.

Parameters:

ut - unix time

Returns:

total shift in seconds which yields local time if added to unix time

See Also:

java.util.TimeZone.getOffset(long), getStandardOffset(UnixTime), getDaylightSavingOffset(UnixTime)

getStandardOffset

public abstract ZonalOffset getStandardOffset(UnixTime ut)

Calculates the standard offset for given global timestamp.

Note: The returned offset has never any subsecond part, normally not even seconds but full minutes or hours.

Parameters:

ut - unix time

Returns:

standard shift in seconds which yields standard local time if added to unix time

Since:

3.2/4.1

getDaylightSavingOffset

public abstract ZonalOffset getDaylightSavingOffset(UnixTime ut)

Calculates the dst-offset for given global timestamp.

Note: The returned offset has never any subsecond part, normally not even seconds but full minutes or hours.

Parameters:

ut - unix time

Returns:

dst-shift in seconds which yields local wall time if added to standard local time

Since:

3.2/4.1

getOffset

public abstract ZonalOffset getOffset(GregorianDate localDate,
                                      WallTime localTime)

Calculates the offset for given local timestamp.

In case of gaps or overlaps, this method uses the standard strategy to get the next defined offset. This behaviour is conform to the JDK-class java.util.GregorianCalendar.

Note: The returned offset has never any subsecond part, normally not even seconds but full minutes or hours.

Parameters:

localDate - local date in timezone

localTime - local wall time in timezone

Returns:

shift in seconds which yields unix time if subtracted from local time choosing later offset at gaps or overlaps

See Also:

java.util.TimeZone.getOffset(int, int, int, int, int, int)

isInvalid

public abstract boolean isInvalid(GregorianDate localDate,
                                  WallTime localTime)

Evaluates if given local timestamp is invalid due to a gap on the local timeline.

A typical example is the transition from standard to daylight saving time because the clock will be manually adjusted such that the clock is moved forward by usually one hour.

Parameters:

localDate - local date in timezone

localTime - local wall time in timezone

Returns:

true if the local time is not defined due to transition gaps else false

isDaylightSaving

public abstract boolean isDaylightSaving(UnixTime ut)

Queries if given global timestamp matches daylight saving time in this timezone?

The DST correction can be obtained as difference between total offset and raw offset if the raw offset has not changed yet. As alternative the DST correction can be obtained by evaluating the transition offset history.

Parameters:

ut - unix time

Returns:

true if the argument represents summer time else false

See Also:

java.util.TimeZone.inDaylightTime(java.util.Date)

isFixed

public abstract boolean isFixed()

Determines if this timezone has no offset transitions and always uses a fixed offset.

Returns:

true if there is no transition else false

Since:

1.2.1

getHistory

public abstract TransitionHistory getHistory()

Gets the underlying offset transitions and rules if available.

Returns:

TransitionHistory or null if there is no better ZoneModelProvider than java.util.TimeZone

getProviderInfo

public static String getProviderInfo()

Describes all registered ZoneModelProvider-instances with name and optionally location and version.

Returns:

String

getVersion

public static String getVersion(String provider)

Tries to get the version of given registered zone model provider.

Parameters:

provider - name of zone model provider

Returns:

String (empty if unknown)

Throws:

IllegalArgumentException - if the provider argument is empty

Since:

2.2

getRegisteredProviders

public static Set<String> getRegisteredProviders()

Yields the names of all registered ZoneModelProvider-instances.

Returns:

unmodifiable list of provider names

Since:

2.2

See Also:

ZoneModelProvider.getName()

getStrategy

public abstract TransitionStrategy getStrategy()

Gets the strategy for resolving local timestamps.

Returns:

transition strategy for resolving local timestamps

See Also:

with(TransitionStrategy)

with

public abstract Timezone with(TransitionStrategy strategy)

Creates a copy of this timezone which uses given strategy for resolving local timestamps.

If this timezone has a fixed offset then the strategy will be ignored because in this case there can never be a conflict. Otherwise if there is no public offset transition history then the only supported strategies are DEFAULT_CONFLICT_STRATEGY and STRICT_MODE.

Parameters:

strategy - transition strategy for resolving local timestamps

Returns:

copy of this timezone with given strategy

Throws:

UnsupportedOperationException - if given strategy requires a transition history and this timezone does not have one

getDisplayName

public String getDisplayName(NameStyle style,
                             Locale locale)

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

If the name is not available then this method will yield the ID of this timezone.

Parameters:

style - name style

locale - language setting

Returns:

localized timezone name for display purposes

See Also:

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

getDisplayName

public static String getDisplayName(TZID tzid,
                                    NameStyle style,
                                    Locale locale)

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

If the name is not available then this method will yield the canonical ID of given timezone identifier.

Parameters:

tzid - timezone id

style - name style

locale - language setting

Returns:

localized timezone name for display purposes

Since:

3.20/4.16

See Also:

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

registerProvider

public static boolean registerProvider(ZoneModelProvider provider)

Registers manually the given zone model provider.

Repeated registrations of the same provider are ignored.

Parameters:

provider - custom zone model provider to be registered

Returns:

true if registration was successful else false

Throws:

IllegalArgumentException - if given ZoneModelProvider refers to default, platform or TZDB-provider by name

Since:

3.20/4.16

dump

public void dump(Appendable buffer)
          throws IOException

Creates a dump of this timezone and writes it to the given buffer.

Parameters:

buffer - buffer to write the dump to

Throws:

IOException - in any case of I/O-errors

Since:

2.2