DateTime Implementations

Summary

This section describes the Primordium implementations of org.osid.calendaring.DateTime.

Implementations

class	calendar type	time type
net.okapia.osid.primordium.calendaring.GregorianUTCDateTime	Gregorian	UTC

GregorianUTCDateTime

GregorianUTCDateTime is a final immutable class.

Constructors

GregorianUTCDateTime Constructor

    /**
     *  Constructs a new GregorianUTCDateTime.
     *
     *  @param specifier a datetime specifier
     *  @throws org.osid.NullArgumentException specifier is null
     */

    public GregorianUTCDateTime(GregorianUTCDateTime.GregorianUTCDateTimeSpecifier specifier);

GregorianUTCDateTimeSpecifier handles the complex arguments in constructing the DateTime.

GregorianUTCDateTimeSpecifier Example

GregorianUTCDateTime.GregorianUTCDateTimeSpecifier specifier = new GregorianUTCDateTime.GregorianUTCDateTimeSpecifier();
 
specifier.setYear(2013);
specifier.setMonth(10);
specifier.setDay(30)
 
DateTime game6 = new GregorianUTCDateTime(specifier);

The specifier will assume the granularity of the more granular level set, otherwise it can be manually overridden.

Static Factories

From an ISO String

    /**
     *  Parses an ISO 8601 date string.
     *
     *  @param iso the iso formatted string
     *  @return a Gregorian/UTC DateTime
     *  @throws org.osid.InvalidArgumentException could not parse iso
     *  @throws org.osid.NullArgumentException iso is null
     */
 
public static org.osid.calendaring.DateTime valueOf(String iso);

The formats of the date string is:

YYYY
YYYY-MM
YYYY-MM-DD
YYYY-MM-DDThhZ
YYYY-MM-DDThh:mmZ
YYYY-MM-DDThh:mm:ssZ
YYYY-MM-DDThh-mm:ss.<fraction of a second>Z

The year may be precede by a + or - to indicate A.D or B.C. The granularity will be assumed based on how many of the date components were specified, but it is not possible to construct dates in this way with granularities less than a YEAR. The time zone designator (Z) is required but only UTC is supported.

From a Java Date

    /**
     *  Converts a Java Date to a DateTime using millisecond granularity.
     *
     *  @param date a Java Date
     *  @return a Gregorian/UTC DateTime
     *  @throws org.osid.NullArgumentException date is null
     */

    public static org.osid.calendaring.DateTime valueOf(java.util.Date date);

This is a simple conversion from a Java Date to an OSID DateTime. If the desired granularity is not a MILLISECOND, the following can be used instead.

From a Java Date With Granularity

    /**
     *  Converts a Java Date to a DateTime using millisecond granularity.
     *
     *  @param date a Java Date
     *  @param granularity the clock resolution
     *  @return a Gregorian/UTC DateTime
     *  @throws org.osid.NullArgumentException date or granularity is null
     */

    public static org.osid.calendaring.DateTime valueOf(java.util.Date date, DateTimeResolution granularity);

Similar methods exist for conversions from Java Calendar.

From a Java Calendar

    /**
     *  Converts a Java Calendar to a DateTime using millisecond granularity.
     *
     *  @param calendar a Java Date
     *  @return a Gregorian/UTC DateTime
     *  @throws org.osid.NullArgumentException calendar is null
     */

    public static org.osid.calendaring.DateTime valueOf(java.util.Calendar calendar);
 
    /**
     *  Converts a Java Calendar to a DateTime using millisecond granularity.
     *
     *  @param calendar a Java Calendar
     *  @param granularity the clock resolution
     *  @return a Gregorian/UTC DateTime
     *  @throws org.osid.NullArgumentException calendar or granularity is null
     */

    public static org.osid.calendaring.DateTime valueOf(java.util.Calendar calendar, DateTimeResolution granularity);

To get the current timestamp in the DateTime:

    /**
     *  Gets the datetime as of right now.
     *
     *  @return a current Gregorian/UTC DateTime
     */

    public static org.osid.calendaring.DateTime now();

and finally to easily say "I don't know" for those pesky required OSID methods:

    /**
     *  Gets an unknown date.
     *
     *  @return an unknown date
     */

    public static org.osid.calendaring.DateTime unknown()

Serialization

toString() will produce the same ISO-like output that can be parsed by valueOf().

Comparison Methods

isGreater(org.osid.calendaring.DateTime d)
isLess(org.osid.calendaring.DateTime d)
isInclusive(org.osid.calendaring.DateTime d)
isExclusive(org.osid.calendaring.DateTime d)

Each of the above methods compares another DateTime of the same calendar and time Type. The granularity of the DateTime implies a range of the dates which is reflected in the comparisons. This behavior is specified by the OSID Java Binder.

this	external DateTime	isGreater()	isLess()	isInclusive()	isExclusive()
2010-01-01	2011-01-01	F	T	F	T
2010	2010-06-06	F	F	T	F
2010-06-06	2010	F	F	F	F
2010-12-31	2010-12-30	T	F	F	T

Equality

Two DateTimes are equal if their calendar & time types, values within their respective granularities, and uncertainties are also equal.

Caveats

Uncertainties are not currently taken into account for the comparison methods.

From the Soap Box

Magic Calendars

On most computer systems, the calendar jumps from September 3 to September 14, 1752. We didn't lose them and September had a full 30 days that year. This happens to be the date when the Calendaring Act of 1750 went into effect changing both the calendar, from Julian to Gregorian (with better leap year correction), and moving the start of the new year to January 1. This only applied to Great Britain and her colonies. Both of these changes occurred independently for many countries at different times.

The OSID DateTime is of a single calendar Type. Creating Gregorian dates in 1930 or 1630 are always placed on the Gregorian Calendar. A calendar is a system and it can go backward and forward through time. A Julian Calendar would be a different calendar Type, and should one be created, would go forward all the way through to the Red Sox victories of modern times.

A DateTime is simply an instance of time. It communicates whatever you feed it, including September 10, 1752.

That 70's Show

A timestamp is a number of clock ticks from a known point in time. While timestamps are fine when recording transactions, they fall short in applications where the dates and times are manually entered or fed from other sources after the fact. They might even pertain to events long before there were modern computer databases.

The DateTime interface is a communication vehicle. It communicates what is, and more importantly, what isn't known about a Date and Time. If all we know is the day an event took place, it shouldn't be implied that it must have occurred at midnight. If all we know is the year, it probably didn't happen on January 1. Or perhaps that was quite a New Year's party.

Granularity captures what is relevant. Graduates from the class of 1918 were awarded degrees on June 3, but the minutes and seconds of the day are irrelevant. Uncertainty captures what isn't known. A photograph taken circa 1908 (let's say uncertainty +/-1 year) might be apropos for a listing in the "photographs of 1909" search results.

DateTime is just a communication vehicle with some bells, whistles, and too many late nights. Convert it to whatever you want but (just keep in mind that the range on the thing is very very large and someone send you some DateTimes from the "big freeze" – it could happen).