 |
JSR 310 Date and Time - Use cases
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, ...
- Handle negative suffixes - bug 4823811
Parsing
- 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, ...
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)
- Strive for a fluent interface.
Other groups and papers on time:
Date time projects:
|