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

[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.

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

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

Changes: https://git.openjdk.java.net/jdk/pull/2980/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=2980&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8241619
  Stats: 53 lines in 4 files changed: 47 ins; 0 del; 6 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