Package 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.

Note: All static methods are threadsafe while this class is immutable as long as the underlying timezone data are.

Author:
Meno Hochschild

  • Field Details

    • 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 Details

    • 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.

      Once the identifier of the system timezone has been evaluated, it will be combined with the best available timezone data and rules.

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

    • ofPlatform

      public static Timezone ofPlatform()

      Obtains the platform timezone with data and rules of the platform.

      Note that this method will never access the timezone repository of Time4J. In contrast, Timezone.ofSystem() only evaluates the identifier of the system timezone and combines it with the best available data and rules (possibly based on Time4J-data). Using the platform data can only be recommended in some situations on mobile platforms where device users try to compensate bad timezone data by adjusting the clock. Hence this method would help to achieve the correct local time as set on the mobile device.

      Returns:
      system timezone using the platform timezone data and rules
      Since:
      3.29/4.25
      See Also:
      ofSystem(), TimeZone

    • 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

    • normalize

      public static TZID normalize​(TZID tzid)

      Equivalent to normalize(tzid.canonical()).

      Parameters:
      tzid - timezone id which might need normalization
      Returns:
      normalized identifier
      Throws:
      IllegalArgumentException - if given identifier is invalid (for example empty)
      Since:
      4.36
      See Also:
      normalize(String)

    • normalize

      public static TZID normalize​(String tzid)

      Tries to normalize given timezone identifier on the base of best efforts.

      This method is only capable of resolving old aliases like "Asia/Calcutta" to modern identifiers (like "Asia/Kolkata") if the underlying ZoneModelProvider supports resolving of aliases. This is true if the tzdata-module is present on the class-path. However, the standard platform zone data do not support such a feature. But fixed offsets like "UTC+01" or the outdated form "Etc/GMT+4" can always be resolved to instances of ZonalOffset.

      Parameters:
      tzid - timezone id which might need normalization
      Returns:
      normalized identifier
      Throws:
      IllegalArgumentException - if given identifier is invalid (for example empty)
      Since:
      3.41/4.36
      See Also:
      TZID.canonical(), ZonalOffset.parse(String), ZoneId.normalized()

    • 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), getRawOffset(UnixTime), getExtraOffset(UnixTime)

    • getRawOffset

      public abstract ZonalOffset getRawOffset​(UnixTime ut)

      Calculates the raw 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:
      raw shift in seconds which yields standard local time if added to unix time
      Since:
      5.5

    • getExtraOffset

      public abstract ZonalOffset getExtraOffset​(UnixTime ut)

      Calculates the extra shift for given global timestamp, in addition to the raw shift.

      Notes: The returned offset has never any subsecond part, normally not even seconds but full minutes or hours. Starting with tzdb-version 2018b, the obtained daylight saving amount might also be negative in some rare cases, see the case of Ireland (Europe/Dublin) which has a negative DST-offset in winter and zero in summer standard time. Users are asked not to interprete too much in this method. It should only be interpreted as deviation relative to standard time (what ever this might be).

      Parameters:
      ut - unix time
      Returns:
      extra shift in seconds which yields local wall time if added to standard local time
      Since:
      5.5
      See Also:
      isDaylightSaving(UnixTime)

    • getStandardOffset

      @Deprecated public final ZonalOffset getStandardOffset​(UnixTime ut)
      Deprecated.
      This method was renamed, use getRawOffset(UnixTime) instead.

      Calculates the standard offset for given global timestamp.

      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

      @Deprecated public final ZonalOffset getDaylightSavingOffset​(UnixTime ut)
      Deprecated.
      This method was renamed, use getExtraOffset(UnixTime) instead.

      Calculates the daylight saving amount for given global timestamp.

      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
      See Also:
      isDaylightSaving(UnixTime)

    • 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 the local clock has been adjusted forward at given timestamp.

      This usually means if the given time matches daylight saving time relative to winter 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. About the rare case of Ireland which observes standard time in summer and has a negative DST correction in winter (using the TZDB-version 2018b), this method will yield true in summer and false in winter.

      Parameters:
      ut - unix time
      Returns:
      true if the argument represents any kind of 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