Timezone (time4j-android 3.6-2015f API)

java.lang.Object
- net.time4j.tz.Timezone

All Implemented Interfaces:

java.io.Serializable
```
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.

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.

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

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
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.

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 java.util.List<TZID> getAvailableIDs()
```
    Gets all available timezone IDs.
    
    Returns:
    
    unmodifiable list of available timezone ids in ascending order
  - getAvailableIDs
```
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.
    
    Parameters:
    
    provider - the registered zone provider whose ids are searched
    
    Returns:
    
    unmodifiable list of available timezone ids in ascending order
    
    Throws:
    
    java.lang.IllegalArgumentException - if the provider argument is empty
    
    Since:
    
    2.2
    
    See Also:
    
    ZoneProvider.getName()
  - getPreferredIDs
```
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.
    
    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 provider whose preferred ids are queried
    
    Returns:
    
    unmodifiable set of preferred timezone ids
    
    Throws:
    
    java.lang.IllegalArgumentException - if the provider argument is empty
    
    Since:
    
    2.2
    
    See Also:
    
    ZoneProvider.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 ZoneProvider.
    
    Parameters:
    
    tzid - timezone id as interface
    
    Returns:
    
    timezone data
    
    Throws:
    
    java.lang.IllegalArgumentException - if given timezone cannot be loaded
  - of
```
public static Timezone of(java.lang.String tzid)
```
    Gets the timezone for given identifier.
    
    Queries the underlying ZoneProvider.
    
    Parameters:
    
    tzid - timezone id as String
    
    Returns:
    
    timezone data
    
    Throws:
    
    java.lang.IllegalArgumentException - if given timezone cannot be loaded
  - of
```
public 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.
    
    Parameters:
    
    tzid - preferred timezone id
    
    fallback - alternative timezone id
    
    Returns:
    
    timezone data
  - of
```
public static Timezone of(java.lang.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:
    
    java.lang.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 Provider than java.util.TimeZone
  - getProviderInfo
```
public static java.lang.String getProviderInfo()
```
    Describes all registered ZoneProvider-instances with name and optionally location and version.
    
    Returns:
    
    String
  - getVersion
```
public static java.lang.String getVersion(java.lang.String provider)
```
    Tries to get the version of given registered zone provider.
    
    Parameters:
    
    provider - name of zone provider
    
    Returns:
    
    String (empty if unknown)
    
    Throws:
    
    java.lang.IllegalArgumentException - if the provider argument is empty
    
    Since:
    
    2.2
  - getRegisteredProviders
```
public static java.util.Set<java.lang.String> getRegisteredProviders()
```
    Yields the names of all registered ZoneProvider-instances.
    
    Returns:
    
    unmodifiable list of provider names
    
    Since:
    
    2.2
    
    See Also:
    
    ZoneProvider.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:
    
    java.lang.UnsupportedOperationException - if given strategy requires a transition history and this timezone does not have one
  - getDisplayName
```
public 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.
    
    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()
  - registerProvider
```
public static boolean registerProvider(ZoneProvider provider)
```
    Registers manually the given zone provider.
    
    Repeated registrations of the same provider are ignored.
    
    Parameters:
    
    provider - custom zone provider to be registered
    
    Returns:
    
    true if registration was successful else false
    
    Throws:
    
    java.lang.IllegalArgumentException - if given ZoneProvider refers to default, platform or TZDB-provider by name
    
    Since:
    
    2.2
  - dump
```
public void dump(java.lang.Appendable buffer)
          throws java.io.IOException
```
    Creates a dump of this timezone and writes it to the given buffer.
    
    Parameters:
    
    buffer - buffer to write the dump to
    
    Throws:
    
    java.io.IOException - in any case of I/O-errors
    
    Since:
    
    2.2

Class Timezone

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_CONFLICT_STRATEGY

STRICT_MODE

Method Detail

getAvailableIDs

getAvailableIDs

getPreferredIDs

ofSystem

of

of

of

of

getID

getOffset

getStandardOffset

getDaylightSavingOffset

getOffset

isInvalid

isDaylightSaving

isFixed

getHistory

getProviderInfo

getVersion

getRegisteredProviders

getStrategy

with

getDisplayName

registerProvider

dump