Summary

Clarify that read permission is not checked in java.nio.file.Files::isSameFile and java.nio.file.Files::mismatch when the paths are equal.

Problem

It is not made clear that no security exception is possible in Files::isSameFile and Files::mismatch when the path parameters are equal.

Solution

Add some verbiage to make it clear that no security exception for read permission will be thrown if the paths are equal.

Specification

--- a/src/java.base/share/classes/java/nio/file/Files.java
+++ b/src/java.base/share/classes/java/nio/file/Files.java
@@ -1531,7 +1531,8 @@ public static FileStore getFileStore(Path path) throws IOException {
      * @throws  SecurityException
      *          In the case of the default provider, and a security manager is
      *          installed, the {@link SecurityManager#checkRead(String) checkRead}
-     *          method is invoked to check read access to both files.
+     *          method is invoked to check read access to both files when the
+     *          two paths are not equal
      *
      * @see java.nio.file.attribute.BasicFileAttributes#fileKey
      */
@@ -1571,6 +1572,9 @@ public static boolean isSameFile(Path path, Path path2) throws IOException {
      * and {@code g}, {@code mismatch(f,g)} will return the same value as
      * {@code mismatch(g,f)}).
      *
+     * <p> If both {@code Path} objects are equal, then this method returns
+     * {@code true} without checking if the file exists.
+     *
      * @param   path
      *          the path to the first file
      * @param   path2
@@ -1583,7 +1587,8 @@ public static boolean isSameFile(Path path, Path path2) throws IOException {
      * @throws  SecurityException
      *          In the case of the default provider, and a security manager is
      *          installed, the {@link SecurityManager#checkRead(String) checkRead}
-     *          method is invoked to check read access to both files.
+     *          method is invoked to check read access to both files when the
+     *          two paths are not equal
      *
      * @since 12
      */