Package net.time4j.scale

Class LeapSeconds

java.lang.Object
net.time4j.scale.LeapSeconds
All Implemented Interfaces:
Iterable<LeapSecondEvent>, Comparator<LeapSecondEvent>
public final class LeapSeconds extends Object implements Iterable<LeapSecondEvent>, Comparator<LeapSecondEvent>

Holds all leap seconds occurred since the official start of UTC in 1972.

The source is either an implementation of the SPI-interface Provider loaded by a ServiceLoader or an internal standard implementation of Provider which accesses the file "leapseconds.data". This resource file must be in the classpath (in folder data). It has the format of a CSV-ASCII-text which has two columns separated by comma. The first column denotes the calendar day after the leap second shift in ISO-8601-format (for example 1972-07-01). The second column determines the sign of the leap second (+/-).

The source will mainly be loaded by the context classloader else by application classloader. If there is no source at all then Time4J assumes that leap seconds shall not be used.

The system property "net.time4j.scale.leapseconds.suppressed" determines if leap seconds shall be active at all. If this system property has the value true then this class will never register any leap seconds equal if the underlying sources are filled or not. Furthermore, the system property "net.time4j.scale.leapseconds.final" determines if leap seconds are only registered at system start or if new ones can be lazily registered at runtime using the methods registerXYZ(). Setting one of both properties can improve the performance.

Note: This implementation is threadsafe.

Author:
Meno Hochschild

  • Field Details

    • SUPPRESS_UTC_LEAPSECONDS

      public static final boolean SUPPRESS_UTC_LEAPSECONDS

      System property "net.time4j.scale.leapseconds.suppressed" which determines that no leap seconds shall be loaded and used.

      Defined values: "true" (suppressed) or "false" (active - default).

    • FINAL_UTC_LEAPSECONDS

      public static final boolean FINAL_UTC_LEAPSECONDS

      System property "net.time4j.scale.leapseconds.final" which determines that leap seconds can be loaded only one time at system start.

      Defined values: "true" (final) or "false" (enables lazy regisration - default).

    • PATH_TO_LEAPSECONDS

      public static final String PATH_TO_LEAPSECONDS

      System property "net.time4j.scale.leapseconds.path" which determines the path of the leap second file.

      Setting this property will usually suppress other leap second providers even if they have registered more leap seconds. The path is an URL which must be understood by ClassLoader.getResourceAsStream(String). The default value is: "data/leapseconds.data" (relative to class path).

      Since:
      2.1.2

  • Method Details

    • getInstance

      public static LeapSeconds getInstance()

      Returns the singleton instance.

      Returns:
      singleton instance

    • isEnabled

      public boolean isEnabled()

      Queries if the leap second support is activated.

      Returns:
      true if leap seconds are supported and are also registered else false
      See Also:
      SUPPRESS_UTC_LEAPSECONDS

    • isExtensible

      public boolean isExtensible()

      Queries if a lazy registration of leap seconds is possible.

      If the leap second support is switched off then a registration of leap seconds is never possible so this method will be ignored.

      Returns:
      true if the method registerXYZ() can be called without exception else false
      See Also:
      registerPositiveLS(int, int, int), registerNegativeLS(int, int, int), FINAL_UTC_LEAPSECONDS, isEnabled()

    • getCount

      public int getCount()

      Yields the count of all registered leap seconds.

      Returns:
      count of registered leap seconds

    • getCount

      public int getCount​(UnixTime until)

      Yields the count of all registered leap seconds which happened before given timestamp.

      Parameters:
      until - the upper search limit (exclusive)
      Returns:
      count of registered leap seconds happening before
      Since:
      3.28/4.24
      See Also:
      getCount()

    • registerPositiveLS

      public void registerPositiveLS​(int year, int month, int dayOfMonth)

      Registers a new positive leap second by defining the switch-over-day.

      Parameters:
      year - proleptic iso year
      month - gregorian month in range (1-12)
      dayOfMonth - day of month in range (1-31)
      Throws:
      IllegalStateException - if support of leap seconds is switched off by configuration or if the value of system property "net.time4j.utc.leapseconds.final" is true
      IllegalArgumentException - if the new event is not after the last stored event or if the date is invalid
      See Also:
      isExtensible(), isEnabled(), SUPPRESS_UTC_LEAPSECONDS, FINAL_UTC_LEAPSECONDS

    • registerNegativeLS

      public void registerNegativeLS​(int year, int month, int dayOfMonth)

      Registers a new negative leap second by defining the switch-over-day.

      Parameters:
      year - proleptic iso year
      month - gregorian month in range (1-12)
      dayOfMonth - day of month in range (1-31)
      Throws:
      IllegalStateException - if support of leap seconds is switched off by configuration or if the value of system property "net.time4j.utc.leapseconds.final" is true
      IllegalArgumentException - if the new event is not after the last stored event or if the date is invalid
      See Also:
      isExtensible(), isEnabled(), SUPPRESS_UTC_LEAPSECONDS, FINAL_UTC_LEAPSECONDS

    • supportsNegativeLS

      public boolean supportsNegativeLS()

      Queries if negative leap seconds are supported.

      Returns:
      true if negative leap seconds are supported else false
      See Also:
      LeapSecondProvider.supportsNegativeLS()

    • iterator

      public Iterator<LeapSecondEvent> iterator()

      Iterates over all leap second events in descending temporal order.

      Specified by:
      iterator in interface Iterable<LeapSecondEvent>
      Returns:
      Iterator over all stored leap second events which enables for-each-support

    • stream

      public Stream<LeapSecondEvent> stream()

      Creates a stream over all leap second events in descending temporal order.

      Returns:
      Stream over all stored leap second events in descending order
      Since:
      4.24

    • getShift

      public int getShift​(GregorianDate date)

      Yields the shift in seconds suitable for the last minute of given calendar date.

      The result of this method can be added to the second value 59 in order to calculate the maximum of the element SECOND_OF_MINUTE in given time context. The behaviour of the method is undefined if given calendar date is undefined.

      Parameters:
      date - day of possible leap second event in the last minute
      Returns:
      shift of second element (most of the times just 0)

    • getShift

      public int getShift​(long utc)

      Yields the shift in seconds dependent on if given UTC time point represents a leap second or not.

      Parameters:
      utc - elapsed SI-seconds relative to UTC epoch [1972-01-01T00:00:00Z] including leap seconds
      Returns:
      1, 0, -1 if the argument denotes a positive leap second, no leap second or a negative leap second

    • getNextEvent

      public LeapSecondEvent getNextEvent​(long utc)

      Yields the next leap second event after given UTC time point.

      Parameters:
      utc - elapsed SI-seconds relative to UTC epoch [1972-01-01T00:00:00Z] including leap seconds
      Returns:
      following leap second event or null if not known
      Since:
      2.1

    • enhance

      public long enhance​(long unixTime)

      Enhances an UNIX-timestamp with leap seconds and converts it to an UTC-timestamp.

      Note: A leap second itself cannot be restored because the mapping between UNIX- and UTC-time is not bijective. Hence the result of this method can not represent a leap second.

      Parameters:
      unixTime - elapsed time in seconds relative to UNIX epoch [1970-01-01T00:00:00Z] without leap seconds
      Returns:
      elapsed SI-seconds relative to UTC epoch [1972-01-01T00:00:00Z] including leap seconds
      See Also:
      strip(long)

    • strip

      public long strip​(long utc)

      Converts given UTC-timestamp to an UNIX-timestamp without leap seconds.

      This method is the reversal of enhance(). Note that there is no bijective mapping, that is sometimes the expression enhance(strip(val)) != val is true.

      Parameters:
      utc - elapsed SI-seconds relative to UTC epoch [1972-01-01T00:00:00Z] including leap seconds
      Returns:
      elapsed time in seconds relative to UNIX epoch [1970-01-01T00:00:00Z] without leap seconds
      See Also:
      enhance(long)

    • isPositiveLS

      public boolean isPositiveLS​(long utc)

      Queries if given UTC-timestamp represents a registered positive leap second.

      Parameters:
      utc - elapsed SI-seconds relative to UTC epoch [1972-01-01T00:00:00Z] including leap seconds
      Returns:
      true if the argument represents a registered positive leap second else false

    • getDateOfExpiration

      public GregorianDate getDateOfExpiration()

      Determines the expiration date of underlying data.

      Returns:
      immutable date of expiration
      Throws:
      IllegalStateException - if leap seconds are not activated
      Since:
      2.3

    • compare

      public int compare​(LeapSecondEvent o1, LeapSecondEvent o2)

      Compares two leap second events by their date in ascending order.

      Specified by:
      compare in interface Comparator<LeapSecondEvent>
      Parameters:
      o1 - first leap second event
      o2 - second leap second event
      Returns:
      -1, 0 or 1 if first event is before, equal to or later than second event
      Since:
      2.3

    • toString

      public String toString()

      For debugging purposes.

      Overrides:
      toString in class Object
      Returns:
      table of leap seconds as String