Use_cases modified by Stephen Colebourne

Stephen Colebourne — Thu, 22 May 2014 22:08:07 -0000

--- v3
+++ v4
@@ -82,7 +82,7 @@
     * 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 support additional 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

Use_cases modified by Stephen Colebourne

Stephen Colebourne — Thu, 22 May 2014 22:08:07 -0000

--- v2
+++ v3
@@ -27,8 +27,7 @@
     * 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 additional date/time fields (day of year, day of week, week of weekyear, weekyear, era, ampm, hour of ampm, second of day ...) 
   * 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)

Use_cases modified by Stephen Colebourne

Stephen Colebourne — Thu, 22 May 2014 22:08:07 -0000

--- v1
+++ v2
@@ -156,7 +156,7 @@
   * Must support ISO8601 date format 
   * Must support RFC date formats 
   * Must support multi-lingual text for day of week, month, era, ... 
-  * Handle negative suffixes - [[http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4823811...](http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4823811)[bug 4823811]] 
+  * Handle negative suffixes - [bug 4823811](http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4823811)

 ## Parsing

Use_cases modified by Stephen Colebourne

Stephen Colebourne — Thu, 22 May 2014 22:08:07 -0000

These are the requirements / use cases that the JSR should seek to achieve:

Precision
Instant
Date and time
Date without time
Year and Month
Year
Time without date
Current date and time
Time zones
Calendar systems
Date and time intervals
Time intervals
Formatting
Parsing
General ideas
Other information

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 - [http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4823811...[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 <a href='http://www.martinfowler.com/bliki/FluentInterface.html'>fluent interface</a>.

Other information

Other groups and papers on time:

Date time projects:

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

Home page

Recent changes to Use_cases

Use_cases modified by Stephen Colebourne

Use_cases modified by Stephen Colebourne

Use_cases modified by Stephen Colebourne

Use_cases modified by Stephen Colebourne

Precision

Instant

Date and time

Date without time

Year and Month

Year

Time without date

Current date and time

Time zones

Calendar systems

Date and time intervals

Time intervals

Formatting

Parsing

General ideas

Other information