Revisiting MayHoldCloseableResource

[Brian Goetz]

Improvement!  Iterating...

> /**
>   * An object that may hold resources (such as file or socket handles)
>   * until it is closed. The {@link #close()} method of an AutoCloseable
>   * object is called automatically when exiting a {@code
>   * try}-with-resources block for which the object has been declared in
>   * the header. This construction ensures prompt release, avoiding
>   * resource exhaustion exceptions and errors that may otherwise occur.
>   *
>   * @apiNote
>   * <p>It is possible, and in fact common, for a base class to
>   * implement AutoCloseable even though not all of its subclasses or
>   * instances hold releasable resources. It is best practice for usages
>   * applying to <em>any</em> possible subclass to use {@code
>   * try}-with-resources constructions.

I worry this can be too-easily misread as "it is best practice for any 
use of AutoCloseable to use try-with-resources".

How about:

For code that must operate in complete generality, or when it is 
statically known that the AutoCloseable instance does hold resources 
requiring release, it is recommended to use TWR constructions to ensure 
prompt resource release.  However ...

However, in frameworks such as
>   * {@link java.util.Stream} that support both IO-based and
>   * non-IO-based forms, {@code try}-with-resources blocks are in
>   * general unnecessary when using non-IO-based forms.
>   *
>   * @author Josh Bloch
>   * @since 1.7
>   */
> @FunctionalInterface
> public interface AutoCloseable {
>