[LEAPSECS] Java JSR-310 TAIInstant class

[Warner Losh]

On 01/29/2011 02:00, Stephen Colebourne wrote:

> This is the Javadoc of the TAIInstant class:

>

> Please use this thread to discuss flaws in the Javadoc.

>

>

>   * An instantaneous point on the time-line measured in the TAI time-scale.

>   *<p>

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

>   *<p>

>   * 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 {@code 1958-01-01T00:00:00(TAI)}.

>   *<p>

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


While this is true, there's little support at the OS level for importing 
GPS time into the system, even on systems that run with a GPS receiver.  
ntp can set system time/TAI offset, but very often this isn't done, 
especially on non-GPS-backed stratum1 server (eg, all non-stratum 1 
servers and most stratum1 servers that aren't GPS-backed).  ntp doesn't 
have a widely deployed way of doing this, although through autokey'd 
negotated sessions you can provide a leapsecond table.  But this leap 
second table isn't well integrated into things like the time zone file, 
so most people don't bother to set this up.

That's a long way of saying 'time is provided to most people as UTC 
time, and working backwards can pose many operational challenges.'  
Those challenges don't seem to be reflected in the above text.


>   *<p>

>   * The duration between two points on the TAI time-scale is calculated

> solely using this class.

>   * Do not use the {@code between} method on {@code Duration} as that

> will lose information.

>   * Instead use {@link #durationUntil(TAIInstant)} on this class.

>   *<p>

>   * It is intended that most applications will use the {@code 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.


Warner