RFR: 8220816: (fs) Files.createDirectory should make it more obvious that it fails when the directory already exists [v3]

[Alan Bateman]

On Tue, 18 Nov 2025 22:14:22 GMT, Brian Burkhalter <bpb at openjdk.org> wrote:

>> Slightly changes the specification of `Files.createDirectory` to highlight that it fails if a filesystem entity already exists at the given location.
>
> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
> 
>   8220816: Update throws verbiage to match

I think the `@throws FileAlreadyExistsException` description could be improved as "because a file of that name already exists" is too subtle. If we do change it then it will need to be done for all the methods that throw this exception, not just Files.createDirectory. What do you think of keeping it as simple as "If `dir` locates a file that already exists" ?

Files.createFile has "Creates a new and empty file, failing if the file already exists", which I think is clear. It's less easy to create a sentence for createDirectory, createSymbolicFile and other methods. "Creates a directory, failing if the file already exists" is accurate but might not be clear to everyone that "file" means any file (sym link, directory, ...). I wonder if we keep it to "Creates a directory, failing if `dir` locates an existing file".  I would be hesitate to using "file or directory" as proposed because that's just two of many cases.

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

PR Comment: https://git.openjdk.org/jdk/pull/28378#issuecomment-3551973453