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

[Brian Burkhalter]

On Fri, 7 Apr 2023 18:24:42 GMT, Archie L. Cobbs <duke at openjdk.org> wrote:

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

Marked as reviewed by bpb (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/13379#pullrequestreview-1377768106