RFR: 8214248: (fs) Files:mismatch spec clarifications

[Alan Bateman]

On Fri, 18 Aug 2023 23:11:43 GMT, Brian Burkhalter <bpb at openjdk.org> wrote:

> Clarify that `Files::mismatch` does not access the file system if both paths locate the same file. Add package documentation about file operations on directories being implementation specific.

src/java.base/share/classes/java/nio/file/Files.java line 1573:

> 1571:      * and {@code g}, {@code mismatch(f,g)} will return the same value as
> 1572:      * {@code mismatch(g,f)}). If both paths locate the same file, the file
> 1573:      * system is not accessed.

The only case where there is no file system access is when the paths are equal.

src/java.base/share/classes/java/nio/file/Files.java line 1588:

> 1586:      *          installed, the {@link SecurityManager#checkRead(String) checkRead}
> 1587:      *          method is invoked to check read access to both files unless both
> 1588:      *          paths locate the same file

This isn't quite right, the SM should be invoked when the paths are not equals.  I think the starting point is the SecurityException specified by isSameFile. It should says "... is invoked to check read access to both files when the two paths are not equal". The mismatch method will then follow with the same wording.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/15350#discussion_r1299241523
PR Review Comment: https://git.openjdk.org/jdk/pull/15350#discussion_r1299241339