Early Draft Review for JSR-310 Specification: Date and Time API

Stephen Colebourne, Michael Nascimento Santos (et al, eds), JSR DraftProject editors for Java Specification Request 310: Date and Time APIhave published an Early Draft Review (EDR) to to gain feedback on anearly version of the JSR. The contents of the EDR are the prosespecification and the javadoc. According to the original publishedRequest, JSR 310 "will provide a new and improved date and time API forJava. The main goal is to build upon the lessons learned from the firsttwo APIs (Date and Calendar) in Java SE, providing a more advanced andcomprehensive model for date and time manipulation.The new API will be targeted at all applications needing a data modelfor dates and times. This model will go beyond classes to replace Dateand Calendar, to include representations of date without time, timewithout date, durations and intervals. This will raise the quality ofapplication code. For example, instead of using an int to store aduration, and javadoc to describe it as being a number of days, thedate and time model will provide a class defining it unambiguously.The new API will also tackle related date and time issues. These includeformatting and parsing, taking into account the ISO8601 standard andits implementations, such as XML. In addition, the areas of serializationand persistence will be considered... In this specification model,dates and times are separated into two basic use cases: machine-scaleand human-scale. Machine-scale time represents the passage of timeusing a single, continually incrementing number. The rules thatdetermine how the scale is measured and communicated are typicallydefined by international scientific standards organisations. Human-scaletime represents the passage of time using a number of named fields,such as year, month, day, hour, minute and second. The rules thatdetermine how the fields work together are defined in a calendar system...From the specification introduction: "Many Java applications requirelogic to store and manipulate dates and times. At present, Java SEprovides a number of disparate APIs for this purpose, including Date,Calendar, SQL Date/Time/Timestamp and XML Duration/XMLGregorianCalendar.Unfortunately, these APIs are not all particularly well-designed andthey do not cover many use cases needed by developers. As an example,Java developers currently have no standard Java SE class to representthe concept of a date without a time, a time without a date or aduration. The result of these missing features has been widespreadabuse of the facilities which are provided, such as using the Date orCalendar class with the time set to midnight to represent a datewithout a time. Such an approach is very error-prone - there arecertain time zones where midnight doesn't exist once a year due tothe daylight saving time cutover. JSR-310 tackles this by providinga comprehensive set of date and time classes suitable for Java SEtoday. The specification includes: Date and Time; Date without Time;Time without Date; Offset from UTC; Time Zone; Durations; Periods;Formatting and Parsing; A selection of calendar systems...Design Goals for JSR-310: (1) Immutable - The JSR-310 classes shouldbe immutable wherever possible. Experience over time has shown thatAPIs at this level should consist of simple immutable objects. Theseare simple to use, can be easily shared, are inherently thread-safe,friendly to the garbage collector and tend to have fewer bugs due tothe limited state-space. (2) Fluent API - The API strives to be fluentwithin the standard patterns of Java SE. A fluent API has methodsthat are easy to read and understand, specifically when chainedtogether. The key goal here is to simplify the use and enhance thereadability of the API. (3) Clear, explicit and expected - Eachmethod in the API should be well-defined and clear in what it does.This isn't just a question of good javadoc, but also of ensuring thatthe method can be called in isolation successfully and meaningfully.(4) Extensible - The API should be extensible in well defined waysby application developers, not just JSR authors. The reasoning issimple - there are just far too many weird and wonderful ways tomanipulate time. A JSR cannot capture all of them, but an extensibleJSR design can allow for them to be added as required by applicationdevelopers or open source projects..."http://wiki.java.net/bin/view/Projects/DateTimeEDR1See also the InfoQueue article by Alex Blewitt and Charles Humble: http://www.infoq.com/news/2010/03/jsr-310