From 4ab0ccb88bef56f512878690d65fcf5cdda61460 Mon Sep 17 00:00:00 2001 From: Brian Burkhalter Date: Tue, 18 Nov 2025 09:38:12 -0800 Subject: [PATCH 1/6] 8220816: (fs) Files.createDirectory should make it more obvious that it fails when the directory already exists --- src/java.base/share/classes/java/nio/file/Files.java | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/java.base/share/classes/java/nio/file/Files.java b/src/java.base/share/classes/java/nio/file/Files.java index 80c771f53068c..d645c102aa7df 100644 --- a/src/java.base/share/classes/java/nio/file/Files.java +++ b/src/java.base/share/classes/java/nio/file/Files.java @@ -611,7 +611,8 @@ public static Path createFile(Path path, FileAttribute... attrs) } /** - * Creates a new directory. The check for the existence of the file and the + * Creates a new directory, failing if the directory already exists. + * The check for the existence of the file and the * creation of the directory if it does not exist are a single operation * that is atomic with respect to all other filesystem activities that might * affect the directory. The {@link #createDirectories createDirectories} From 358bea7df3b35f9e353bfcdbda5acc03ab71a984 Mon Sep 17 00:00:00 2001 From: Brian Burkhalter Date: Tue, 18 Nov 2025 09:48:35 -0800 Subject: [PATCH 2/6] 8220816: "directory" -> "file or directory" --- src/java.base/share/classes/java/nio/file/Files.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/java.base/share/classes/java/nio/file/Files.java b/src/java.base/share/classes/java/nio/file/Files.java index d645c102aa7df..7bb01768a4af4 100644 --- a/src/java.base/share/classes/java/nio/file/Files.java +++ b/src/java.base/share/classes/java/nio/file/Files.java @@ -611,7 +611,7 @@ public static Path createFile(Path path, FileAttribute... attrs) } /** - * Creates a new directory, failing if the directory already exists. + * Creates a new directory, failing if the file or directory already exists. * The check for the existence of the file and the * creation of the directory if it does not exist are a single operation * that is atomic with respect to all other filesystem activities that might From 3af3490337ed7b3f928a4abbc8bed3fc06f7bb0d Mon Sep 17 00:00:00 2001 From: Brian Burkhalter Date: Tue, 18 Nov 2025 14:08:52 -0800 Subject: [PATCH 3/6] 8220816: Update throws verbiage to match --- src/java.base/share/classes/java/nio/file/Files.java | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/java.base/share/classes/java/nio/file/Files.java b/src/java.base/share/classes/java/nio/file/Files.java index 7bb01768a4af4..ee34bd8f7fd88 100644 --- a/src/java.base/share/classes/java/nio/file/Files.java +++ b/src/java.base/share/classes/java/nio/file/Files.java @@ -637,8 +637,9 @@ public static Path createFile(Path path, FileAttribute... attrs) * if the array contains an attribute that cannot be set atomically * when creating the directory * @throws FileAlreadyExistsException - * if a directory could not otherwise be created because a file of - * that name already exists (optional specific exception) + * if a directory could not otherwise be created because a file or + * directory of that name already exists + * (optional specific exception) * @throws IOException * if an I/O error occurs or the parent directory does not exist */ From 5c62cd5f172717811a7d6d729a68721b7d75cbb8 Mon Sep 17 00:00:00 2001 From: Brian Burkhalter Date: Wed, 19 Nov 2025 09:36:01 -0800 Subject: [PATCH 4/6] 8220816: Improve consistency per review comments --- .../share/classes/java/nio/file/Files.java | 30 ++++++++++--------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/src/java.base/share/classes/java/nio/file/Files.java b/src/java.base/share/classes/java/nio/file/Files.java index ee34bd8f7fd88..0bc7eb2bb7d7e 100644 --- a/src/java.base/share/classes/java/nio/file/Files.java +++ b/src/java.base/share/classes/java/nio/file/Files.java @@ -575,7 +575,8 @@ public static DirectoryStream newDirectoryStream(Path dir, Set.of(StandardOpenOption.CREATE_NEW, StandardOpenOption.WRITE); /** - * Creates a new and empty file, failing if the file already exists. The + * Creates a new and empty file, failing if {@code path} locates an existing + * file. The * check for the existence of the file and the creation of the new file if * it does not exist are a single operation that is atomic with respect to * all other filesystem activities that might affect the directory. @@ -598,7 +599,7 @@ public static DirectoryStream newDirectoryStream(Path dir, * if the array contains an attribute that cannot be set atomically * when creating the file * @throws FileAlreadyExistsException - * If a file of that name already exists + * if {@code path} locates an existing file * (optional specific exception) * @throws IOException * if an I/O error occurs or the parent directory does not exist @@ -611,8 +612,8 @@ public static Path createFile(Path path, FileAttribute... attrs) } /** - * Creates a new directory, failing if the file or directory already exists. - * The check for the existence of the file and the + * Creates a new directory, failing if {@code dir} locates an existing + * file. The check for the existence of the file and the * creation of the directory if it does not exist are a single operation * that is atomic with respect to all other filesystem activities that might * affect the directory. The {@link #createDirectories createDirectories} @@ -637,8 +638,7 @@ public static Path createFile(Path path, FileAttribute... attrs) * if the array contains an attribute that cannot be set atomically * when creating the directory * @throws FileAlreadyExistsException - * if a directory could not otherwise be created because a file or - * directory of that name already exists + * if {@code dir} locates an existing file * (optional specific exception) * @throws IOException * if an I/O error occurs or the parent directory does not exist @@ -678,8 +678,8 @@ public static Path createDirectory(Path dir, FileAttribute... attrs) * if the array contains an attribute that cannot be set atomically * when creating the directory * @throws FileAlreadyExistsException - * if {@code dir} exists but is not a directory (optional specific - * exception) + * if {@code dir} locates an existing file but is not a directory + * (optional specific exception) * @throws IOException * if an I/O error occurs */ @@ -932,7 +932,8 @@ public static Path createTempDirectory(String prefix, } /** - * Creates a symbolic link to a target (optional operation). + * Creates a symbolic link to a target, failing if {@code link} locates an + * existing file (optional operation). * *

The {@code target} parameter is the target of the link. It may be an * {@link Path#isAbsolute absolute} or relative path and may not exist. When @@ -966,8 +967,8 @@ public static Path createTempDirectory(String prefix, * array contains an attribute that cannot be set atomically when * creating the symbolic link * @throws FileAlreadyExistsException - * if a file with the name already exists (optional specific - * exception) + * if {@code link} locates an existing file + * (optional specific exception) * @throws IOException * if an I/O error occurs */ @@ -980,7 +981,8 @@ public static Path createSymbolicLink(Path link, Path target, } /** - * Creates a new link (directory entry) for an existing file (optional + * Creates a new link (directory entry) for an existing file, + * failing if {@code link} locates an existing file (optional * operation). * *

The {@code link} parameter locates the directory entry to create. @@ -1009,8 +1011,8 @@ public static Path createSymbolicLink(Path link, Path target, * if the implementation does not support adding an existing file * to a directory * @throws FileAlreadyExistsException - * if the entry could not otherwise be created because a file of - * that name already exists (optional specific exception) + * if {@code link} locates an existing file + * (optional specific exception) * @throws IOException * if an I/O error occurs */ From 9cf6ede516cc863dfd22e52e6b357d5a0104cac1 Mon Sep 17 00:00:00 2001 From: Brian Burkhalter Date: Wed, 19 Nov 2025 11:12:43 -0800 Subject: [PATCH 5/6] 8220816: Address more review comments --- src/java.base/share/classes/java/nio/file/Files.java | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/java.base/share/classes/java/nio/file/Files.java b/src/java.base/share/classes/java/nio/file/Files.java index 0bc7eb2bb7d7e..7b12479f73b7e 100644 --- a/src/java.base/share/classes/java/nio/file/Files.java +++ b/src/java.base/share/classes/java/nio/file/Files.java @@ -576,10 +576,10 @@ public static DirectoryStream newDirectoryStream(Path dir, /** * Creates a new and empty file, failing if {@code path} locates an existing - * file. The - * check for the existence of the file and the creation of the new file if - * it does not exist are a single operation that is atomic with respect to - * all other filesystem activities that might affect the directory. + * file. The check for the existence of the file and the creation of the new + * file if it does not exist are a single operation that is atomic with + * respect to all other filesystem activities that might affect the + * directory. * *

The {@code attrs} parameter is optional {@link FileAttribute * file-attributes} to set atomically when creating the file. Each attribute @@ -678,7 +678,7 @@ public static Path createDirectory(Path dir, FileAttribute... attrs) * if the array contains an attribute that cannot be set atomically * when creating the directory * @throws FileAlreadyExistsException - * if {@code dir} locates an existing file but is not a directory + * if {@code dir} locates an existing file that is not a directory * (optional specific exception) * @throws IOException * if an I/O error occurs @@ -982,7 +982,7 @@ public static Path createSymbolicLink(Path link, Path target, /** * Creates a new link (directory entry) for an existing file, - * failing if {@code link} locates an existing file (optional + * failing if {@code link} locates an existing file (optional * operation). * *

The {@code link} parameter locates the directory entry to create. From 3684b8c78a834fab679dc9cd2770591b40d4d7fd Mon Sep 17 00:00:00 2001 From: Brian Burkhalter Date: Wed, 19 Nov 2025 12:06:14 -0800 Subject: [PATCH 6/6] 8220816: Change FAEE for CREATE_NEW cases --- .../share/classes/java/nio/file/Files.java | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/java.base/share/classes/java/nio/file/Files.java b/src/java.base/share/classes/java/nio/file/Files.java index 7b12479f73b7e..3f1d6fae4e4d9 100644 --- a/src/java.base/share/classes/java/nio/file/Files.java +++ b/src/java.base/share/classes/java/nio/file/Files.java @@ -203,7 +203,7 @@ public static InputStream newInputStream(Path path, OpenOption... options) * @throws UnsupportedOperationException * if an unsupported option is specified * @throws FileAlreadyExistsException - * If a file of that name already exists and the {@link + * If the path locates an existing file and the {@link * StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified * (optional specific exception) * @throws IOException @@ -340,7 +340,7 @@ public static OutputStream newOutputStream(Path path, OpenOption... options) * if an unsupported open option is specified or the array contains * attributes that cannot be set atomically when creating the file * @throws FileAlreadyExistsException - * If a file of that name already exists and the {@link + * If the path locates an existing file and the {@link * StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified * and the file is being opened for writing (optional specific * exception) @@ -377,7 +377,7 @@ public static SeekableByteChannel newByteChannel(Path path, * @throws UnsupportedOperationException * if an unsupported open option is specified * @throws FileAlreadyExistsException - * If a file of that name already exists and the {@link + * If the path locates an existing file and the {@link * StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified * and the file is being opened for writing (optional specific * exception) @@ -2715,7 +2715,7 @@ public static BufferedReader newBufferedReader(Path path) throws IOException { * @throws UnsupportedOperationException * if an unsupported option is specified * @throws FileAlreadyExistsException - * If a file of that name already exists and the {@link + * If the path locates an existing file and the {@link * StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified * (optional specific exception) * @@ -2758,7 +2758,7 @@ public static BufferedWriter newBufferedWriter(Path path, Charset cs, * @throws UnsupportedOperationException * if an unsupported option is specified * @throws FileAlreadyExistsException - * If a file of that name already exists and the {@link + * If the path locates an existing file and the {@link * StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified * (optional specific exception) * @@ -3165,7 +3165,7 @@ public static List readAllLines(Path path) throws IOException { * @throws UnsupportedOperationException * if an unsupported option is specified * @throws FileAlreadyExistsException - * If a file of that name already exists and the {@link + * If the path locates an existing file and the {@link * StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified * (optional specific exception) */ @@ -3226,7 +3226,7 @@ public static Path write(Path path, byte[] bytes, OpenOption... options) * @throws UnsupportedOperationException * if an unsupported option is specified * @throws FileAlreadyExistsException - * If a file of that name already exists and the {@link + * If the path locates an existing file and the {@link * StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified * (optional specific exception) */