Discontinue use of java.util.Date


This issue is actually reported by Adrian Custer, edited by Martin Desruisseaux:

The type java.util.Date is unsuitable to represent the data structures required by the ISO 19103 Date and ISO 19103 Time types. ISO 19103 says: (p15, 19103:2005-07-15)

A date gives values for year, month, and day. ... Character encoding of a date is a string that shall follow the format for date specified in ISO 8601.

A time is given by an hour, minute and second. ... Character encoding of a time is a string that follows the ISO 8601 format.</blockquote>

The Java source code documentation for java.util.Date says:

The class java.util.Date represents a specific instant in time, with millisecond precision.</blockquote>

Semantically, these objects have different roles and functions. The ISO data types embody representations of time whereas the Java type embodies a particular temporal moment. While it is possible to represent January 1955 with the ISO types, with the Java type one can only represent the first millisecond of January 1955. Even worse, it is simply impossible with java.util.Date to represent the ISO time 16:20 &#8212; java.util.Date can only represent a four twenty on a particular day. The Java type java.util.Date is simply unsuitable for this task as we have discovered recently.

The misnaming and misuse of java.util.Date have long been recognized in the Java community so that not reusing the simple object from the Java standard library will not prove particularly surprising to programmers. Many have moved on to use the java.util.Calendar data structure or to use the objects from the Joda time library.

ISO 19108 (Temporal Schema) defines TM_CalDate and TM_ClockTime. The are implemented in the pending section of GeoAPI as the CalendarDate and ClockTime interfaces respectively, both of them in the org.opengis.temporal package. We could use the ISO 19108 CalendarDate or DateAndTime object as a replacement of ISO 19103 Date, instead than java.util.Date. Actually, the description of date and time in ISO 19103 refers explicitly to ISO 19108 with the statement "Principles for date and time are further discussed in ISO 19108".

However it is too late for including the temporal schema in the GeoAPI 3.0 release. But we could include an empty placeholder for CalendarDate with a Javadoc saying that this interface will be expanded in a future GeoAPI release. This is the approach already taken for the ISO 19107 Geometry object. The inconvenient is that user will have to cast CalendarDate to whatever implementation class they use, until the temporal schema is included in an official GeoAPI release.

See the "GeoAPI public comments" PDF document in [https://jira.codehaus.org/browse/GEO-188" title="Comments from the GeoAPI public review" class="issue-link" data-issue-key="GEO-188"><del>GEO-188</del> for a list of method to change.