I note that there has been some previous discussion about JSR-310 on this list. I thought I'd provide an update on the status wrt leap seconds (as spec lead) given Java is perhaps the most important enterprise programming language.
The relevant classes for leap seconds are in this package: http://threeten.sourceforge.net/apidocs/javax/time/package-summary.html Instant is the class that will typically be used, and has 86400 seconds in a day using the UTC-SLS definition. The Javadoc has the full explanation: http://threeten.sourceforge.net/apidocs/javax/time/Instant.html UTCInstant supports leap seconds based on a pluggable UTCRules class: http://threeten.sourceforge.net/apidocs/javax/time/UTCInstant.html TAIInstant represents the TAI scale: http://threeten.sourceforge.net/apidocs/javax/time/TAIInstant.html TimeSource allows an implementation to provide an accurate UTC/TAI clock if one is available: http://threeten.sourceforge.net/apidocs/javax/time/TimeSource.html Note that the UTC definition used states "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. " Given the acrimony on this list, I'm sure there will be opinions on these design decisions (which differ from those last discussed here AFAICT). I'm looking for (constructive) feedback of all kinds, remembering that my goal is practical usage, not scientific purity. Also bear in mind that wide-adoption of this in Java may (or at least should) influence the future direction of standards. Interestingly, I started the process of looking into the topic with a strong dislike of leap-seconds, and a desire to remove them. I ended it with the strong desire to retain them exactly as at present, but with UTC-SLS for most users and separate UTC support for those that need it. This balanced the needs of most developers and business users to not care about leap seconds, with the reality that they exist. For reference, here is the explanation I previously sent to the ThreeTen mailing list: " There are four key elements of date/time that vary: - month lengths - leap years - DST - leap seconds The API handles each of these, but in different ways. Month lengths and leap years can be managed by DateResolver. DST by ZonedDateTime and ZoneResolver. Leap seconds by UTCInstant and UTCRules. However, the general prinicple of the API is that users care about these four elements in decreasing order. And specifically, almost no-one cares about leap seconds. The impact of the last statement is that the API only permits the second-of-minute to be from 0 to 59 inclusive. 60 is never a valid value. This is in accordance with most users expectations and makes a large API actually usable. (Without this simplification, every single user would need to take account of leap seconds. Trying to hide them in special methods like plusLeapSecond doesn't help. As a receiver of an object you don't know what state the class has been left in. In our initial approach, I indicated that simple Javadoc was a key goal. If the Javadoc is compex, then its a sign of multiple classes.) So, this lead to the question of how a date/time class, like OffsetDateTime, maps to the real time-line. With this change, the mapping is defined as UTC-SLS. This has the advantage that time always progresses forwards, given an accurate clock. Thus, OffsetDateTime is not 'just' a label, it also has a well-defined physical point for all moments prior to the next leap-second. Instant is an alternative view of OffsetDateTime. The two are always convertible exactly, however an Instant is always in the equivalent of +00:00 offset. UTCInstant exposes leap seconds accurately. UTCRules are applied in all instant conversions, and you need to convert a TAIInstnat to an Instant before converting to OffsetDateTime. As you say, TAIInstant is the only true "machine time". However... For most users that don't care about the subtleties of sub-second accuracy around leap seconds and just want to ignore them, they want something that they /believe/ is a "machine time". This is currently thought of as System.currentTimeMillis(). Instant is the replacement for that concept. Its "machine time" for most users that need a it, typically for an event time-stamp of some kind. InstantProvider is simply an interface to access this definition of Instant. TAIInstant (the correct "machine time") is theoretically a better choice, but is difficult to obtain, and not easily processed by ther systems, such as DB and XML. So, we have it for those specialist users that need it, but it is a low-importance class. So, the whole purpose of the design is to construct a successful mirage for our users so they don't ever have to deal with leap-seconds. UTC-SLS provides a clear definition for those that want to deal with higher accuracy time-sources. TAIInstant and UTCInstant deal with those that want to keep everything truly correct. On durations, the current code copes nicely with the differences between the UTC, TAI and 86400 definitions. A duration can be obtained as the difference between two points on any of the three scales. But it is not linked to any scale. They are effective seconds not SI seconds. Those that care about the difference should use TAIInstant throughout, and they will get SI seconds. In summary, if we were being truly honest in the API, then TAIInstant would be called Instant, and UTCInstant and Instant would disappear into the other human focussed classes. But our users don't want the truth - at least not around leap seconds - they want something in line with their conceptual model of time. " Feedback welcome. Stephen Colebourne Project lead ThreeTen Co-spec lead JSR-310 https://sourceforge.net/apps/mediawiki/threeten/index.php?title=ThreeTen _______________________________________________ LEAPSECS mailing list [email protected] http://six.pairlist.net/mailman/listinfo/leapsecs
