RFR: 8291023: FileOutputStream.close() re-entrantly invokes itself via FileChannel.close() [v2]

[Archie L. Cobbs]

> IO stream classes like `FileOutputStream` can have assocated NIO channels.
> 
> When `close()` is invoked on one of these classes, it in turn invokes `close()` on the associated channel (if any). But when the associated channel's `close()` method is invoked, it in turn invokes `close()` on the associated stream (if any).
> 
> As a result, these IO stream `close()` methods invoke themselves reentrantly when there is an associated channel.
> 
> This is not a problem for these classes because they are written to handle this (i.e., they are idempotent), but it can be surprising (or worse, just silently bug-inducing) for subclasses that override `close()`.
> 
> There are two possible ways to address this:
> 1. Modify the code to detect and avoid the (unnecessary) reentrant invocations
> 2. Add a `@implNote` to the Javadoc so subclass implementers are made aware
> 
> This patch takes the second, more conservative approach.

Archie L. Cobbs has updated the pull request incrementally with one additional commit since the last revision:

  Apply Javadoc improvements suggested in review.

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/13379/files
  - new: https://git.openjdk.org/jdk/pull/13379/files/d3409a57..9978b52e

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=13379&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=13379&range=00-01

  Stats: 5 lines in 4 files changed: 1 ins; 0 del; 4 mod
  Patch: https://git.openjdk.org/jdk/pull/13379.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/13379/head:pull/13379

PR: https://git.openjdk.org/jdk/pull/13379