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

[Jaikiran Pai]

On Wed, 19 Nov 2025 20:13:42 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: Change FAEE for CREATE_NEW cases

Hello Brian, the changes look reasonable to me.

Having said that, the JBS issue description states that the usage of the word "file" makes it sound like the exception is raised only if a regular file exists at the `Path`. Specifically, the previous wording was:

> If a file of that name already exists

and with the proposed change we now have:

> If the path locates an existing file

So, I think, that wording will still leave readers wondering whether existing directory at that `Path` are considered when throwing that exception. 

I am not proposing further changes though (I can't think of something that's more concise). `Files.exists(Path)` too uses the word "file":

> Tests whether a file exists.

and it checks even for directories, so I think it's all consistent with the rest of the API docs.

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

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