RFR: 8241619: (fs) Files.newByteChannel(path, Set.of(CREATE_NEW, READ)) does not throw a FileAlreadyExistsException when the file exists

[Alan Bateman]

On Fri, 12 Mar 2021 22:38:05 GMT, Brian Burkhalter <bpb at openjdk.org> wrote:

> Please consider this proposal to add `@throws FileAlreadyExistsException` or modify an existing such throws clause's description in a number of methods in `java.nio.file.Files`, `java.nio.file.spi.FileSystemProvider`, and `java.nio.channels.FileChannel`. The methods affected are `open()` in `FileChannel` and various `new*()` methods in `Files` and `FileSystemProvider`. The `Files.newByteChannel()` methods already documented this exception so this would bring the other methods in line.
> 
> A `FileAlreadyExistsException` is an optional specific exception, i.e., a subclass of `IOException` intended to provide a more precise description of the error. The package specification of `java.nio.file` describes optional specific exceptions but those of the other two packages do not. If these exceptions are to be added to the `FileChannel` and `FileSystemProvider` classes, then perhaps a similar paragraph (or a link) should be added to their respective package specifications as well.
> 
> The change to `java.nio.channels.AsynchronousFileChannel` is an incidental correction.

Are you planning to link the use of "optional specific exception" in FileChannel to the section in the java.nio.file package description? Also if we are adding optional specific exceptions to FileChannel.open then we'll have to do the same for AsynchronousFileChannel.open.

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

PR: https://git.openjdk.java.net/jdk/pull/2980