Find JSRs
Submit this Search


Ad Banner
 
 
 
 

Summary  |  Proposal  |  Detail (Summary & Proposal)
JSRs: Java Specification Requests
JSR 310: Date and Time API

Stage Access Start Finish
Final Release Download page 04 Mar, 2014  
Final Approval Ballot View results 18 Feb, 2014 03 Mar, 2014
Proposed Final Draft Download page 14 Jan, 2014  
Public Review Ballot View results 10 Dec, 2013 23 Dec, 2013
Public Review Download page 04 Nov, 2013 04 Dec, 2013
Early Draft Review 2 Download page 14 Sep, 2012 14 Oct, 2012
Early Draft Review Download page 26 Feb, 2010 28 Mar, 2010
Expert Group Formation   13 Feb, 2007  
JSR Review Ballot View results 30 Jan, 2007 12 Feb, 2007
Status: Active
JCP version in use: 2.9
Java Specification Participation Agreement version in use: 2.0


Description:
This JSR will provide a new and improved date and time API for Java.

Expert Group Transparency:
  Public Communications
  Issue Tracking

Team

Specification Leads
  Stephen Colebourne Colebourne, Stephen
  Roger Riggs Oracle
  Michael Nascimento Santos Santos, Michael Nascimento
Expert Group
  Adam Bien Stephen Colebourne Google Inc.
: Kevin Bourrillion
  Mikael Grev IBM
: Toby Corbin
Oracle
: Masayoshi Okutsu
  Oracle
: Roger Riggs
Oracle
: Douglas Surber
RedHat
: David Lloyd
  Richey Jr., Clark D. Michael Nascimento Santos Sun Microsystems, Inc.
: Masayoshi Okutsu

Updates to the Original JSR

The following information has been updated from the original proposal.

2014.02.14:
Since the Early Draft Review 2:

2.18 Please provide a description of the business terms for the Specification, RI and TCK that will apply when this JSR is final.

The final specification will use the standard JCP license.
The Reference Implementation and Technology Compatibility Kit licenses will be the same as for JSR 337: JavaTM SE 8 Release Contents.
 
2012.11.14:

2.19 Please describe the communications channel you have established for the public to observe Expert Group deliberations, provide feedback, and view archives of all Expert Group communications.

Comments should be sent to the threeten-develop mail list https://lists.sourceforge.net/lists/listinfo/threeten-develop
Expert Group communications are archived at https://lists.sourceforge.net/lists/listinfo/threeten-develop

2.20 What is the URL of the Issue Tracker that the public can read, and how does the public log issues in the Issue Tracker?

https://github.com/ThreeTen/threeten/issues?state=open

2.21 Please provide the location of the publicly accessible document archive you have created for the Expert Group.

http://sourceforge.net/apps/mediawiki/threeten/index.php?title=ThreeTen

2012.04.10:

Specification Leads: Stephen Colebourne (self), Michael Nascimento Santos (self), Roger Riggs (Oracle)

E-Mail Address: scolebourne@joda.org, misterm@gmail.com, roger.riggs@oracle.com

Telephone Number: -, -, +1 781 442 0539

Fax Number: -, -, +1 781 442 1610

2012.02.27:

2.13 Please describe the anticipated schedule for the development of this specification.

A first Early Draft Review has occurred. A second one is anticipated during mid 2012. With successful progress it is intended that this JSR can be considered for inclusion in Java SE 8.

2.15 It is important to the success of the community and each JSR that the work of the Expert Group be handled in a manner which provides the community and the public with insight into the work the Expert Group is doing, and the decisions that the Expert Group has made. The Executive Committees would like to ensure Spec Leads understand the value of this transparency and ask that each JSR have an operating plan in place for how their JSR will address the involvement of the community and the public. Please provide your plan here, and refer to the Spec Lead Guide for a more detailed description and a set of example questions you may wish to answer in your plan.

http://threeten.sourceforge.net

Both spec leads are experienced open source practitioners and intend to drive the JSR as transparently as possible. Stephen Colebourne founded and leads the Joda-Time project, and is a member of the Apache Software Foundation, with contributions focused on Jakarta-Commons. Michael Nascimento Santos founded and leads the Genesis project, and has made contributions to NetBeans, AspectWerkz, and Thinlet. Michael also has experience from 5 previous JSRs.

To achieve the transparency, the reference implementation will be developed on a publicly viewable sourcebase, and the primary mailing list will be open to any member of the Java community. As the specification will be driven by of the reference implementation, this will have the effect of a continuously available specification draft. Weblogs, forums and articles will also be used to generate interest in the JSR.

2.18 Please provide a description of the business terms for the Specification, RI and TCK that will apply when this JSR is final.


The main reference implementation uses the BSD license - https://github.com/ThreeTen/threeten/blob/master/LICENSE.txt
The TCK will be under the same BSD license as the main code.
The final specification will use the standard JCP license.

2010.02.24:

2.18 Please provide a description of the business terms for the Specification, RI and TCK that will apply when this JSR is final.

The main reference implementation uses the BSD license - https://jsr-310.dev.java.net/source/browse/jsr-310/tags/TRUNK_EDR_201002/LICENSE.txt?rev=1003&view=markup
It is our intention that the TCK will be under the same BSD license as the main code.
The final specification will use the standard JCP license.


Original Java Specification Request (JSR)

Identification | Request | Contributions | Additional Information

Section 1. Identification

Submitting Member:Stephen Colebourne

Name of Contact Person: Stephen Colebourne, Michael Nascimento Santos

E-Mail Address: scolebourne@joda.org, misterm@gmail.com

Telephone Number:

Fax Number:


Specification Leads: Stephen Colebourne, Michael Nascimento Santos

E-Mail Address: scolebourne@joda.org, misterm@gmail.com

Telephone Number:

Fax Number:


Initial Expert Group Membership:

Colebourne, Stephen
Google Inc.
Santos, Michael Nascimento
Sun Microsystems, Inc

Supporting this JSR:

Apache Software Foundation
Colebourne, Stephen
Google Inc.
Ivankovits, Mario
Lea, Doug
Leme, Felipe
Mulkers, Robin
Pemberton, Niall
Red Hat Middleware LLC
Richey Jr., Clark D.
Sabino, Vanessa
Santos, Michael Nascimento
SouJava
Souza, Bruno
Strachan, James
Suleiman, Hani
Sun Microsystems, Inc
Valle, Mauro do
Vasseur, Alexandre



Section 2: Request

2.1 Please describe the proposed Specification:

This JSR will provide a new and improved date and time API for Java. The main goal is to build upon the lessons learned from the first two APIs (Date and Calendar) in Java SE, providing a more advanced and comprehensive model for date and time manipulation.

The new API will be targeted at all applications needing a data model for dates and times. This model will go beyond classes to replace Date and Calendar, to include representations of date without time, time without date, durations and intervals. This will raise the quality of application code. For example, instead of using an int to store a duration, and javadoc to describe it as being a number of days, the date and time model will provide a class defining it unambiguously.

The new API will also tackle related date and time issues. These include formatting and parsing, taking into account the ISO8601 standard and its implementations, such as XML. In addition, the areas of serialization and persistence will be considered.

The final goal of the new API is to be simple to use. The API will need to contain some powerful features, but these must not be allowed to obscure the standard use cases. Part of being easy to use includes interaction with the existing Date and Calendar classes, something that will be a key focus of the Expert Group.

2.2 What is the target Java platform? (i.e., desktop, server, personal, embedded, card, etc.)

Java SE.

2.3 The Executive Committees would like to ensure JSR submitters think about how their proposed technology relates to all of the Java platform editions. Please provide details here for which platform editions are being targeted by this JSR, and how this JSR has considered the relationship with the other platform editions.

This JSR is targeted at Java SE, but the date and time classes have the potential to be widely used. Other specifications, from Java SE or Java EE, may wish to examine or contribute to this JSR, and eventually use the new model. Such changes are outside the remit of this JSR, but input from those groups will be welcomed.

Java ME is not targeted by this JSR. A future JSR or revision may wish to build upon the work done here to provide a subset of features for Java ME.

2.4 Should this JSR be voted on by both Executive Committees?

No.

2.5 What need of the Java community will be addressed by the proposed specification?

Currently Java SE has two separate date and time APIs - java.util.Date and java.util.Calendar. Both APIs are consistently described as difficult to use by Java developers on weblogs and forums. Notably, both use a zero-index for months, which is a cause of many bugs. Calendar has also suffered from many bugs and performance issues over the years, primarily due to storing its state in two different ways internally.

One classic bug (4639407) prevented certain dates from being created in a Calendar object. A sequence of code could be written that could create a date in some years but not in others, having the effect of preventing some users from entering their correct birth dates. This was caused by the Calendar class only allowing a daylight savings time gain of one hour in summer, when historically it was plus 2 hours around the time of the second world war. While this bug is now fixed, if at some point in the future a country chose to introduce a daylight savings time gain of plus three hours in summer, then the Calendar class would again be broken.

The current Java SE API also suffers in multi-threaded environments. Immutable classes are known to be inherently thread-safe as their state cannot change. However, both Date and Calendar are mutable, which requires programmers to consider cloning and threading explicitly. In addition, the lack of thread-safety in DateTimeFormat is not widely known, and has been the cause of many hard to track down threading issues.

As well as the problems with the classes that Java SE has for datetime, it has no classes for modelling other concepts. Non-time-zone dates or times, durations, periods and intervals have no class representation in Java SE. As a result, developers frequently use an int to represent a duration of time, with javadoc specifying the unit.

The lack of a comprehensive date and time model also results in many common operations being trickier than they should be. For example, calculating the number of days between two dates is a particularly hard problem at present.

This JSR will tackle the problem of a complete date and time model, including dates and times (with and without time zones), durations and time periods, intervals, formatting and parsing.

2.6 Why isn't this need met by existing specifications?

Java SE currently has no comprehensive model for date and time.

No other JSR is working on this topic. The closest specification is JSR-275 (Units and Quantities), however this tackles the scientific usage of time (specifically duration) and not the business/commercial usage of time envisaged by this JSR.

2.7 Please give a short description of the underlying technology or technologies:

This JSR will initially develop code using standard functionality based on Java SE 5. It is not envisaged at present that there is any need to use specific functionality from Java SE 6. The specification will track language developments proposed for Java SE 7 and consider whether this JSR should make use of them.

In terms of design, it is intended that immutable classes will form the core. It is also intended to use interfaces, if possible, to bring the old Date and Calendar classes into the new model. The expert group will also examine if Calendar can be reimplemented internally using the new date and time classes.

2.8 Is there a proposed package name for the API Specification? (i.e., javapi.something, org.something, etc.)

The library will use javax.time.* retaining the possibility to use java.util.time.* if included in a future version of Java SE.

2.9 Does the proposed specification have any dependencies on specific operating systems, CPUs, or I/O devices that you know of?

Only indirectly. The expert group will review whether System.currentTimeMillis() can be retrofitted with a mechanism to effectively change the apparent date and time within the whole JVM.

2.10 Are there any security issues that cannot be addressed by the current security model?

No.

2.11 Are there any internationalization or localization issues?

No issues are expected.

2.12 Are there any existing specifications that might be rendered obsolete, deprecated, or in need of revision as a result of this work?

It is intended that this JSR will produce classes that effectively replace the need for the existing Date and Calendar APIs. Over time we look forward to other specifications being updated to us the new date and time API.

2.13 Please describe the anticipated schedule for the development of this specification.

Early Draft Review by mid 2007. With successful progress it is intended that this JSR can be considered for inclusion in Java SE 7.

Note that this section has been updated from this original proposal.

2.14 Please describe the anticipated working model for the Expert Group working on developing this specification.

It is intended that this JSR is run as transparently as possible. The primary mailing list will be open to anyone in the Java community to contribute to. The reference implementation sourcebase will also be publicly viewable. The project will have a homepage at java.net and tools such as blogs and internet forums will be used to advertise the ongoing process as appropriate.

On occasion, it may be necessary for the expert group to have closed discussions. These will primarily be held on a closed mailing list. Other means of communication, such as teleconference or instant messaging, may be used as the participants feel appropriate.

2.15 It is important to the success of the community and each JSR that the work of the Expert Group be handled in a manner which provides the community and the public with insight into the work the Expert Group is doing, and the decisions that the Expert Group has made. The Executive Committees would like to ensure Spec Leads understand the value of this transparency and ask that each JSR have an operating plan in place for how their JSR will address the involvement of the community and the public. Please provide your plan here, and refer to the Spec Lead Guide for a more detailed description and a set of example questions you may wish to answer in your plan.

Both spec leads are experienced open source practitioners and intend to drive the JSR as transparently as possible. Stephen Colebourne founded and leads the Joda-Time project, and is a member of the Apache Software Foundation, with contributions focused on Jakarta-Commons. Michael Nascimento Santos founded and leads the Genesis project, and has made contributions to NetBeans, AspectWerkz, and Thinlet. Michael also has experience from 5 previous JSRs.

To achieve the transparency, the reference implementation will be developed on a publicly viewable sourcebase, and the primary mailing list will be open to any member of the Java community. As the specification will be driven by of the reference implementation, this will have the effect of a continuously available specification draft. Weblogs, forums and articles will also be used to generate interest in the JSR.

Note that this information has been updated from this original proposal.

2.16 Please describe how the RI and TCK will de delivered, i.e. as part of a profile or platform edition, or stand-alone, or both. Include version information for the profile or platform in your answer.

The codebase will initially be developed separately from the JDK. However, the goal of the JSR is inclusion in a future version of Java SE.

2.17 Please state the rationale if previous versions are available stand-alone and you are now proposing in 2.13 to only deliver RI and TCK as part of a profile or platform edition (See sections 1.1.5 and 1.1.6 of the JCP 2 document).

There is no previous version.

2.18 Please provide a description of the business terms for the Specification, RI and TCK that will apply when this JSR is final.

The RI and TCK will be available free of charge in both binary and source forms using a business-friendly, Open Source license similar to the BSD or Apache Software License.

Note that this information has been updated from this original proposal.





Section 3: Contributions

3.1 Please list any existing documents, specifications, or implementations that describe the technology. Please include links to the documents if they are publicly available.

This JSR will draw heavily on experience gained from the Joda-Time project ( http://joda-time.sourceforge.net). This project reached version 1.0 in early 2005 and is now at version 1.4. Invaluable lessons have been learned and many use cases gathered from user requests.

Other projects which have worked in this area include ICU ( http://icu.sourceforge.net/), Time and Money ( http://timeandmoney.domainlanguage.com/) and Calendar Date ( http://calendardate.sourceforge.net/).

3.2 Explanation of how these items might be used as a starting point for the work.

Joda-Time defines a model and implementation classes for dates, times, durations, periods, intervals, formatting and parsing. The aim is not to port Joda-Time directly into Java, but to learn from it with ideas and code from other sources in the community.



Section 4: Additional Information (Optional)

4.1 This section contains any additional information that the submitting Member wishes to include in the JSR.