Revisiting MayHoldCloseableResource

[Doug Lea]

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