These are the requirements / use cases that the JSR should seek to achieve:
Precision
Must support nanosecond precision
Must support at least plus/minus the age of the universe (13.7 billion years)
Instant
Typical use cases: time-stamp for logging, '36763681916 nanoseconds after 1970-01-01T00:00'
Create an object to represent an Instant
Must be able to create from millisecond timestamp
Must be able to create from nanosecond timestamp
Must not provide access to the date and time fields
Must be able to be compared to another instance - earlier/later/equals
Must be able to be converted to a date and time with time zone instance
Must be independent of all calendar systems
Must serialize using the internal timestamp relative to the epoch
Performance focussed around conversion to year/month/day/hour/minute/second
Date and time
Typical use cases: date and time train departs, '12th September 2007, 09:15'
Create an object to represent a Date and Time
Must be able to create from year, month, day, hour, minute, second
May be able to create from other field combinations
Must be able to call methods to access the date fields (year, month, day of month, hour, minute, second)
Must support additional date fields (day of year, day of week, week of weekyear, weekyear, era, ampm, hour of ampm, second of day ...)
Must not provide access to time fields (preferably by not having methods to call, but if they do exist they must throw an exception)
Must support precision to the hour, minute, second level (and nanosecond?)
Must be able to be compared to another instance - earlier/later/equals
Must link the datetime to a time zone, or to no time zone (local)
Must be able to be converted to an instant if a time zone is present
Must be specific to the ISO (proleptic Gregorian) calendar system
Must serialize using the field values
Date without time
Typical use cases: Birth date, transaction date, '12th September 2007'
Create an object to represent a Date without a Time
Must be able to create from year, month, day
May be able to create from other field combinations
Must be able to call methods to access the date fields (year, month, day of month)
Must support additional date fields (day of year, day of week, week of weekyear, weekyear, era, ...)
Must not provide access to time fields (preferably by not having methods to call, but if they do exist they must throw an exception)
Must be able to be compared to another instance - earlier/later/equals
Must link the date to a time zone, or to no time zone (local)
Must be specific to the ISO (proleptic Gregorian) calendar system
Must serialize using the field values
Year and Month
Typical use cases: Monthly newsletter 'Spetember 2007'
Create an object to represent a month in a specific year
Must be able to create from year, month
May be able to create from other field combinations
Must be able to call methods to access the fields (year, month)
Must support additional fields (quarter, month of quarter, era, ...)
Must not provide access to time fields or those requiring a day (preferably by not having methods to call, but if they do exist they must throw an exception)
Must be able to be compared to another instance - earlier/later/equals
Must be specific to the ISO (proleptic Gregorian) calendar system
Must serialize using the field values
Year
Typical use cases: Yearbook, '2007'
Create an object to represent a year
Must be able to create from year
May be able to create from other field combinations
Must be able to call methods to access the fields (year)
Must support additional fields (year of era, decade, century, era, ...)
Must not provide access to time fields or those requiring a day or month (preferably by not having methods to call, but if they do exist they must throw an exception)
Must be able to be compared to another instance - earlier/later/equals
Must be specific to the ISO (proleptic Gregorian) calendar system
Must serialize using the field values
Time without date
Typical use cases: office hours, '09:15'
Create an object to represent a Time without a Date
Must be able to create from hour, minute, second
May be able to create from other field combinations
Must be able to call methods to access the time fields (hour, minute, second)
Must support additional date fields (meridianAmPm, hour of ampm, nanosecond? ...)
Must not provide access to date fields (preferably by not having methods to call, but if they do exist they must throw an exception)
Must support precision to the hour, minute, second level (and nanosecond?)
Must be able to be compared to another instance - earlier/later/equals
Must link the time to a time zone, or to no time zone (local)
Must be specific to the ISO (proleptic Gregorian) calendar system
Must serialize using the field values
Current date and time
Typical use cases: logging the current instant, checking that a library book is not overdue
Must be able to control the current time for testing
Must support real time
Must allow real time plus offset to be supported
Must allow fixed time to be supported
Must allow real time progressing at a slower rate to be supported
Must be able to get the current instant
Must be able to get the current datetime, which requires a timezone
Must be able to get the current date - today, which requires a timezone
Must be able to get the next date - tomorrow, which requires a timezone
Must be able to get the previous date - yesterday, which requires a timezone
Must be able to get the current year-month, which requires a timezone
Must be able to get the current year, which requires a timezone
Must be able to get the current time, which requires a timezone
Time zones
Typical use cases: recording the time in Paris vs the time in New York
Must be able to obtain an instance representing a time zone
Must be able to query the standard offset at any given instant
Must be able to query the actual offset (including DST) at any given instant
Must be able to determine if DST applies for any given instant
Must be able to convert dates and times between time zones
Must support same instant conversion
Must support same local time conversion
Calendar systems
Must support the ISO (proleptic Gregorian) calendar system
Must be able to support other calendar systems, but not necessarily to the same degree
Date and time intervals
Typical use cases: Interval that a flight is in the air.
Must be able to obtain an instance representing an interval
Must be able to construct from a start and end datetime, where the precision of the datetimes is the same
Must be able to construct from a datetime and a duration before or after, where the precision of the duration matches that of the datetime
Must be able to convert to a duration
Must be able to compare to another interval to see if it is before, abuts-before, overlaps, contains, is contained, abuts-after, after, equals
Must be able to compare to a datetime to see if the datetime is before, contained or after
Must not support Comparable
Time intervals
Typical use cases: Time a shop is open, '09:00 to 17:00'
Must be able to obtain an instance representing a time interval
Must be able to construct from a start and end time
Must be able to construct from a time and a duration before or after
Must be able to support an interval that goes overnight, such as '22:00 to 08:00' (and any number of days?)
Must be able to convert to a duration
Must be able to compare to another time interval to see if it is before, abuts-before, overlaps, contains, is contained, abuts-after, after, equals
Must be able to compare to a time to see if the datetime is before, contained or after
Must not support Comparable
Formatting
Must be able to format datetimes
Must be able to format instants
Must be able to format intervals
Must be able to format durations
Must support ISO8601 date format
Must support RFC date formats
Must support multi-lingual text for day of week, month, era, ...
Must support multi-lingual text for day of week, month, era, ...
General ideas
Good integration with Date and Calendar.
Good integration with JDBC.
Specify unambiguously the deadline for filing a tax return when I'm sitting in HI, logged into an office in NJ, submitting to a server in CA a return which will be processed in CO. (Bruce Hamilton)
Given an arbitrary date, return the last day of the week or month that the given day is in. (2007-5-13, BarendGarvelink)
It would be useful to find the dates of weekdays like '3rd Tuesday in May', 'Sunday before 25th Dec' without having to check through every day (lucretius2 - 23 Jul 2007)
Work easily with Date/Time classes in a JSTL JSP. (2007-5-13, BarendGarvelink)