Package javax.time

Class TAIInstant

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

public final class TAIInstant extends Object implements Comparable<TAIInstant>, Serializable
An instantaneous point on the time-line measured in the TAI time-scale.

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. Sadly, the real-life time-line is not this simple.

This class is an alternative representation based on the TAI time-scale. This scale is defined using atomic clocks and has proceeded in a continuous uninterrupted manner since its epoch of 1958-01-01T00:00:00(TAI).

As there are no leap seconds, or other discontinuities, in TAI, this time-scale would make an excellent timestamp. While there are, at the time of writing, few easy ways to obtain an accurate TAI instant, it is relatively easy to obtain a GPS instant. GPS and TAI differ by the fixed amount of 19 seconds.

The duration between two points on the TAI time-scale is calculated solely using this class. Do not use the between method on Duration as that will lose information. Instead use durationUntil(TAIInstant) 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.

TAIInstant is immutable and thread-safe.

See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final int
    The number of nanoseconds, later along the time-line, from the seconds field.
    private static final int
    Constant for nanos per second.
    private static final Pattern
    Parse regex.
    private final long
    The number of seconds from the epoch of 1958-01-01T00:00:00(TAI).
    private static final long
    Serialization version id.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    TAIInstant(long epochSeconds, int nanoOfSecond)
    Constructs an instance.
  • Method Summary

    Modifier and Type
    Method
    Description
    int
    compareTo(TAIInstant otherInstant)
    Compares this instant to another based on the time-line.
    Returns the duration between this instant and the specified instant.
    boolean
    equals(Object otherInstant)
    Checks if this instant is equal to the specified TAIInstant.
    int
    Gets the number of nanoseconds, later along the time-line, from the start of the second.
    long
    Gets the number of seconds from the TAI epoch of 1958-01-01T00:00:00(TAI).
    int
    Returns a hash code for this instant.
    minus(Duration duration)
    Returns a copy of this instant with the specified duration subtracted.
    static TAIInstant
    of(Instant instant)
    Obtains an instance of TAIInstant from an Instant using the system default leap second rules.
    static TAIInstant
    of(UTCInstant instant)
    Obtains an instance of TAIInstant from a UTCInstant.
    static TAIInstant
    ofTAISeconds(long taiSeconds, long nanoAdjustment)
    Obtains an instance of TAIInstant from the number of seconds from the TAI epoch of 1958-01-01T00:00:00(TAI) with a nanosecond fraction of second.
    static TAIInstant
    parse(String text)
    Obtains an instance of TAIInstant from a text string.
    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 UTCInstant using the system default leap second rules.

    Methods inherited from class java.lang.Object

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

    • NANOS_PER_SECOND

      private static final int NANOS_PER_SECOND
      Constant for nanos per second.
      See Also:
    • PARSER

      private static final Pattern PARSER
      Parse regex.
    • serialVersionUID

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

      private final long seconds
      The number of seconds from the epoch of 1958-01-01T00:00:00(TAI).
    • nanos

      private final int nanos
      The number of nanoseconds, later along the time-line, from the seconds field. This is always positive, and never exceeds 999,999,999.
  • Constructor Details

    • TAIInstant

      private TAIInstant(long epochSeconds, int nanoOfSecond)
      Constructs an instance.
      Parameters:
      epochSeconds - the number of seconds from the epoch
      nanoOfSecond - the nanoseconds within the second, from 0 to 999,999,999
  • Method Details

    • ofTAISeconds

      public static TAIInstant ofTAISeconds(long taiSeconds, long nanoAdjustment)
      Obtains an instance of TAIInstant from the number of seconds from the TAI epoch of 1958-01-01T00:00:00(TAI) with a nanosecond fraction of second.

      This method allows an arbitrary number of nanoseconds to be passed in. The factory will alter the values of the second and nanosecond in order to ensure that the stored nanosecond is in the range 0 to 999,999,999. For example, the following will result in the exactly the same instant:

        TAIInstant.ofSeconds(3, 1);
        TAIInstant.ofSeconds(4, -999999999);
        TAIInstant.ofSeconds(2, 1000000001);
       
      Parameters:
      taiSeconds - the number of seconds from the epoch of 1958-01-01T00:00:00(TAI)
      nanoAdjustment - the nanosecond adjustment to the number of seconds, positive or negative
      Returns:
      the TAI instant, never null
      Throws:
      IllegalArgumentException - if nanoOfSecond is out of range
    • of

      public static TAIInstant of(Instant instant)
      Obtains an instance of TAIInstant from an Instant using the system default leap second rules.

      Converting a UTC-SLS instant to a TAI instant requires leap second rules. This method uses the latest available system rules. The conversion first maps from UTC-SLS to UTC, then converts to TAI.

      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 TAI instant, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • of

      public static TAIInstant of(UTCInstant instant)
      Obtains an instance of TAIInstant from a UTCInstant.

      Converting a UTC instant to a TAI instant requires leap second rules. This method uses the rules held in within the UTC instant.

      Conversion from a UTCInstant will be entirely accurate. The resulting TAI instant will not reference the leap second rules, so converting back to a UTC instant may result in a different UTC instant.

      Parameters:
      instant - the instant to convert, not null
      Returns:
      the TAI instant, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • parse

      public static TAIInstant parse(String text)
      Obtains an instance of TAIInstant from a text string.

      The following format is accepted in ASCII:

      • {seconds}.{nanosOfSecond}s(TAI)
      The accepted format is strict. The seconds part must contain only numbers and a possible leading negative sign. The nanoseconds part must contain exactly nine digits. The trailing literal must be exactly specified. This format parses the toString format.
      Parameters:
      text - the text to parse such as '12345.123456789s(TAI)', not null
      Returns:
      the parsed instant, never null
      Throws:
      CalendricalException - if the text cannot be parsed
    • getTAISeconds

      public long getTAISeconds()
      Gets the number of seconds from the TAI epoch of 1958-01-01T00:00:00(TAI).

      The TAI second count is a simple incrementing count of seconds where second 0 is 1958-01-01T00:00:00(TAI). The nanosecond part of the day is returned by getNanosOfSecond.

      Returns:
      the seconds from the epoch of 1958-01-01T00:00:00(TAI)
    • getNanoOfSecond

      public int getNanoOfSecond()
      Gets the number of nanoseconds, later along the time-line, from the start of the second.

      The nanosecond-of-second value measures the total number of nanoseconds from the second returned by getTAISeconds.

      Returns:
      the nanoseconds within the second, from 0 to 999,999,999
    • plus

      public TAIInstant 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 TAIInstant based on this instant with the duration added, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • minus

      public TAIInstant 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 TAIInstant based on this instant with the duration subtracted, never null
      Throws:
      ArithmeticException - if the calculation exceeds the supported range
    • durationUntil

      public Duration durationUntil(TAIInstant taiInstant)
      Returns the duration between this instant and the specified instant.

      This calculates the duration between this instant and another based on the TAI time-scale. Adding the duration to this instant using plus(javax.time.Duration) will always result in an instant equal to the specified instant.

      Parameters:
      taiInstant - 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
    • toUTCInstant

      public UTCInstant toUTCInstant()
      Converts this instant to a UTCInstant using the system default leap second rules.

      This method converts this instant 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.

      Returns:
      a UTCInstant representing the same instant using the system leap second rules, never null
    • toInstant

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

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

      Returns:
      an Instant representing the best approximation of this instant, never null
    • compareTo

      public int compareTo(TAIInstant otherInstant)
      Compares this instant to another based on the time-line.
      Specified by:
      compareTo in interface Comparable<TAIInstant>
      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 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 as {seconds).(nanosOfSecond}s(TAI). At least one second digit will be present. The nanoseconds will always be nine digits.

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