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

[Brian Burkhalter]

On Thu, 18 Mar 2021 08:52:33 GMT, Alan Bateman <alanb 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.

Added "optional specific exception" link to `FileChannel.open()` and `@throws FileAlreadyExistsException` to `AsynchronousFileChannel.open().

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

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