XMLGregorianCalendar missing a schema-aware comparison function

[glassfishrobot]

Submitted by David Bau, entered by Joe Fialli

There is no schema-aware comparison function on the
XmlGregorianCalendar type. This is useful for validation, but it requires a
four-state (not a three-state) return value, because there is a "not equal
to" result defined by schema.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

[glassfishrobot]

Reported by @jfialli

[glassfishrobot]

@jfialli said:
Submitted by Dennis Sosnoski, entered by Joe Fialli.

The following needs to be reflected in the comparison operations on
XMLGregorianCalendar.

The comparison of dateTime values is specified that two dateTimes are equal if

• they both have time zones and the normalized (UTC) values are the same
• are both in unknown time zones with the same values.

[glassfishrobot]

@jfialli said:
Submitted by Dennis Sosnoski:

Also, the equals and hashcode methods need to be
implemented and use only the UTC time (not the zone) in order to
properly implement Schema

[glassfishrobot]

@jfialli said:
java.util.Calendar defines after and before methods. These methods need
to be overriden in XMLGregorianCalendar and updated to refer to implementing
order relation according to XSD Part 2, 3.2.7.3 Order relation on dateTime.
For ease of reference, here is the java.util.Calendar.before() javadoc. (after
is basically same wording)

public boolean before(Object when)

Compares the time field records. Equivalent to comparing result of
conversion to UTC.

Parameters:
when - the Calendar to be compared with this Calendar.
Returns:
true if the current time of this Calendar is before the time of Calendar
when; false otherwise.

Recommendation:
Update javadoc to state that method returns false if ordering is indeterminate.

---

Override equals to incorporate XSD Part 2, 3.2.7.3 "Order relation on dateTime"
impact on compare to XMLGregorianCalendar instances. Can one compare
a GregorianCalendar to XMLGregorianCalendar.

---

Issue to consider, is overriding these methods enough or
do we really need to add a comparison operator that implements XSD Part 2,
3.2.7.3 Order relation on dateTime and returns greater, lessthan, equal or
indeterminate.

[glassfishrobot]

@jfialli said:
Discussion at jsr222 eg meeting on 10/28/2003

I posed the question of whether Java programmers would be satisified with the
existing Calendar methods before, after and equals. Naturally, these methods
have to be updated in XMLGregorianCalendar to accomodate "indeterminate"
ordering described in XML Schema Part 2 spec Section on partial order relation
on xsd:dateTime.

Majority in expert group desired a method added to XMLGregorianCalendar
that returns on possible results for comparison of the partially order relation
on xsd:dateTime. Possible results are lessThan, greaterThan, equals and
indeterminate.

[glassfishrobot]

@jfialli said:
Table 1 below defines the mapping between the XSD calendar datatype fields
and the XMLGregorianCalendar field. Using this table and the algorithm
defined in XSD Part 2, Section 3.2.7.3 "Order relation on dateTime", the
schema aware comparator can be defined unambiguously in the javadoc.
Additionally, these mappings could be used to refine the definitions of
XMLGregorianCalendar methods after and before to reflect the Order
relation on dateTime.

Table 1: Calendar field mapping between XSD and Java representation

XSD XMLGregorianCalendar field
calendar
datatype field

---

year get(Calendar.YEAR) [+ getEon()] (or getYear())
month get(Calendar.MONTH)
day get(Calendar.DATE) (or get(Calendar.DAY_OF_MONTH))
hour get(Calendar.HOUR)
minute get(Calendar.MINUTE)
second get(Calendar.SECOND)
fractional second get(Calendar.MILLISECOND) [+ getFractionalSeconds()]
timezone

Note: Calendar fields that are not listed in this table have no
binding to XML Schema. For example, note that Calendar.DST_OFFSET
is omitted.

[glassfishrobot]

This issue was imported from java.net JIRA JSR222-3