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