Package javax.time

Class UTCInstant

java.lang.Object
javax.time.UTCInstant
All Implemented Interfaces:
Serializable, Comparable<UTCInstant>

public final class UTCInstant extends Object implements Comparable<UTCInstant>, Serializable
An instantaneous point on the time-line measured in the UTC time-scale, handling leap seconds.

Most of the Time Framework for Java 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. However, 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. Alternative implementations of the rules may be supplied.

The default rules implementation fixes 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 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 seconds. The default rules only implement UTC from 1972. Prior to that date, the default rules fix the UTC-TAI offset at 10 seconds. While not historically accurate, it is a simple, easy definition, suitable for this library.

The standard Java epoch of 1970-01-01 is prior to the introduction of whole leap-seconds into UTC in 1972. As such, the Time Framework for Java needs to define what the 1970 epoch actually means. The chosen definition follows the UTC definition given above, such that 1970-01-01 is 10 seconds offset from TAI.

UTCInstant is immutable and thread-safe.

See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final long
    The Modified Julian Day, from the epoch of 1858-11-17.
    private final long
    The number of nanoseconds, later along the time-line, from the MJD field.
    private static final long
    Constant for nanos per second.
    private final UTCRules
    The leap second rules.
    private static final long
    Constant for seconds per day.
    private static final long
    Serialization version id.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    UTCInstant(long myDay, long nanoOfDay, UTCRules rules)
    Constructs an instance.
  • Method Summary

    Modifier and Type
    Method
    Description
    int
    compareTo(UTCInstant otherInstant)
    Compares this instant to another based on the time-line, then the name of the rules.
    Returns the duration between this instant and the specified instant.
    boolean
    equals(Object otherInstant)
    Checks if this instant is equal to the specified UTCInstant.
    long
    Gets the Modified Julian Day (MJD).
    long
    Gets the number of nanoseconds, later along the time-line, from the start of the Modified Julian Day.
    Gets the leap second rules defining when leap seconds occur.
    int
    Returns a hash code for this instant.
    boolean
    Checks if the instant is within a leap second.
    minus(Duration duration)
    Returns a copy of this instant with the specified duration subtracted.
    static UTCInstant
    of(Instant instant)
    Obtains an instance of UTCInstant from a provider of instants using the system default leap second rules.
    static UTCInstant
    of(Instant instant, UTCRules rules)
    Obtains an instance of UTCInstant from a provider of instants using the specified leap second rules.
    static UTCInstant
    of(TAIInstant taiInstant)
    Obtains an instance of UTCInstant from a TAI instant using the system default leap second rules.
    static UTCInstant
    of(TAIInstant taiInstant, UTCRules rules)
    Obtains an instance of UTCInstant from a TAI instant using the specified leap second rules.
    static UTCInstant
    ofModifiedJulianDays(long mjDay, long nanoOfDay)
    Obtains an instance of UTCInstant from a Modified Julian Day with a nanosecond fraction of second using the system default leap second rules.
    static UTCInstant
    ofModifiedJulianDays(long mjDay, long nanoOfDay, UTCRules rules)
    Obtains an instance of UTCInstant from a Modified Julian Day with a nanosecond fraction of second using the specified leap second rules.
    plus(Duration duration)
    Returns a copy of this instant with the specified duration added.
    Converts this instant to an Instant using the system default leap second rules.
    A string representation of this instant.
    Converts this instant to a TAIInstant using the stored leap second rules.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • SECS_PER_DAY

      private static final long SECS_PER_DAY
      Constant for seconds per day.
      See Also:
    • NANOS_PER_SECOND

      private static final long NANOS_PER_SECOND
      Constant for nanos per second.
      See Also:
    • serialVersionUID

      private static final long serialVersionUID
      Serialization version id.
      See Also:
    • mjDay

      private final long mjDay
      The Modified Julian Day, from the epoch of 1858-11-17.
    • nanos

      private final long nanos
      The number of nanoseconds, later along the time-line, from the MJD field. This is always positive and includes leap seconds.
    • rules

      private final UTCRules rules
      The leap second rules.
  • Constructor Details

    • UTCInstant

      private UTCInstant(long myDay, long nanoOfDay, UTCRules rules)
      Constructs an instance.
      Parameters:
      nanoOfDay - the nanoseconds within the day, including leap seconds
      rules - the leap second rules, not null
      mjDay - the date as a Modified Julian Day (number of days from the epoch of 1858-11-17)
  • Method Details

    • ofModifiedJulianDays

      public static UTCInstant ofModifiedJulianDays(long mjDay, long nanoOfDay)
      Obtains an instance of UTCInstant from a Modified Julian Day with a nanosecond fraction of second using the system default leap second rules.

      This factory creates an instance of a UTC instant. The nanosecond of day value includes any leap second and has a valid range from 0 to 86,400,000,000,000 - 1 on days other than leap-second-days and other lengths on leap-second-days.

      The nanosecond value must be positive even for negative values of Modified Julian Days. 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, never null
      Throws:
      IllegalArgumentException - if nanoOfDay is out of range
    • ofModifiedJulianDays

      public static UTCInstant ofModifiedJulianDays(long mjDay, long nanoOfDay, UTCRules rules)
      Obtains an instance of UTCInstant from a Modified Julian Day with a nanosecond fraction of second using the specified leap second rules.

      This factory creates an instance of a UTC instant. The nanosecond of day value includes any leap second and has a valid range from 0 to 86,400,000,000,000 - 1 on days other than leap-second-days and other lengths on leap-second-days.

      The nanosecond value must be positive even for negative values of Modified Julian Days. 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, never null
      Throws:
      IllegalArgumentException - if nanoOfDay is out of range
    • of

      public static UTCInstant of(Instant instant)
      Obtains an instance of UTCInstant from a provider of instants using the system default leap second rules.

      This method converts from the UTC-SLS to the UTC time-scale using the system default leap-second rules. This conversion will lose information around a leap second in accordance with UTC-SLS. Converting back to an Instant may result in a slightly different instant.

      Parameters:
      instant - the instant to convert, not null
      Returns:
      the UTC instant, never null
    • of

      public static UTCInstant of(Instant instant, UTCRules rules)
      Obtains an instance of UTCInstant from a provider of instants using the specified leap second rules.

      This method converts from the UTC-SLS to the UTC time-scale using the specified leap-second rules. This conversion will lose information around a leap second in accordance with UTC-SLS. Converting back to an Instant may result in a slightly different instant.

      Parameters:
      instant - the instant to convert, not null
      rules - the leap second rules, not null
      Returns:
      the UTC instant, never null
    • of

      public static UTCInstant of(TAIInstant taiInstant)
      Obtains an instance of UTCInstant from a TAI instant using the system default leap second rules.

      This method converts from the TAI to the UTC time-scale using the system default leap-second rules. This conversion does not lose information and the UTC instant may safely be converted back to a TAIInstant.

      Parameters:
      taiInstant - the TAI instant to convert, not null
      Returns:
      the UTC instant, never null
    • of

      public static UTCInstant of(TAIInstant taiInstant, UTCRules rules)
      Obtains an instance of UTCInstant from a TAI instant using the specified leap second rules.

      This method converts from the TAI to the UTC time-scale using the specified leap-second rules. This conversion does not lose information and the UTC instant may safely be converted back to a TAIInstant.

      Parameters:
      taiInstant - the TAI instant to convert, not null
      rules - the leap second rules, not null
      Returns:
      the UTC instant, never null
    • getRules

      public UTCRules getRules()
      Gets the leap second rules defining when leap seconds occur.
      Returns:
      the leap seconds rules
    • getModifiedJulianDays

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

      The Modified Julian Day count is a simple incrementing count of days where day 0 is 1858-11-17. The nanosecond part of the day is returned by getNanosOfDay.

      A Modified Julian Day varies in length, being one second longer on a leap day.

      Returns:
      the Modified Julian Day based on the epoch 1858-11-17
    • 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 from the Modified Julian Day returned by getModifiedJulianDay. This value will include any additional leap seconds.

      Returns:
      the nanoseconds within the day, including leap seconds
    • 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(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, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • minus

      public UTCInstant minus(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, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • durationUntil

      public 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(javax.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, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • toTAIInstant

      public TAIInstant toTAIInstant()
      Converts this instant to a TAIInstant using the stored leap second rules.

      This method converts from the UTC to the TAI time-scale using the stored leap-second rules. Conversion to a TAIInstant retains the same point on the time-line but loses the stored rules. If the TAI instant is converted back to a UTC instant with different or updated rules then the calculated UTC instant may be different.

      Returns:
      a TAIInstant representing the same instant, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • toInstant

      public Instant toInstant()
      Converts this instant to an Instant using the system default leap second rules.

      This method converts this instant from the UTC to the UTC-SLS time-scale using the stored leap-second rules. This conversion will lose information around a leap second in accordance with UTC-SLS. Converting back to a UTCInstant may result in a slightly different instant.

      Returns:
      an Instant representing the best approximation of this instant, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • compareTo

      public int compareTo(UTCInstant otherInstant)
      Compares this instant to another based on the time-line, then the name of the rules.

      The comparison is based on the positions on the time-line and the rules. This definition means that two instants representing the same instant on the time-line will differ if the rules differ. To compare the time-line instant, convert both instants to a TAIInstant.

      Specified by:
      compareTo in interface 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(Object otherInstant)
      Checks if this instant is equal to the specified UTCInstant.

      The comparison is based on the positions on the time-line and the rules. This definition means that two instants representing the same instant on the time-line will differ if the rules differ. To compare the time-line instant, convert both instants to a TAIInstant.

      Overrides:
      equals in class 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 Object
      Returns:
      a suitable hash code
    • toString

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

      The string is formatted using ISO-8601.

      Overrides:
      toString in class Object
      Returns:
      a representation of this instant, never null