Early_Draft_Review modified by Stephen Colebourne

Stephen Colebourne — Thu, 22 May 2014 22:08:10 -0000

--- v2
+++ v3
@@ -9,7 +9,7 @@
   * [User guide](User_Guide) - more detailed introduction 
   * [Reference implementation source/binary download](https://sourceforge.net/projects/threeten/files/) \- alpha reference implementation 
   * [Signup to the mailing list](https://sourceforge.net/mail/?group_id=386712) \- the develop mailing list is the main one 
-  * [Home](ThreeTen) - the home page of ThreeTen/JSR-310 
+  * [Home](Old_home_page) - the home page of ThreeTen/JSR-310

 **All** members of the Java community are encouraged to review the specification and post comments here or the dev mailing list.

Early_Draft_Review modified by Stephen Colebourne

Stephen Colebourne — Thu, 22 May 2014 22:08:10 -0000

--- v1
+++ v2
@@ -4,7 +4,7 @@

 The JSR-310 API entered early draft review (a formal JCP stage) on 2010-02-26. The purpose of this stage was to get FEEDBACK! 

-  * [Specification](http://docs.google.com/View?id=dfn5297z_8d27fnf) \- very lightweight 
+  * [Specification](https://docs.google.com/document/d/1rd8yplQZIRz3LxMzpVLuskr1b0HwBmK9PXpdgBYojSw/pub) \- very lightweight 
   * [Javadoc](http://threeten.sourceforge.net/apidocs/) \- the main part of the specification 
   * [User guide](User_Guide) - more detailed introduction 
   * [Reference implementation source/binary download](https://sourceforge.net/projects/threeten/files/) \- alpha reference implementation

Early_Draft_Review modified by Stephen Colebourne

Stephen Colebourne — Thu, 22 May 2014 22:08:10 -0000

This document was converted from the java.net wiki and is retained for historical reasons.

The JSR-310 API entered early draft review (a formal JCP stage) on 2010-02-26. The purpose of this stage was to get FEEDBACK!

Specification - very lightweight
Javadoc - the main part of the specification
User guide - more detailed introduction
Reference implementation source/binary download - alpha reference implementation
Signup to the mailing list - the develop mailing list is the main one
Home - the home page of ThreeTen/JSR-310

All members of the Java community are encouraged to review the specification and post comments here or the dev mailing list.

Please note that the API is not "finished". Work is still ongoing, so all feedback is extremely useful. Specifically, we need to know if

the overall shape and size of the API is too large, too small or about right
whether there are key use cases that are missing (or you can't find)
specific method names are too long, too short or unclear
the specification is clear, unclear or about right
what would you change?
anything else that is an issue

Remember - Java SE already has two poor quality date/time APIs. We need to ensure that the third one works well!

Please separate each comment with comment with a horizontal line (three or more dashes) Additions may be made using your signature, or anonymously.

I found the method I was looking for, DayOfWeek.firstDayOfWeekFor(Locale), so that's all good! However, I thought that the week-of-year number also changed based on the same logic (at least the existing Calendar class have options for this), but I only find ISOChronology.weekOfWeekBasedYearRule(), not taking Locale. Sorry if my understanding is not correct, or if this is covered other places in the API.

The HistoricChronology and CopticChronology seems to have identical rules - is this correct, and if so, one of them seems redundant?

The GregorianCalendar from existing date/time API models the 1582 Julian cutover, which is a nice feature to have by default without additional coding.
-- stolsvik - 2010-03-03

Spec Lead Reply:
I agree that the locale specific code for day of week and week of year still needs work. The underlying part for week of year exists - use WeekOfWeekBasedYear to follow ISO rules, or WeekOfYear to follow week starts on 1st Jan rules.

HistoricChronology isn't fully implemented yet. It is different to Coptic. There is a factory method on HistoricDate that defaults to the 1582 date.
-- Main.scolebourne - 2010-03-03

Stolsvik:
Regarding WeekOfWeekYear: I don't really know how this works (I'm a user!), but the two cases you mention does not seem to be the same as current API? The current API states (by default) that week 1 is the first week having 4 days within the year (?), and that again follows the logic of firstDayOfWeek(Locale)? (Therefore, Americans and Norwegians would then rather often have different views on what constitute week 1?)
-- Main.stolsvik - 2010-03-04

Spec Lead Reply:
My point was that you can work around the problem at the moment. Compare the two methods https://jsr-310.dev.java.net/nonav/doc-2010-02-09/javax/time/calendar/ISOChronology.html#weekOfYearRule%28%29 and https://jsr-310.dev.java.net/nonav/doc-2010-02-09/javax/time/calendar/ISOChronology.html#weekOfWeekBasedYearRule%28%29
-- Main.scolebourne - 2010-03-05

Stolsvik:
I still don't get it. WeekOfYearRule creates "artificial" weeks that don't resembles much in the real world: It is not typical to use e.g. a week going from Thursday to Wednesday, which could easily be the case with the weekOfYearRule: "This field counts weeks in groups of seven days starting from the first of January. The 1st to the 7th of January is always week 1 while the 8th to the 14th is always week 2". OTOH, weekOfWeekBasedYearRule states "This field counts weeks using the ISO-8601 algorithm. The first week of the year is the week which has at least 4 days in the year using a Monday to Sunday week definition." - while the issue I'm trying to make is what if one instead have a "Sunday to Saturday week definition": In this case, "the first week of the year which has at least 4 days in the year" would not necessarily be the same as if the week starts on Monday?
-- Main.stolsvik - 2010-03-07

Spec Lead Reply:
There may yet be a need that we've missed here. Thank you.
-- Main.scolebourne - 2010-03-09

The main use-case that doesn't appear to be filled by the current API is getting the Period between two dates/times/etc. Eg. Period.between(DateProvider from, DateProvider to)

-- Main.benlings - 2010-03-03

Spec Lead Reply:
I agree that this use case should probably be supported.
-- Main.scolebourne - 2010-03-04

so when do we see this api in java se?

Spec Lead Reply:
The inclusion or otherwise of any JSR is supposed to be under the control of the Java SE 7 JSR. Unfortunately, there is currently no such JSR, so at present the decision lies solely with Oracle (Sun).
-- Main.scolebourne - 2010-03-05

Comparing to the old date and time api in jdk, this one is a pretty great improvement which eases a lot of pain in development. Thanks for your effort.
However, I found the enum QuarterOfYear uses Q1/Q2... as the values rather than spring/summer...IMHO, spring/summer... would be better for abstracting season and easier to understand.
Do I miss something?

-- Ming Jin - 2010-03-07

Spec Lead Reply:
The concept of a quarter is very different to that of a season. The terms Q1 to Q4 are standard terminology agreed internationally in business and in the CLDR data.
-- Main.scolebourne - 2010-03-00

Unless I'm missing something priting dates is rather verbose in 310 when compared to Joda Time: Joda Time: LocalDate date = ... String dateString = date.toString("dd/mm/yyyy");

JSR 310: LocalDate date = ... DateTimeFormatter formatter = new DateTimeFormatterBuilder().appendPattern("dd/mm/yyyy").toFormatter() String dateString = formatter.print(date);

Any reason not to add the toString method in?

Also I think you may need easier ways of converting between the current Date, Calendar, SQL Date/Time/Timestamp and XML Duration/XMLGregorianCalendar APIs and 310 unless these various APIs are going to be updated to work with 310?

Spec Lead Reply:
Easier methods to format/parse will probably be added.
The older classes are all likely to be updated with JSR-310 connections to enable interoperability.
-- Main.scolebourne - 2010-03-09

API looks good at first glance. Certainly gives me the feeling of a proper date/time API. Still working through the details...

-- Main.jhkuperus - 2010-03-09

I'm currently involved with an application that uses hundreds of thousands of GregorianCalendar objects in HTTP sessions on many JVM's resulting in crazy memory requirements. GregorianCalender turns out to use about 500 bytes. I'm not sure if you can blame the developers who use it in httpsession: how can they find out? It is not in the javadoc nor in an annotation like @MemoryHungry or so. I haven't looked into jsr-310 in detail, is jsr-310 going to solve this? E.g. by being efficient on memory usage and document cases otherwise?

-- Main.jborgers - 2010-03-11

Spec Lead Reply:
JSR-310 objects are better structured than the JDK, so I'd expect them to be lower memory. I've not profiled them yet though.
-- Main.scolebourne - 2010-03-18

Duration and Instant should use java.util.concurrent.TimeUnit in methods like minusXXX(), plusXXX() and the static factory methods (i.e. nanos and seconds). -- Main.dyokomizo - 2010-03-17

Spec Lead Reply:
Some integration with TimeUnit will be added, certainly in factory methods. Not sure about plus/minus though.
-- Main.scolebourne - 2010-03-18

Will the JDBC classes (PreparedStatement and ResultSet) be updated to allow use of the new objects in the APIs? i.e. overload setDate and setTimestamp in PreparedStatement to accept InstantProvider & TimeProvider, similarly provide additional methods on ResultSet to return various instances of InstantProviders.

This was a minor annoyance for me with JodaTime, having to make the sure the appropriate conversion was done in each case. With additions to the API, the conversions can be taken care of automatically.

Main.jhowarth - 2010-03-18

Spec Lead Reply:
This is the responsibility of the JDBC expert group. They follow JSR-310 closely and, I understand, intend to add methods along the lines of what you propose.
-- Main.scolebourne - 2010-03-18

I was looking for convinent methods in API. Can we add a method to have Duration between LocalDate instances. Something like, LocalDate dt1 = LocalDate.of(2006, 1, 24); LocalDate dt2 = LocalDate.of(2010, 1, 24); Duration d=Duration.durationBetween(dt1, dt2); Currently the the API takes InstantProvider to get the Duration..

Main.chandrasekhar_s - 2010-03-19

Spec Lead Reply:
This should have been on the TODO list. I've added it.
-- Main.scolebourne - 2010-03-19

Period.days(10).totalHours() will give 0 as, Period class, totalHours() is ignoring Days (It is properly documented though). To me totalHoursWith24HourDays() seems a bit confusing. Can we apply the standard definition of day to totalHours() and avoid the (duplicate) totalHoursWith24HourDays() method? Similar is the case with totalMinutes()/totalMinutesWith24HourDays(), totalSeconds()/totalSecondsWith24HourDays() and totalNanos().

-- Main.chandrasekhar_s - 2010-03-22

Spec Lead Reply:
The problem is that a day is not necessarily 24 hours long. At Daylight Savings start/end, a day is 23 or 25 hours long. These methods are intended to emphasise that point in the API. I'm not sure we can do anything else - the methods will appear next to one another in an IDE.
-- Main.scolebourne - 2010-04-12

For the default supported zones like Europe/London, America/New_York etc, can we define a String Constants class, just to avoid the wrong formats and also to list the supported zones.?

-- Main.chandrasekhar - 2010-03-22

Spec Lead Reply:
This may be possible for the major time zones, but that leads to the problem of picking which ones to support. Ideally it would be an Enum, but that isn't viable for a JDK library that changes rarely. We will consider this though.
-- Main.scolebourne - 2010-04-12

Recent changes to Early_Draft_Review

Early_Draft_Review modified by Stephen Colebourne

Early_Draft_Review modified by Stephen Colebourne

Early_Draft_Review modified by Stephen Colebourne

Forums / Articles / Blogs