public abstract class Timezone
extends java.lang.Object
implements java.io.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 ZoneProvider. 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.
| Modifier and Type | Class and Description |
|---|---|
static class |
Timezone.Cache
Offers some static methods for the configuration of the
timezone cache.
|
| 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. |
| Modifier and Type | Method and Description |
|---|---|
void |
dump(java.lang.Appendable buffer)
Creates a dump of this timezone and writes it to the given
buffer.
|
static java.util.List<TZID> |
getAvailableIDs()
Gets all available timezone IDs.
|
static java.util.List<TZID> |
getAvailableIDs(java.lang.String provider)
Gets all available timezone IDs for given
ZoneProvider. |
abstract ZonalOffset |
getDaylightSavingOffset(UnixTime ut)
Calculates the dst-offset for given global timestamp.
|
java.lang.String |
getDisplayName(NameStyle style,
java.util.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 total offset for given global timestamp.
|
static java.util.Set<TZID> |
getPreferredIDs(java.util.Locale locale,
boolean smart,
java.lang.String provider)
Gets a provider-specific
Set of preferred timezone IDs
for given ISO-3166-country code. |
static java.lang.String |
getProviderInfo()
Describes all registered
ZoneProvider-instances with
name and optionally location and version. |
static java.util.Set<java.lang.String> |
getRegisteredProviders()
Yields the names of all registered
ZoneProvider-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 java.lang.String |
getVersion(java.lang.String provider)
Tries to get the version of given registered zone 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(java.lang.String tzid)
Gets the timezone for given identifier.
|
static Timezone |
of(java.lang.String tzid,
TransitionHistory history)
Creates a new synthetic timezone based only on given data.
|
static Timezone |
of(java.lang.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(ZoneProvider provider)
Registers manually the given zone provider.
|
abstract Timezone |
with(TransitionStrategy strategy)
Creates a copy of this timezone which uses given strategy for
resolving local timestamps.
|
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).
getOffset(GregorianDate,WallTime)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).
public static java.util.List<TZID> getAvailableIDs()
Gets all available timezone IDs.
public static java.util.List<TZID> getAvailableIDs(java.lang.String provider)
Gets all available timezone IDs for given ZoneProvider.
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 ZoneProvider will be
queried.
provider - the registered zone provider whose ids are searchedjava.lang.IllegalArgumentException - if the provider argument is emptyZoneProvider.getName()public static java.util.Set<TZID> getPreferredIDs(java.util.Locale locale, boolean smart, java.lang.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 and is only available if the given provider supports it and denotes a valid registered provider. Otherwise this method will produce an empty set. if given provider name is "DEFAULT" then the default zone provider will be queried.
locale - ISO-3166-alpha-2-country to be evaluatedsmart - if true then try to select zone ids such
that there is only one preferred id per zone nameprovider - the registered zone provider whose preferred ids
are queriedjava.lang.IllegalArgumentException - if the provider argument is emptyZoneProvider.getPreferredIDs(Locale, boolean)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..
java.util.TimeZone.getDefault()public static Timezone of(TZID tzid)
Gets the timezone for given identifier.
Queries the underlying ZoneProvider.
tzid - timezone id as interfacejava.lang.IllegalArgumentException - if given timezone cannot be loadedpublic static Timezone of(java.lang.String tzid)
Gets the timezone for given identifier.
Queries the underlying ZoneProvider.
tzid - timezone id as Stringjava.lang.IllegalArgumentException - if given timezone cannot be loadedpublic static Timezone of(java.lang.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 ZoneProvider.
tzid - preferred timezone idfallback - alternative timezone idpublic static Timezone of(java.lang.String tzid, TransitionHistory history)
Creates a new synthetic timezone based only on given data.
tzid - timezone idhistory - history of offset transitionsjava.lang.IllegalArgumentException - if a fixed zonal offset is combined
with a non-empty historypublic abstract TZID getID()
Gets the associated timezone identifier.
java.util.TimeZone.getID()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.
ut - unix timejava.util.TimeZone.getOffset(long),
getStandardOffset(UnixTime),
getDaylightSavingOffset(UnixTime)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.
ut - unix timepublic 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.
ut - unix timepublic 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.
localDate - local date in timezonelocalTime - local wall time in timezonejava.util.TimeZone.getOffset(int, int, int, int, int, int)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.
localDate - local date in timezonelocalTime - local wall time in timezonetrue if the local time is not defined due to
transition gaps else falsepublic 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.
ut - unix timetrue if the argument represents summer time
else falsejava.util.TimeZone.inDaylightTime(java.util.Date)public abstract boolean isFixed()
Determines if this timezone has no offset transitions and always uses a fixed offset.
true if there is no transition else falsepublic abstract TransitionHistory getHistory()
Gets the underlying offset transitions and rules if available.
TransitionHistory or null if there is no
better Provider than java.util.TimeZonepublic static java.lang.String getProviderInfo()
Describes all registered ZoneProvider-instances with
name and optionally location and version.
public static java.lang.String getVersion(java.lang.String provider)
Tries to get the version of given registered zone provider.
provider - name of zone providerjava.lang.IllegalArgumentException - if the provider argument is emptypublic static java.util.Set<java.lang.String> getRegisteredProviders()
Yields the names of all registered
ZoneProvider-instances.
ZoneProvider.getName()public abstract TransitionStrategy getStrategy()
Gets the strategy for resolving local timestamps.
with(TransitionStrategy)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.
strategy - transition strategy for resolving local timestampsjava.lang.UnsupportedOperationException - if given strategy requires
a transition history and this timezone does not have onepublic java.lang.String getDisplayName(NameStyle style, java.util.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.
style - name stylelocale - language settingjava.util.TimeZone.getDisplayName(boolean,int,Locale),
Locale.getDefault(),
getID()public static boolean registerProvider(ZoneProvider provider)
Registers manually the given zone provider.
Repeated registrations of the same provider are ignored.
provider - custom zone provider to be registeredtrue if registration was successful else falsejava.lang.IllegalArgumentException - if given ZoneProvider
refers to default, platform or TZDB-provider by namepublic void dump(java.lang.Appendable buffer)
throws java.io.IOException
Creates a dump of this timezone and writes it to the given buffer.
buffer - buffer to write the dump tojava.io.IOException - in any case of I/O-errors