Java-Time Clock Implementation Note

[Daniel Fuchs]

Thanks Stephen,

On 16/05/2017 15:32, Stephen Colebourne wrote:
> 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."

I like this. Let's turn it into a docs-only bug for JDK 9: we can
still fix those... I will log the issue - unless you prefer to do it?

best regards,

-- daniel

>
> 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
>>>
>>