RFR: 8305762: FileInputStream and FileOutputStream implSpec should be corrected or removed

[Alan Bateman]

On Tue, 11 Apr 2023 23:55:50 GMT, Brent Christian <bchristi at openjdk.org> wrote:

> With the removal of the AltFinalizer mechanism from `FileInputStream` and `FileOutputStream` in [JDK-8192939](https://bugs.openjdk.org/browse/JDK-8192939), this portion of the Implementation Requirement in the class JavaDoc is no longer true:
> 
>> If this FileOutputStream has been subclassed and the close() method has been overridden, the close() method will be called when the FileInputStream is unreachable."
> 
> The class doc, and the doc for close(), are updated to correctly reflect current behavior, and guidance for subclasses is clarified.

src/java.base/share/classes/java/io/FileInputStream.java line 45:

> 43:  * @apiNote
> 44:  * To release resources used by this stream {@link #close} should be called
> 45:  * directly or by try-with-resources.

I wonder if we should re-word the API note at the same time. I think it would be more readable to start with "The close method should be called ...".

src/java.base/share/classes/java/io/FileInputStream.java line 50:

> 48:  * Subclasses are responsible for the cleanup of resources acquired by the subclass.
> 49:  * Subclasses requiring that resource cleanup take place after a stream becomes
> 50:  * unreachable should use the {@link java.lang.ref.Cleaner} mechanism.

This is in the style of an API note for implementors so implSpec is appropriate here.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/13437#discussion_r1166446385
PR Review Comment: https://git.openjdk.org/jdk/pull/13437#discussion_r1166441998