[LEAPSECS] Java: ThreeTen/JSR-310

[Stephen Colebourne]

On 28 January 2011 22:09, Keith Winstein <keithw at mit.edu> wrote:

> Aside from others' concerns, I am a little worried about the nonfunctional

> nature of your API. The user might appreciate documentation about which

> expressions may vary across calls to registerSystemLeapSecond(), and which

> member functions are well-defined functions of the object and arguments

> only. (And maybe some example test cases about the correct answer.)

>

> For example, if you make Instant a = ofEpochSeconds( 1325375990 ) and

> Instant b = ofEpochSeconds( 1325375991 ), and then take long d = between( a,

> b ).toMillisLong(), what do you get?

>

> It seems to me if I read your documentation correctly, that right now you

> would get d = 1000. Then in a few months the IERS emails everybody to add in

> a leap second, somebody calls registerSystemLeapSecond(), and suddenly the

> *same code* will yield a different result -- d = 1001.


Then I need to clarify the documentation.

Instant and Duration store internally long seconds and int
nano-of-day. Each day is 86400 seconds.
Creating two instances of Instant and then querying the duration
between will always work on 86400 second days and be unaffected by
registerLeapSecond().

Doing the same operation with two instances of UTCInstant will yield
the effect you describe above (although you have to use the
durationUntil() method).


> Do I understand correctly? If so, I think you are being a little glib to

> tell the user that duration calculations with Instant "ignore leap seconds."

> To the contrary: by using UTC-SLS, you are acknowledging the existence of

> leap seconds, and you are making user-visible changes in response to new

> information received about them, and your date-and-time routines are no

> longer functions of the inputs -- they have side effects based on ancillary

> calls to registerSystemLeapSecond(). I don't see how you are ignoring them

> at all.


Since UTCInstant is affected by registerLeapSecond(), conversions to
Instant are as well. As you say, this makes them slightly non
deterministic. Thats why the UTCInstant class is marked for advanced
users only!


> E.g., you say that "Instant uses the UTC-SLS time-scale which always has

> 86400 seconds in a day." But do you "always" have 86400000 milliseconds in

> the day?


Yes, Instant always has 86400000 millis per day.


> Another question I couldn't figure out from the documentation is whether

> ofEpochMillis(x).toEpochMillisLong() is supposed to be an identity. It seems

> like it might not be -- if a call to registerSystemLeapSecond() happens in

> between, then this could yield a different output than what was put in. Code

> could easily make this assumption so if it's rarely not true, you should

> warn the user.


As above. On Instant, it is an identity.


> Another question is whether your notion of UTC-SLS EpochMillis will be

> compatible with the operating system's POSIX epoch time_t (which often just

> pauses on a leap second). I'm guessing it probably won't be, and users may

> get in trouble here too without warning. E.g., the Python time.time()

> function will give different results than your new definition of "epoch"

> time.


It is up to implemetors to provide a suitable mapping to the OS. I'm
just providing the best tools I can.


> Also it's not clear to me how you plan to distribute these historical leap

> seconds. There is no historical leap second table in the GPS navigation

> message that I am aware of, and no way to get one within the POSIX API

> either. So it is a little tricky...


The zoneinfo databse has the history.


> I raised these same issues when the Haskell people came on here five years

> ago so I am not trying to pick on Java. :-) But I do think the issues are

> probably subtle, and since UTC-SLS has never been implemented in any

> widespread software, we do not really know what the issues are very well.

> Being the very first implementation of UTC-SLS anywhere may put you on the

> untested bleeding edge -- whether that's appropriate for this API is up to

> you I guess.


There are good test cases of the UTC-SLS, but a code review is always welcome.

Stephen