[LEAPSECS] Java JSR-310 TAIInstant class

[Stephen Colebourne]

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

Stephen