Skip to content

8220816: (fs) Files.createDirectory should make it more obvious that it fails when the directory already exists #28378

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
+27 −23
Open

8220816: (fs) Files.createDirectory should make it more obvious that it fails when the directory already exists #28378

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4ab0ccb
8220816: (fs) Files.createDirectory should make it more obvious that …
bplb Nov 18, 2025
358bea7
8220816: "directory" -> "file or directory"
bplb Nov 18, 2025
3af3490
8220816: Update throws verbiage to match
bplb Nov 18, 2025
5c62cd5
8220816: Improve consistency per review comments
bplb Nov 19, 2025
9cf6ede
8220816: Address more review comments
bplb Nov 19, 2025
3684b8c
8220816: Change FAEE for CREATE_NEW cases
bplb Nov 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 17 additions & 13 deletions src/java.base/share/classes/java/nio/file/Files.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -575,7 +575,8 @@ public static DirectoryStream<Path> 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
Copy link
Contributor

@AlanBateman AlanBateman Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That works. I assume you'll re-flow this a bit to avoid "file. The" be on its own.

Copy link
Member Author

@bplb bplb Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume you'll re-flow this a bit

I left it that way intentionally to ease comparing the diffs in progress.

Copy link
Member Author

@bplb bplb Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 9cf6ede.

* 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.
Expand All @@ -598,7 +599,7 @@ public static DirectoryStream<Path> 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
* <i>(optional specific exception)</i>
* @throws IOException
* if an I/O error occurs or the parent directory does not exist
Expand All @@ -611,7 +612,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 {@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}
Expand All @@ -636,8 +638,8 @@ 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 <i>(optional specific exception)</i>
* if {@code dir} locates an existing file
* <i>(optional specific exception)</i>
* @throws IOException
* if an I/O error occurs or the parent directory does not exist
*/
Expand Down Expand Up @@ -676,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 <i>(optional specific
* exception)</i>
* if {@code dir} locates an existing file but is not a directory
Copy link
Contributor

@AlanBateman AlanBateman Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe "that is not a directory" might be better.

Copy link
Member Author

@bplb bplb Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 9cf6ede.

* <i>(optional specific exception)</i>
* @throws IOException
* if an I/O error occurs
*/
Expand Down Expand Up @@ -930,7 +932,8 @@ public static Path createTempDirectory(String prefix,
}

/**
* Creates a symbolic link to a target <i>(optional operation)</i>.
* Creates a symbolic link to a target, failing if {@code link} locates an
* existing file <i>(optional operation)</i>.
*
* <p> 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
Expand Down Expand Up @@ -964,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 <i>(optional specific
* exception)</i>
* if {@code link} locates an existing file
* <i>(optional specific exception)</i>
* @throws IOException
* if an I/O error occurs
*/
Expand All @@ -978,7 +981,8 @@ public static Path createSymbolicLink(Path link, Path target,
}

/**
* Creates a new link (directory entry) for an existing file <i>(optional
* Creates a new link (directory entry) for an existing file,
* failing if {@code link} locates an existing file <i>(optional
Copy link
Contributor

@AlanBateman AlanBateman Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor nit, I think the comment has got mis-aligned.

Copy link
Member Author

@bplb bplb Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 9cf6ede.

* operation)</i>.
*
* <p> The {@code link} parameter locates the directory entry to create.
Expand Down Expand Up @@ -1007,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 <i>(optional specific exception)</i>
* if {@code link} locates an existing file
* <i>(optional specific exception)</i>
* @throws IOException
* if an I/O error occurs
*/
Expand Down