feedback on JSR310

[hohwille]

JSR310 is really a great improvement compared to what we had before with Date and Calendar. However, the API of JSR310 has many pitfalls and is partially academic. I am leaving this feedback here in the hope that someone might care even though I assume that this will be closed without anybody caring and after Java8 is out my feedback is maybe too late anyways...

I make a simple example to make a story of it: all I want to do is having two exact points in time (both in UTC). Further I want to calculate the number of days between those points ignoring the time.

• Reading about the classes offered for that I first decide to use Instant to store the points in time.
• I then try to get the date without time from that by LocalDateTime.from(instant). However, I quickly notice that this will always fail for any instance of Instant. Why was the API designed in a way that something that can never work cause a runtime error instead of a compiler error? Why does it cause an error at all? As you can read on the web this is not intuitive and seems more like an academic decision than a helpful design for API users: http://stackoverflow.com/questions/23641846/java-se-8-temporalaccessor-from-issues-when-used-with-a-java-time-instant-object I might be mislead by the comments and am aware that implementing data/time/TZ/caldendar stuff is extremely complex and totally underestimated by most people but that is just my point of view so far after reading javadocs and the comments on that link.
• So let us maybe use OffsetDateTime instead of Instant then.
• Now we can extract the Date by LocalDate.from(offsetDateTime).
• So all we need to do is calculate the number of days between two LocalDate instances.
• Let us try Duration.between(startDate, endDate).get(ChronoUnit.DAYS) - bang yet another runtime exception for something that is an error detectable already at compile-time. Still I do not see why this can not work from an API perspective.
• So you search the web how to do it and find e.g. http://www.leveluplunch.com/java/examples/number-of-days-between-two-dates/ and so I tried Period.between(startDate, endDate).getDays() as suggested. No runtime error, returns an int. Seems to work but after some observation again totally mislead and wrong. E.g. Period.between(offsetDateTime.minusYears(1), offsetDateTime).getDays() returns zero. Bang. I mean seriously reading the javadoc of Period would reveal the mistake but if someone simply googles for a solution he will fail utterly.
• ChronoUnit.DAYS.between(startDate, endDate) will do the job.
• Actually my result will still be wrong and if Instant would actually be considered as UTC based it would have been correct.

So I do not want to say that you did bad work. If the API is used properly everything is fine. However, you created an expert API that has several pitfalls and is far from being used intuitively. Maybe such intuitive API would be impossible to create. However, a design that allows such clear types but runtime errors for things obvious at compile-time is really a big pitfall for every newbie.

[jodastephen]

These two APIs can calculate the difference between two Instant objects:

Duration.between(a, b).toDays()
ChronoUnit.DAYS.between(a, b)

The LocalDate.from(instant) issue is well known. The problem is that LocalDate needs a time-zone to extract data from an Instant and no time-zone is specified (it would be incorrect to choose either UTC or the system time-zone). The situation will be improved if this JDK issue is fixed.

The Duration.get(ChronoUnit.DAYS) issue is answered here. The method name "get" is simply wrong for what it is, which is a low-level method.

Thanks for the feedback.

[hohwille]

Thanks for clarification. The more people get used to java.time the better documentation on the web will get. Thanks for your time, mate.