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

[Doug Lea]

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/
>>
> 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.
  *