Interface DateTime

All Superinterfaces:
Comparable<DateTime>, DateTime, OsidPrimitive, OsidPrimitive, Serializable
public interface DateTime extends OsidPrimitive, DateTime

The DateTime interface defines a date and/or time. This interface provides a very broad range of dates, describes more or less precision, and/or conveys an uncertainty. A number of convenience methods for retrieving time elements are available but only those methods covered by the specified granularity are valid.

DateTime is a combination of a date and a time. The behavior of the date portion implies a subtely different behavior than the rest of the interface. What follows is an interpretation based on the Gregorian calendar most of use today.

  • Time Values: Elements count up to the next level. There are 1000 milliseconds in a second and 60 minutes in an hour. Each fractional second behaves like it's own clock hand.
  • Time Granularity: Elements below (more fine grained) their specified granularity are meaningless. Don't ask for attoseconds at a SECOND granularity.
  • Date Granularity: Elements below their specified granularity are meaningless. Don't ask for years at an AEON granularity.
  • Date Values: Elements DAY AND MONTH count up to the next level and wraparound like time. There are 12 months in a year.
  • Years: Years are proleptic and continue infinitely into the future and back into the past (infinite in this case means the limit of the counter).
  • Big Year Values: The largest countable element on a Gregorian Calendar is YEAR. Less granular elements than YEARS (CENTURIES) are calculated from the YEAR. 2026 is CENTURY 21, MILLENNIUM 3, AEON 1.
  • Limitations: There is an unspecified practial limitation of 9.22 quintillion years which is plenty of range to put the Big Rip on your calendar. At AEON granularity, that number increases to 9.22 sextiliion. We do expect to see a far future release of the OSIDs to address any limitations describing universe-ending milestones beyond that timeframe.

The counting behavior and the semantic meaning of the elements is determined by the Calendar and Time Systems used although it is expected the fractional second behavior remains constant.

A typical example is describing a day where the time isn't known, and the event did not occur at midnight. 

getMillennium() == 2
getCentury() == 18
getYear() == 1776
getMonth() == 7
getDay() == 4
getHour() == 0
getGranularity() == DateTimeResolution.DAY
definesUncertainty() == false

Another example showing that the time is probably 1pm but could have been as late as 3pm or early as noon. 

getMillennium() == 3
getCentury() == 21
getYear() == 2008
getMonth() == 3
getDay() == 17
getHour() == 13
getMinute() == 0
getGranularity() == TimeResolution.MINUTE
definesUncertainty() == true
getUncertaintyGranularity() == DateTimeResolution.HOUR
getUncertaintyMinus() == 1
getUncertaintyPlus == 2

An example marking the birth of the universe. 13.73 billion years +/- 120 million years. The granularity suggests that no more resolution than one million years can be inferred from the "clock", making errors in the exact number of millennia insignificant. 

getEpoch() == -13,730
getGranularity() == TimeResolution.EPOCH
definesUncertainty() == true
getUncertaintyGranularity() == DateTimeResolution.EPOCH
getUncertaintyMinus() == 120
getUncertaintyPlus == 120

The way to think about granularity versus uncertainty is that granularity is the space between the clock ticks. A clock which displays minutes cannot tell you the second something occurred. Uncertainty is based on the measurement. My digital camera reports times in 100ms increments. That's as granular as it gets. It does not run a NTP client, so it can be a few minutes off. That's its uncertainty.

Finally, uncertainty may be inclusive. Plus or minus 1 year implies the entire two year range of time inclusive of every fractional second in between. A non-inclusive uncertainty implies only three DateTimes -- now, this time 1 year ago, and this time 1 year from now. "This is a photo of the family at Christmas dinner. It could have been 1982 or 1983."

  • Method Details

    • getCalendarType

      Type getCalendarType()
      Gets the calendar type.
      Returns:
      the calendar type
      Compliance:
      mandatory - This method must be implemented.

    • getAeon

      long getAeon()
      Gets the aeon. An aeon is 1B years.
      Returns:
      the aeon
      Compliance:
      mandatory - This method must be implemented.

    • getEpoch

      long getEpoch()
      Gets the epoch. An epoch is 1M years.
      Returns:
      the eposh
      Compliance:
      mandatory - This method must be implemented.

    • getMillennium

      long getMillennium()
      Gets the millennium. A millenium is 1,000 years.
      Returns:
      the millennium
      Compliance:
      mandatory - This method must be implemented.

    • getCentury

      long getCentury()
      Gets the century.
      Returns:
      the century
      Compliance:
      mandatory - This method must be implemented.

    • getYear

      long getYear()
      Gets the year.
      Returns:
      the year
      Compliance:
      mandatory - This method must be implemented.

    • getMonth

      long getMonth()
      Gets the month number.
      Returns:
      the month
      Compliance:
      mandatory - This method must be implemented.

    • getWeek

      long getWeek()
      Gets the week.
      Returns:
      the week
      Compliance:
      mandatory - This method must be implemented.

    • getDay

      long getDay()
      Gets the day.
      Returns:
      the day of the month
      Compliance:
      mandatory - This method must be implemented.

    • getTimeType

      Type getTimeType()
      Gets the time type.
      Returns:
      the time type
      Compliance:
      mandatory - This method must be implemented.

    • getHour

      long getHour()
      Gets the hour of the day.
      Returns:
      the hour of the day
      Compliance:
      mandatory - This method must be implemented.

    • getMinute

      long getMinute()
      Gets the minute of the hour.
      Returns:
      the minute of the hour
      Compliance:
      mandatory - This method must be implemented.

    • getSecond

      long getSecond()
      Gets the second of the minute.
      Returns:
      the second of the minute
      Compliance:
      mandatory - This method must be implemented.

    • getMilliseconds

      long getMilliseconds()
      Gets the number of milliseconds in this second 0-999. A millisecond is one thousandth (1e-3) of a second.
      Returns:
      the milliseconds of the second
      Compliance:
      mandatory - This method must be implemented.

    • getMicroseconds

      long getMicroseconds()
      Gets the number of microseconds of the second 0-999. A microsecond is one millionth (1e-6) of a second.
      Returns:
      the micrseconds of the millisecond
      Compliance:
      mandatory - This method must be implemented.

    • getNanoseconds

      long getNanoseconds()
      Gets the number of nanoseconds of the microsecond 0-999. A nanosecond is one billionth (1e-9) of a second.
      Returns:
      the nanoseconds of the microsecond
      Compliance:
      mandatory - This method must be implemented.

    • getPicoseconds

      long getPicoseconds()
      Gets the number of picoseconds of the nanosecond 0-999. A picosecond is one trillionth (1e-12) of a second.
      Returns:
      the picoseconds of the nanosecond
      Compliance:
      mandatory - This method must be implemented.

    • getFemtoseconds

      long getFemtoseconds()
      Gets the number of femtoseconds of the picosecond 0-999. A femtosecond is one quadrillionth (1e-15) of a second.
      Returns:
      the femtoseconds of the picosecond
      Compliance:
      mandatory - This method must be implemented.

    • getAttoseconds

      long getAttoseconds()
      Gets the number of attoseconds of the femtoseconds 0-999. An attosecond is one quintillionth (1e-18) of a second.
      Returns:
      the attoseconds of the femtosecond
      Compliance:
      mandatory - This method must be implemented.

    • getZeptoseconds

      long getZeptoseconds()
      Gets the number of zeptoseconds of the attosecond 0-999. A zeptosecond is one sextillionth (1e-21) of a second.
      Returns:
      the zeptoseconds of the attosecond
      Compliance:
      mandatory - This method must be implemented.

    • getYoctoseconds

      long getYoctoseconds()
      Gets the number of yoctoseconds of the picosecond 0-999. A yoctosecond is one septillionth (1e-24) of a second. This is getting quite small.
      Returns:
      the yoctoseconds of the picosecond
      Compliance:
      mandatory - This method must be implemented.

    • getRontoseconds

      long getRontoseconds()
      Gets the number of rontoseconds of the yoctosecond 0-999. A rontosecond is one octillionth (1e-27) of a second.
      Returns:
      the rontoseconds of the yoctosecond
      Compliance:
      mandatory - This method must be implemented.

    • getQuectoseconds

      long getQuectoseconds()
      Gets the number of quectoseconds of the rontosecond 0-999. A quectosecond is one nonillionth (1e-30) of a second.
      Returns:
      the quectoseconds of the rontoseconds
      Compliance:
      mandatory - This method must be implemented.

    • getMilliquectoseconds

      long getMilliquectoseconds()
      Gets the number of milliquectoseconds of the quectosecond 0-999. A milliquectosecond is one decillionth (1e-33) of a second.
      Returns:
      the milliquectoseconds of the quectosecond
      Compliance:
      mandatory - This method must be implemented.

    • getMicroquectoseconds

      long getMicroquectoseconds()
      Gets the number of microquectoseconds of the milliquectosecond 0-999. A microquectosecond is one undecillionth (1e-36) of a second.
      Returns:
      the microquectoseconds of the milliquectosecond
      Compliance:
      mandatory - This method must be implemented.

    • getPlanckseconds

      long getPlanckseconds()
      Gets the number of planckseconds of the microquectosecond. A plancksecond is 53.91247 quattuordecillionths (5.391247e-44) of a second.
      Returns:
      the plancks of the microquectosecond
      Compliance:
      mandatory - This method must be implemented.

    • getGranularity

      DateTimeResolution getGranularity()
      Gets the granularity of this time. The granularity indicates the resolution of the clock (the tick). More precision than what is specified in this method cannot be inferred from the available data.
      Returns:
      granularity
      Compliance:
      mandatory - This method must be implemented.

    • getGranularityMultiplier

      long getGranularityMultiplier()
      If the granularity of the time equals getGranularity(), then the multiplier is 1. This method may return a different number when the granularity differs from one of the defined resolutions.
      Returns:
      granularity multiplier
      Compliance:
      mandatory - This method must be implemented.

    • definesUncertainty

      boolean definesUncertainty()
      Tests if uncertainty is defined for this time.
      Returns:
      true if uncertainty is defined, false otherwise
      Compliance:
      mandatory - This method must be implemented.

    • getUncertaintyUnits

      DateTimeResolution getUncertaintyUnits()
      Gets the units of the uncertainty.
      Returns:
      units of the uncertainty
      Throws:
      IllegalStateException - definesUncertainty() is false
      Compliance:
      mandatory - This method must be implemented.

    • getUncertaintyMinus

      long getUncertaintyMinus()
      Gets the uncertainty of this datetime in the negative direction.
      Returns:
      the uncertainty under this value
      Throws:
      IllegalStateException - definesUncertainty() is false
      Compliance:
      mandatory - This method must be implemented.

    • getUncertaintyPlus

      long getUncertaintyPlus()
      Gets the uncertainty of this datetime in the positive direction.
      Returns:
      the uncertainty over this value
      Throws:
      IllegalStateException - definesUncertainty() is false
      Compliance:
      mandatory - This method must be implemented.

    • isUncertaintyDateInclusive

      boolean isUncertaintyDateInclusive()
      Tests if the uncertainty is inclusive of all dates. An inclusive uncertainty includes the entire range specified by the uncertainty units e.g. +/- 1 year includes all of the months and days within that interval. A non-inclusive uncertainty would mean the year is uncertain but the month and day is certain.
      Returns:
      true if the uncertainty includes all dates, false otherwise
      Throws:
      IllegalStateException - definesUncertainty() is false
      Compliance:
      mandatory - This method must be implemented.