Java-Time Clock Implementation Note

[Stephen Colebourne]

Its not terrible, but I think confusing enough it should be fixed.

Maybe:
"The clock implementation provided here is based on the same
underlying clock as System.currentTimeMillis(), but may have a
precision finer
than milliseconds if available. However, little to no guarantee is
provided about the accuracy of the underlying clock. Applications
requiring a more accurate clock must implement this abstract class
themselves using a different external clock, such as an NTP server."

Stephen



On 16 May 2017 at 11:59, Daniel Fuchs <daniel.fuchs at oracle.com> wrote:
> Hi Stephen,
>
> Thanks for pointing that out.
>
> On 16/05/2017 11:27, Stephen Colebourne wrote:
>>
>> In JDK 9, the implementation of Clock has been improved to be better
>> than millisecond in most cases [1]. However, I've just noticed that
>> the Javadoc of the "Implementation Note" is now wrong. It says:
>>
>> "The clock implementation provided here is based on
>> System.currentTimeMillis(). That method provides little to no
>> guarantee about the accuracy of the clock. Applications requiring a
>> more accurate clock must implement this abstract class themselves
>> using a different external clock, such as an NTP server."
>>
>> This needs to be updated to indicate that the implementation is no
>> longer based on System.currentTimeMillis(). Since this is an
>> "implementation note" I hope that this doesn't affect the
>> specification, or need too much process.
>
>
> Strictly speaking the implementation is based on the *same* clock
> than System.currentTimeMillis() is based on. This is very important
> as it means that times obtained by System.currentTimeMillis() and
> times obtained by the system clock are consistent with each other.
>
> So I am not sure the note [2] is actually wrong?
>
> Would the following be a better wording (syntax/grammar may need
> correction)?
>
> <<
> The clock implementation provided here is based on the same clock than
> System.currentTimeMillis() is based on, but may have a precision finer
> than milliseconds if provided by the underlying clock.
> However, little to no guarantee is provided about the accuracy of the
> underlying clock. Applications requiring a more accurate clock must
> implement this abstract class themselves using a different external clock,
> such as an NTP server.
>>>
>
> best regards,
>
> -- daniel
>
> [2] http://download.java.net/java/jdk9/docs/api/java/time/Clock.html
>
>
>
>
>>
>> Is anyone willing to take this up as a JDK 9 bug?
>>
>> thanks
>> Stephen
>>
>> [1] https://bugs.openjdk.java.net/browse/JDK-8068730
>>
>