Class UtcInstant

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<UtcInstant>

    public final class UtcInstant
    extends java.lang.Object
    implements java.lang.Comparable<UtcInstant>, java.io.Serializable
    An instantaneous point on the time-line measured in the UTC time-scale with leap seconds.

    The java.time classes use the Java time-scale for simplicity. That scale works on the assumption that the time-line is simple, there are no leap-seconds and there are always 24 * 60 * 60 seconds in a day. Unfortunately, the Earth's rotation is not straightforward, and a solar day does not match this definition.

    This class is an alternative representation based on the UTC time-scale which includes leap-seconds. Leap-seconds are additional seconds that are inserted into the year-month-day-hour-minute-second time-line in order to keep UTC in line with the solar day. When a leap second occurs, an accurate clock will show the time 23:59:60 just before midnight.

    Leap-seconds are announced in advance, typically at least six months. The UtcRules class models which dates have leap-seconds. All the methods on this class use the latest available system rules.

    The system leap-second rules fix the start point of UTC as 1972. This date was chosen as UTC was more complex before 1972.

    The duration between two points on the UTC time-scale is calculated solely using this class. Do not use the between method on Duration as that will lose information. Instead use durationUntil(UtcInstant) on this class.

    It is intended that most applications will use the Instant class which uses the UTC-SLS mapping from UTC to guarantee 86400 seconds per day. Specialist applications with access to an accurate time-source may find this class useful.

    Time-scale

    The length of the solar day is the standard way that humans measure time. As the Earth's rotation changes, the length of the day varies. In general, a solar day is slightly longer than 86400 SI seconds. The actual length is not predictable and can only be determined by measurement. The UT1 time-scale captures these measurements.

    The UTC time-scale is a standard approach to bundle up all the additional fractions of a second from UT1 into whole seconds, known as leap-seconds. A leap-second may be added or removed depending on the Earth's rotational changes. If it is removed, then the relevant date will have no time of 23:59:59. If it is added, then the relevant date will have an extra second of 23:59:60.

    The modern UTC time-scale was introduced in 1972, introducing the concept of whole leap-seconds. Between 1958 and 1972, the definition of UTC was complex, with minor sub-second leaps and alterations to the length of the notional second.

    This class may be used for instants in the far past and far future. Since some instants will be prior to 1972, it is not strictly an implementation of UTC. Instead, it is a proleptic time-scale based on TAI and equivalent to it since 1972.

    Implementation Requirements:

    This class is immutable and thread-safe.

    This class must be treated as a value type. Do not synchronize, rely on the identity hash code or use the distinction between equals() and ==.

    See Also:
    Serialized Form
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(UtcInstant otherInstant)
      Compares this instant to another based on the time-line.
      java.time.Duration durationUntil​(UtcInstant utcInstant)
      Returns the duration between this instant and the specified instant.
      boolean equals​(java.lang.Object otherInstant)
      Checks if this instant is equal to the specified UtcInstant.
      long getModifiedJulianDay()
      Gets the Modified Julian Day (MJD).
      long getNanoOfDay()
      Gets the number of nanoseconds, later along the time-line, from the start of the Modified Julian Day.
      int hashCode()
      Returns a hash code for this instant.
      boolean isLeapSecond()
      Checks if the instant is within a leap second.
      UtcInstant minus​(java.time.Duration duration)
      Returns a copy of this instant with the specified duration subtracted.
      static UtcInstant of​(java.time.Instant instant)
      Obtains an instance of UtcInstant from an Instant.
      static UtcInstant of​(TaiInstant instant)
      Obtains an instance of UtcInstant from a TaiInstant.
      static UtcInstant ofModifiedJulianDay​(long mjDay, long nanoOfDay)
      Obtains an instance of UtcInstant from a Modified Julian Day with a nanosecond fraction of day.
      static UtcInstant parse​(java.lang.CharSequence text)
      Obtains an instance of UtcInstant from a text string 2007-12-03T10:15:30.00Z.
      UtcInstant plus​(java.time.Duration duration)
      Returns a copy of this instant with the specified duration added.
      java.time.Instant toInstant()
      Converts this instant to an Instant.
      java.lang.String toString()
      A string representation of this instant.
      TaiInstant toTaiInstant()
      Converts this instant to a TaiInstant.
      UtcInstant withModifiedJulianDay​(long mjDay)
      Returns a copy of this UtcInstant with the Modified Julian Day (MJD) altered.
      UtcInstant withNanoOfDay​(long nanoOfDay)
      Returns a copy of this UtcInstant with the nano-of-day altered.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Method Detail

      • ofModifiedJulianDay

        public static UtcInstant ofModifiedJulianDay​(long mjDay,
                                                     long nanoOfDay)
        Obtains an instance of UtcInstant from a Modified Julian Day with a nanosecond fraction of day.

        Modified Julian Day is a simple incrementing count of days where day 0 is 1858-11-17. Nanosecond-of-day is a simple count of nanoseconds from the start of the day including any additional leap-second. This method validates the nanosecond-of-day value against the Modified Julian Day.

        The nanosecond-of-day value has a valid range from 0 to 86,400,000,000,000 - 1 on most days, and a larger or smaller range on leap-second days.

        The nanosecond value must be positive even for negative values of Modified Julian Day. One nanosecond before Modified Julian Day zero will be -1 days and the maximum nanosecond value.

        Parameters:
        mjDay - the date as a Modified Julian Day (number of days from the epoch of 1858-11-17)
        nanoOfDay - the nanoseconds within the day, including leap seconds
        Returns:
        the UTC instant, not null
        Throws:
        java.lang.IllegalArgumentException - if nanoOfDay is out of range
      • of

        public static UtcInstant of​(java.time.Instant instant)
        Obtains an instance of UtcInstant from an Instant.

        Converting a UTC-SLS instant to UTC requires leap second rules. This method uses the latest available system rules.

        Conversion from an Instant will not be completely accurate near a leap second in accordance with UTC-SLS.

        Parameters:
        instant - the instant to convert, not null
        Returns:
        the UTC instant, not null
        Throws:
        java.time.DateTimeException - if the range of UtcInstant is exceeded
        java.lang.ArithmeticException - if numeric overflow occurs
      • of

        public static UtcInstant of​(TaiInstant instant)
        Obtains an instance of UtcInstant from a TaiInstant.

        Converting a TAI instant to UTC requires leap second rules. This method uses the latest available system rules.

        The UtcInstant will represent exactly the same point on the time-line as per the available leap-second rules. If the leap-second rules change then conversion back to TAI may result in a different instant.

        Parameters:
        instant - the instant to convert, not null
        Returns:
        the UTC instant, not null
        Throws:
        java.time.DateTimeException - if the range of UtcInstant is exceeded
        java.lang.ArithmeticException - if numeric overflow occurs
      • parse

        public static UtcInstant parse​(java.lang.CharSequence text)
        Obtains an instance of UtcInstant from a text string 2007-12-03T10:15:30.00Z.

        The string must represent a valid instant in UTC and is parsed using DateTimeFormatter.ISO_INSTANT with leap seconds handled.

        Parameters:
        text - the text to parse such as "12345.123456789s(TAI)", not null
        Returns:
        the parsed instant, not null
        Throws:
        java.time.format.DateTimeParseException - if the text cannot be parsed
        java.time.DateTimeException - if parsed text represents an invalid leap second
      • getModifiedJulianDay

        public long getModifiedJulianDay()
        Gets the Modified Julian Day (MJD).

        The Modified Julian Day is a simple incrementing count of days where day 0 is 1858-11-17. The nanosecond part of the day is returned by getNanosOfDay. The day varies in length, being one second longer on a leap day.

        Returns:
        the Modified Julian Day based on the epoch 1858-11-17
      • withModifiedJulianDay

        public UtcInstant withModifiedJulianDay​(long mjDay)
        Returns a copy of this UtcInstant with the Modified Julian Day (MJD) altered.

        The Modified Julian Day is a simple incrementing count of days where day 0 is 1858-11-17. The nanosecond part of the day is returned by getNanosOfDay. The day varies in length, being one second longer on a leap day.

        This instance is immutable and unaffected by this method call.

        Parameters:
        mjDay - the date as a Modified Julian Day (number of days from the epoch of 1858-11-17)
        Returns:
        a UtcInstant based on this instant with the requested day, not null
        Throws:
        java.time.DateTimeException - if nanoOfDay becomes invalid
      • getNanoOfDay

        public long getNanoOfDay()
        Gets the number of nanoseconds, later along the time-line, from the start of the Modified Julian Day.

        The nanosecond-of-day value measures the total number of nanoseconds within the day from the start of the day returned by getModifiedJulianDay. This value will include any additional leap seconds.

        Returns:
        the nanoseconds within the day, including leap seconds
      • withNanoOfDay

        public UtcInstant withNanoOfDay​(long nanoOfDay)
        Returns a copy of this UtcInstant with the nano-of-day altered.

        The nanosecond-of-day value measures the total number of nanoseconds within the day from the start of the day returned by getModifiedJulianDay. This value will include any additional leap seconds.

        This instance is immutable and unaffected by this method call.

        Parameters:
        nanoOfDay - the nanoseconds within the day, including leap seconds
        Returns:
        a UtcInstant based on this instant with the requested nano-of-day, not null
        Throws:
        java.time.DateTimeException - if the nanoOfDay value is invalid
      • isLeapSecond

        public boolean isLeapSecond()
        Checks if the instant is within a leap second.

        This method returns true when an accurate clock would return a seconds field of 60.

        Returns:
        true if this instant is within a leap second
      • plus

        public UtcInstant plus​(java.time.Duration duration)
        Returns a copy of this instant with the specified duration added.

        The duration is added using simple addition of the seconds and nanoseconds in the duration to the seconds and nanoseconds of this instant. As a result, the duration is treated as being measured in TAI compatible seconds for the purpose of this method.

        This instance is immutable and unaffected by this method call.

        Parameters:
        duration - the duration to add, not null
        Returns:
        a UtcInstant with the duration added, not null
        Throws:
        java.lang.ArithmeticException - if the calculation exceeds the supported range
      • minus

        public UtcInstant minus​(java.time.Duration duration)
        Returns a copy of this instant with the specified duration subtracted.

        The duration is subtracted using simple subtraction of the seconds and nanoseconds in the duration from the seconds and nanoseconds of this instant. As a result, the duration is treated as being measured in TAI compatible seconds for the purpose of this method.

        This instance is immutable and unaffected by this method call.

        Parameters:
        duration - the duration to subtract, not null
        Returns:
        a UtcInstant with the duration subtracted, not null
        Throws:
        java.lang.ArithmeticException - if the calculation exceeds the supported range
      • durationUntil

        public java.time.Duration durationUntil​(UtcInstant utcInstant)
        Returns the duration between this instant and the specified instant.

        This calculates the duration between this instant and another based on the UTC time-scale. Any leap seconds that occur will be included in the duration. Adding the duration to this instant using plus(java.time.Duration) will always result in an instant equal to the specified instant.

        Parameters:
        utcInstant - the instant to calculate the duration until, not null
        Returns:
        the duration until the specified instant, may be negative, not null
        Throws:
        java.lang.ArithmeticException - if the calculation exceeds the supported range
      • toInstant

        public java.time.Instant toInstant()
        Converts this instant to an Instant.

        Converting a UTC instant to UTC-SLS requires leap second rules. This method uses the latest available system rules.

        Conversion to an Instant will not be completely accurate near a leap second in accordance with UTC-SLS.

        Returns:
        an Instant representing the best approximation of this instant, not null
        Throws:
        java.time.DateTimeException - if the range of Instant is exceeded
        java.lang.ArithmeticException - if numeric overflow occurs
      • toTaiInstant

        public TaiInstant toTaiInstant()
        Converts this instant to a TaiInstant.

        Converting a UTC instant to TAI requires leap second rules. This method uses the latest available system rules.

        The TaiInstant will represent exactly the same point on the time-line as per the available leap-second rules. If the leap-second rules change then conversion back to UTC may result in a different instant.

        Returns:
        a TaiInstant representing the same instant, not null
        Throws:
        java.time.DateTimeException - if the range of TaiInstant is exceeded
        java.lang.ArithmeticException - if numeric overflow occurs
      • compareTo

        public int compareTo​(UtcInstant otherInstant)
        Compares this instant to another based on the time-line.

        The comparison is based first on the Modified Julian Day, then on the nano-of-day. It is "consistent with equals", as defined by Comparable.

        Specified by:
        compareTo in interface java.lang.Comparable<UtcInstant>
        Parameters:
        otherInstant - the other instant to compare to, not null
        Returns:
        the comparator value, negative if less, positive if greater
      • equals

        public boolean equals​(java.lang.Object otherInstant)
        Checks if this instant is equal to the specified UtcInstant.

        The comparison is based on the Modified Julian Day, then on the nano-of-day.

        Overrides:
        equals in class java.lang.Object
        Parameters:
        otherInstant - the other instant, null returns false
        Returns:
        true if the other instant is equal to this one
      • hashCode

        public int hashCode()
        Returns a hash code for this instant.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a suitable hash code
      • toString

        public java.lang.String toString()
        A string representation of this instant.

        The string is formatted using ISO-8601. The output includes seconds, 9 nanosecond digits and a trailing 'Z'. The time-of-day will be 23:59:60 during a positive leap second.

        Overrides:
        toString in class java.lang.Object
        Returns:
        a representation of this instant, not null