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

[Brian Burkhalter]

> 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

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/2980/files
  - new: https://git.openjdk.java.net/jdk/pull/2980/files/d9417bde..324670e9

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=2980&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=2980&range=00-01

  Stats: 25 lines in 6 files changed: 6 ins; 0 del; 19 mod
  Patch: https://git.openjdk.java.net/jdk/pull/2980.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/2980/head:pull/2980

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