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

[Alan Bateman]

On Mon, 15 Mar 2021 19:02:32 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.
>
> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
> 
>   8241619: change "if" to "IF"; link optional specific exception doc

src/java.base/share/classes/java/nio/file/spi/package-info.java line 36:

> 34:  * java.lang.NullPointerException NullPointerException} to be thrown.  In some
> 35:  * cases methods which are specified to throw an {@code IOException} may throw
> 36:  * a more precise <a href="../file/package-summary.html#optspecex">optional

The terminology in the reference section is "optional specific exception" so it would be more consistent to continue with "specific" rather than switching to "precise" here. I'm in two minds about adding this to the java.nio.channels package description as it's only applicable to the static open methods defined by FileChannel and AsynchronousFileChannel.

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

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