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. ------------- Commit messages: - Add @implNote's regarding close() invoking itself reentrantly. Changes: https://git.openjdk.org/jdk/pull/13379/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=13379&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8291023 Stats: 15 lines in 3 files changed: 15 ins; 0 del; 0 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
