RFR: 8022176: Weaken contract of java.lang.AutoCloseable

[Martin Buchholz]

Looks good, except there's one more IO that needs to be changed to I/O


On Sat, Aug 24, 2013 at 6:09 AM, Doug Lea <dl at cs.oswego.edu> wrote:

> On 08/24/2013 04:36 AM, Alan Bateman wrote:
>
>> On 23/08/2013 22:35, Henry Jen wrote:
>>
>>> Hi,
>>>
>>> Please review the javadoc spec change for AutoCloseable.
>>>
>>> Basically, it clarifies that AutoCloseable is to be automatically closed
>>> with try-with-resource construct, and the implementation may or may not
>>> hold resources that need to be closed.
>>>
>>> http://cr.openjdk.java.net/~**henryjen/ccc/8022176/webrev/<http://cr.openjdk.java.net/~henryjen/ccc/8022176/webrev/>
>>>
>>>  I realize this might be agreed wording but I wonder about the term
>> "header", shouldn't this be "resource specification"?
>>
>
> "resource specification", while accurate, looked confusing here.
> But we could include both terms, which seems like an improvement.
> See below.
>
>
>
>> A minor comment but maybe it should be "I/O" (rather than "IO") to be
>> consistent with the other javadoc.
>>
>
> Sure.
>
>
> /**
>  * An object that may hold resources (such as file or socket handles)
>  * until it is closed. The {@link #close()} method of an {@code
> AutoCloseable}
>  * object is called automatically when exiting a {@code
>  * try}-with-resources block for which the object has been declared in
>  * the resource specification 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 will hold releasable resources.  For code that must operate
>  * in complete generality, or when it is known that the {@code
> AutoCloseable}
>  * instance requires resource release, it is recommended to use {@code
>  * try}-with-resources constructions. However, when using facilities such
> as
>  * {@link java.util.stream.Stream} that support both I/O-based and
>  * non-IO-based forms, {@code try}-with-resources blocks are in
>  * general unnecessary when using non-I/O-based forms.
>  *
>