• Handle negative suffixes - bug 4823811

• Performance focussed around conversion to year/month/day/hour/minute/second

• Must support nanosecond precision
• Must support at least plus/minus the age of the universe (13.7 billion years)

• 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

• 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

• 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

• 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

• 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

• 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

• 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

• 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

• Must support the ISO (proleptic Gregorian) calendar system
• Must be able to support other calendar systems, but not necessarily to the same degree

• 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

• 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

• 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 be able to parse datetimes
• Must be able to parse instants
• Must be able to parse intervals
• Must be able to parse durations
• Must support ISO8601 date format
• Must support RFC date formats
• Must support multi-lingual text for day of week, month, era, ...

• 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)

• Strive for a < a href='http://www.martinfowler.com/bliki/FluentInterface.html'>fluent interface.

• Work easily with Date/Time classes in a JSTL JSP. (2007-5-13, BarendGarvelink)

• Given an arbitrary date, return the last day of the week or month that the given day is in. (2007-5-13, BarendGarvelink)

• 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)

• Joda-Time: http://joda-time.sourceforge.net
• Time and Money: http://timeandmoney.sourceforge.net/
• Recurrences: http://code.google.com/p/google-rfc-2445/
• Geo API: http://geoapi.sourceforge.net/pending/javadoc/org/opengis/temporal/package-summary.html

• iCal - http://google-rfc-2445.googlecode.com/svn/trunk/rfc2445.html

• http://www.cgd.ucar.edu/cms/eaton/cf-metadata/CF-1.0.html#cal

Date time projects:

• http://joda-time.sourceforge.net
• http://timeandmoney.sourceforge.net/
• http://code.google.com/p/google-rfc-2445/

• Comprehensive support for ISO8601 standard

• There should be comprehensive support for very ancient times (BC) as they are used in some sciences (e.g. paleontology).

• Integration with date/time formatting for date, time, interval, etc

• http://www.w3.org/TR/2005/NOTE-timezone-20051013/

• There should be a way to represent a date without a time. This is useful in many applications, for example a birth date.
• There should be a simple set of methods to construct a date today, yesterday and tomorrow.
• There should be a way to represent a time without a date. This is used for a flight time, or meeting time.
• There should be a way to represent a date and time at a point on the globe represented by a timezone.
• There should be a way to represent a timestamp. This is used for comparing points in time.
• Support nano-second precision for timestamps.
• The serialization and deserialization of an object representing a date, time or datetime should recreate the same date/time. This needs to happen even if the time zone rules have changed whilst the object was serialized.
• There should be support for date ranges, time ranges, datetime ranges.
• It must be easy to convert dates from one time zone to another, as well as changing the timezone while preserving the "absolute" date/time info.
• Good integration with Date and Calendar.
• Good integration with JDBC.

JSR 310 Date and Time - Use cases

These are the use cases that the JSR should seek to achieve.

There should be a way to represent a date without a time. This is useful in many applications, for example a birth date.

There should be a simple set of methods to construct a date today, yesterday and tomorrow.

There should be a way to represent a time without a date. This is used for a flight time, or meeting time.

There should be a way to represent a date and time at a point on the globe represented by a timezone.

There should be a way to represent a timestamp. This is used for comparing points in time.

Support nano-second precision for timestamps.

The serialization and deserialization of an object representing a date, time or datetime should recreate the same date/time. This needs to happen even if the time zone rules have changed whilst the object was serialized.

There should be support for date ranges, time ranges, datetime ranges.

Good integration with Date and Calendar.

Good integration with JDBC.