Summary

Add a sentence to both java.io.File.listRoots() and java.nio.file.FileSystem.getRootDirectories() to make it clear that the root directories may not be accessible to programs.

Update the specification of File.listRoots() to move text about implementation to an "Implementation Note".

Problem

The specification of File.listRoots() and java.nio.file.FileSystem.getRootDirectories() may be misread and developers assume that Java APIs can access the root directories that are enumerated. There is no guarantee that this is possible.

Furthermore, some of the text in File.listRoots() is really an implementation note.

Solution

Update the specification of File.listRoots() and java.nio.file.FileSystem.getRootDirectories() to make it clear that the root directories may not be accessible.

Move implementation notes from Files.listRoot() an implNote section.

Specification

--- a/src/java.base/share/classes/java/io/File.java
+++ b/src/java.base/share/classes/java/io/File.java
@@ -1813,17 +1813,26 @@ public class File
      * <p> A particular Java platform may support zero or more
      * hierarchically-organized file systems.  Each file system has a
      * {@code root} directory from which all other files in that file system
-     * can be reached.  Windows platforms, for example, have a root directory
-     * for each active drive; UNIX platforms have a single root directory,
-     * namely {@code "/"}.  The set of available filesystem roots is affected
-     * by various system-level operations such as the insertion or ejection of
-     * removable media and the disconnecting or unmounting of physical or
-     * virtual disk drives.
+     * can be reached.
      *
      * <p> This method returns an array of {@code File} objects that denote the
      * root directories of the available filesystem roots.  It is guaranteed
      * that the canonical pathname of any file physically present on the local
      * machine will begin with one of the roots returned by this method.
+     * There is no guarantee that a root directory can be accessed.
+     *
+     * <p> Unlike most methods in this class, this method does not throw
+     * security exceptions.  If a security manager exists and its {@link
+     * SecurityManager#checkRead(String)} method denies read access to a
+     * particular root directory, then that directory will not appear in the
+     * result.
+     *
+     * @implNote
+     * Windows platforms, for example, have a root directory
+     * for each active drive; UNIX platforms have a single root directory,
+     * namely {@code "/"}.  The set of filesystem roots is affected
+     * by various system-level operations such as the disconnecting or
+     * unmounting of physical or virtual disk drives.
      *
      * <p> The canonical pathname of a file that resides on some other machine
      * and is accessed via a remote-filesystem protocol such as SMB or NFS may
@@ -1835,12 +1844,6 @@ public class File
      * platform will be returned by this method, while {@code File} objects
      * containing UNC pathnames will not be returned by this method.
      *
-     * <p> Unlike most methods in this class, this method does not throw
-     * security exceptions.  If a security manager exists and its {@link
-     * SecurityManager#checkRead(String)} method denies read access to a
-     * particular root directory, then that directory will not appear in the
-     * result.
-     *
      * @return  An array of {@code File} objects denoting the available
      *          filesystem roots, or {@code null} if the set of roots could not
      *          be determined.  The array will be empty if there are no

--- a/src/java.base/share/classes/java/nio/file/FileSystem.java
+++ b/src/java.base/share/classes/java/nio/file/FileSystem.java
@@ -178,7 +178,8 @@ public abstract class FileSystem
      * hierarchies may change during the lifetime of the Java virtual machine.
      * For example, in some implementations, the insertion of removable media
      * may result in the creation of a new file hierarchy with its own
-     * top-level directory.
+     * top-level directory. There is no guarantee that a root directory
+     * can be accessed.
      *
      * <p> When a security manager is installed, it is invoked to check access
      * to the each root directory. If denied, the root directory is not returned