This request for spec clarification was orginially filed on behalf of CLDC 1.1, but since CLDC follows the JLS, this request is to update the JLS first.

A test chanllenge for api/java_util/Calendar/index.html#GetTimeInMillis and api/java_util/Calendar/index.html#GetTime was submitted on the grounds that the spec should be updated to the fact that synchronizing getTime()/getTimeInMillis() with get(int) is
more important that returning the exact value passed to setTime(Date) or
setTimeInMillis(long).

The challenge was denied, and the licensee would like to see the documentation updated.


Details of the original test exclusion request:
This test verifies that the long value returned from Calendar.getTime()
precisely matches the value passed into Calendar.setTime(Date). The test
checks a variety of values, including Long.MIN_VALUE and Long.MAX_VALUE.

However, the specification for Calendar.setTime(Date) states:

> Note: Calling setTime() with Date(Long.MAX_VALUE) or
> Date(Long.MIN_VALUE) may yield incorrect field values from get().

While getTime() is not specifically mentioned in this caveat, it is clear
elsewhere in the Calendar specification that get() and getTime() are
related in that both express the Calendar's current time:

> getTime
>
> public final Date getTime()
>
> Gets this Calendar's current time.
>
> Returns:
> the current time.

> get
>
> public final int get(int field)
>
> Gets the value for a given time field.
>
> Parameters:
> field - the given time field (either YEAR, MONTH, DATE,
> DAY_OF_WEEK, HOUR_OF_DAY, HOUR, AM_PM, MINUTE, SECOND, or MILLISECOND
> Returns:
> the value for the given time field.

Ensuring that the value returned from getTime() matches the values
returned from get(int) is much more important than ensuring that getTime()
returns the same value set by setTime(new Date(Long.MAX_VALUE)) (or
MIN_VALUE). Thus, the exception in the setTime(Date) specification should
be implicitly extended to getTime(), and the test deemed invalid.

Similar argument for getTimeInMillis()
 Justification:
Javadocs should be updated for the next release.