Menu ▾ ▴

Use_cases

Stephen Colebourne

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/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)
  • 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 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 <a href='http://www.martinfowler.com/bliki/FluentInterface.html'>fluent interface</a>.

Other information

Other groups and papers on time:

Date time projects:

Related

OldWiki: Old_home_page
OldWiki: ThreeTen

Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.