Revisiting MayHoldCloseableResource

[Joe Bowbeer]

Looks good to me.


On Tue, Aug 20, 2013 at 4:35 PM, Doug Lea <dl at cs.oswego.edu> wrote:

> On 08/20/2013 10:45 AM, Brian Goetz wrote:
>
>> Improvement!  Iterating...
>>
>
>  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 ...
>>
>
> This might be more straighforward changing "statically known" to
> just "known".
> Otherwise some people will be thinking that there is some static type
> that would tell them which kind they have, which there isn't.
>
> Leading to...
>
>
>
> /**
>  * 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. For usages applying to
>  * <em>any</em> possible subclass, or those applying to classes
>  * requiring resource release, it is best practice to use {@code
>  * try}-with-resources constructions. 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.
>  *
>
>