8305748: Clarify reentrant behavior of close() in FileInputStream, FileOutputStream, and RandomAccessFile

Reviewed-by: alanb, bpb

src/java.base/share/classes/java/io/FileInputStream.java

@@ -493,6 +493,11 @@ public class FileInputStream extends InputStream
      * Subclasses requiring that resource cleanup take place after a stream becomes
      * unreachable should use the {@link java.lang.ref.Cleaner} mechanism.
      *
+     * <p>
+     * If this stream has an associated channel then this method will close the
+     * channel, which in turn will close this stream. Subclasses that override
+     * this method should be prepared to handle possible reentrant invocation.
+     *
      * @throws     IOException  {@inheritDoc}
      *
      * @revised 1.4

src/java.base/share/classes/java/io/FileOutputStream.java

@@ -386,6 +386,11 @@ public class FileOutputStream extends OutputStream
      * Subclasses requiring that resource cleanup take place after a stream becomes
      * unreachable should use the {@link java.lang.ref.Cleaner} mechanism.
      *
+     * <p>
+     * If this stream has an associated channel then this method will close the
+     * channel, which in turn will close this stream. Subclasses that override
+     * this method should be prepared to handle possible reentrant invocation.
+     *
      * @throws     IOException  if an I/O error occurs.
      *
      * @revised 1.4

src/java.base/share/classes/java/io/RandomAccessFile.java

@@ -697,6 +697,11 @@ public class RandomAccessFile implements DataOutput, DataInput, Closeable {
      * <p> If this file has an associated channel then the channel is closed
      * as well.
      *
+     * @apiNote
+     * If this stream has an associated channel then this method will close the
+     * channel, which in turn will close this stream. Subclasses that override
+     * this method should be prepared to handle possible reentrant invocation.
+     *
      * @throws     IOException  if an I/O error occurs.
      *
      * @revised 1.4