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.

Author:

Meno Hochschild

See Also:

Serialized Form

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.
static interface	Timezone.Provider SPI interface which encapsulates the timezone repository and provides all necessary data for a given timezone id.

Field Summary

Fields

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

Method Summary

Methods

Modifier and Type	Method and Description
static List<TZID>	getAvailableIDs() Gets all available timezone IDs.
String	getDisplayName(NameStyle style, Locale locale) Returns the name of this 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 offset for given global timestamp.
static Set<TZID>	getPreferredIDs(Locale locale) Gets a Set of preferred timezone IDs for given ISO-3166-country code.
static String	getProviderInfo() Describes the underlying repository with name and optionally location and version.
abstract TransitionStrategy	getStrategy() Gets the strategy for resolving local timestamps.
abstract boolean	isDaylightSaving(UnixTime ut) Queries if given global timestamp matches daylight saving time in this timezone?
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, 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.
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 JDK subtracts the next defined offset from any local timestamp in order to calculate the global time.

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.

Method Detail

getAvailableIDs

public static List<TZID> getAvailableIDs()

Gets all available timezone IDs.

Returns:

unmodifiable list of available timezone ids in ascending order

getPreferredIDs

public static Set<TZID> getPreferredIDs(Locale locale)

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

This information is necessary to enable parsing of timezone names and is only available if the olson-module "net.time4j.tz.olson" is accessible in class path.

Parameters:

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

Returns:

unmodifiable set of preferred timezone ids

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.

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.

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.

Parameters:

tzid - preferred timezone id

fallback - alternative timezone id

Returns:

timezone data

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 offset for given global timestamp.

Parameters:

ut - unix time

Returns:

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

See Also:

java.util.TimeZone.getOffset(long)

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.

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)

getHistory

public abstract TransitionHistory getHistory()

Gets the underlying offset transitions and rules if available.

Returns:

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

getProviderInfo

public static String getProviderInfo()

Describes the underlying repository with name and optionally location and version.

Returns:

String

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

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()