JDK 9 doc-api-only RFR of 7086489: File.lastModified should accuracy as well as resolution

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

JDK 9 doc-api-only RFR of 7086489: File.lastModified should accuracy as well as resolution

Brian Burkhalter-2
Please review at your convenience.

Issue: https://bugs.openjdk.java.net/browse/JDK-7086489
Patch: [1]

Thanks,

Brian

[1] Hg mq diff

--- a/src/java.base/share/classes/java/io/File.java
+++ b/src/java.base/share/classes/java/io/File.java
@@ -923,6 +923,12 @@
      * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
      * Files.readAttributes} method may be used.
      *
+     * @implSpec While the unit of the returned value is milliseconds, this
+     * does not imply that its accuracy is to the millisecond as some platforms
+     * may truncate the last-modified time to a less accurate value. For
+     * example if the value were truncated to seconds, then the last three
+     * digits of the returned value would all be zero.
+     *
      * @return  A <code>long</code> value representing the time the file was
      *          last modified, measured in milliseconds since the epoch
      *          (00:00:00 GMT, January 1, 1970), or <code>0L</code> if the
Reply | Threaded
Open this post in threaded view
|

Re: JDK 9 doc-api-only RFR of 7086489: File.lastModified should accuracy as well as resolution

Stuart Marks
This is for JDK 9, right, so we want only non-normative doc changes?

I'd think this should be an @apiNote instead of @implSpec. The @apiNote
clarifies but doesn't change the semantics, whereas @implSpec can impose
requirements on the implementation and is thus normative.

The intent of the wording is correct, but I also think it's potentially
confusing, particularly regarding "truncation." If the time resolution (or
"granularity") in a particular file system is one second, the value returned is
converted from seconds to milliseconds and no truncation occurs. The "last three
digits...zero" assumes the value is expressed in decimal, which isn't incorrect,
but it seems to require more explanation to make sense. I'd leave it out.

For APIs with similar issues, see System.currentTimeMillis() and
System.nanoTime(). In particular, currentTimeMillis() says:

      * Returns the current time in milliseconds.  Note that
      * while the unit of time of the return value is a millisecond,
      * the granularity of the value depends on the underlying
      * operating system and may be larger.  For example, many
      * operating systems measure time in units of tens of
      * milliseconds.

I'm not sure "granularity" is the best term, but it seems OK. Maybe the best
thing to do would be to use this wording and adjust "operating system" to "file
system".

s'marks

On 5/17/17 12:16 PM, Brian Burkhalter wrote:

> Please review at your convenience.
>
> Issue: https://bugs.openjdk.java.net/browse/JDK-7086489
> Patch: [1]
>
> Thanks,
>
> Brian
>
> [1] Hg mq diff
>
> --- a/src/java.base/share/classes/java/io/File.java
> +++ b/src/java.base/share/classes/java/io/File.java
> @@ -923,6 +923,12 @@
>       * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
>       * Files.readAttributes} method may be used.
>       *
> +     * @implSpec While the unit of the returned value is milliseconds, this
> +     * does not imply that its accuracy is to the millisecond as some platforms
> +     * may truncate the last-modified time to a less accurate value. For
> +     * example if the value were truncated to seconds, then the last three
> +     * digits of the returned value would all be zero.
> +     *
>       * @return  A <code>long</code> value representing the time the file was
>       *          last modified, measured in milliseconds since the epoch
>       *          (00:00:00 GMT, January 1, 1970), or <code>0L</code> if the
>
Reply | Threaded
Open this post in threaded view
|

Re: JDK 9 doc-api-only RFR of 7086489: File.lastModified should accuracy as well as resolution

Brian Burkhalter-2
Hi Stuart,

Thanks for the careful reading and comments.

On May 17, 2017, at 1:15 PM, Stuart Marks <[hidden email]> wrote:

> This is for JDK 9, right, so we want only non-normative doc changes?
>
> I'd think this should be an @apiNote instead of @implSpec. The @apiNote clarifies but doesn't change the semantics, whereas @implSpec can impose requirements on the implementation and is thus normative.
>
> The intent of the wording is correct, but I also think it's potentially confusing, particularly regarding "truncation." If the time resolution (or "granularity") in a particular file system is one second, the value returned is converted from seconds to milliseconds and no truncation occurs. The "last three digits...zero" assumes the value is expressed in decimal, which isn't incorrect, but it seems to require more explanation to make sense. I'd leave it out.

Good points.

> For APIs with similar issues, see System.currentTimeMillis() and System.nanoTime(). In particular, currentTimeMillis() says:
>
>     * Returns the current time in milliseconds.  Note that
>     * while the unit of time of the return value is a millisecond,

This wording "the unit of time of the return value is a millisecond” sounds weird. I would have written "the unit of time of the return value is milliseconds.”

>     * the granularity of the value depends on the underlying
>     * operating system and may be larger.  For example, many
>     * operating systems measure time in units of tens of
>     * milliseconds.
>
> I'm not sure "granularity" is the best term, but it seems OK. Maybe the best thing to do would be to use this wording and adjust "operating system" to "file system".

How about then (ignore formatting)?

    * @apiNote
    * While the unit of time of the return value is milliseconds,
    * the granularity of the value depends on the underlying
    * file system and may be larger.  For example, some
    * file systems use time stamps in units of seconds.

Thanks,

Brian
Reply | Threaded
Open this post in threaded view
|

Re: JDK 9 doc-api-only RFR of 7086489: File.lastModified should accuracy as well as resolution

Stuart Marks
On 5/17/17 1:28 PM, Brian Burkhalter wrote:
> This wording "the unit of time of the return value is a millisecond” sounds
> weird. I would have written "the unit of time of the return value is
> milliseconds.”
OK.
> How about then (ignore formatting)?
>
>     * @apiNote
>     * While the unit of time of the return value is milliseconds,
>     * the granularity of the value depends on the underlying
>     * file system and may be larger.  For example, some
>     * file systems use time stamps in units of seconds.
This looks good! I trust you with the formatting. You can go ahead and push; I
don't need another review.

Thanks,

s'marks