RFR: 8305748: Clarify reentrant behavior of close() in FileInputStream, FileOutputStream, and RandomAccessFile [v3]

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

  Address review comments.

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

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

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

  Stats: 11 lines in 3 files changed: 0 ins; 0 del; 11 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