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

[Brian Burkhalter]

On Sun, 14 Mar 2021 17:19:06 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.
>
> src/java.base/share/classes/java/nio/channels/FileChannel.java line 277:
> 
>> 275:      *          StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified
>> 276:      *          and the file is being opened for writing
>> 277:      *          <i>(optional specific exception)</i>
> 
> This may be the first usage of optional specific exceptions in the java.nio.channels API docs. It's okay to do this but it will require linking to the java.nio.file package description where this is defined. You'll also need to import the exception or use the fully qualified class file here. Probably best to replace "if" with "If" to be consistent with the other exception messages here.

Thanks for adding the `nio` label. I had mentioned the package description already and will update that. There is not much consistency in whether the first letter of the `@throws` verbiage is upper case.

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

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