MumbleCloseable

[Brian Goetz]

On 6/25/2013 10:55 AM, Doug Lea wrote:

> I like the idea of an construction saying that "implementations
> of this type may hold resources, and if so you should use them
> with try-with-resources". Too bad that none of the obvious/simple
> ways to do this work. But of the less obvious approaches,
> creating a type "PossiblyHoldsResourcesUntilClosed" seems to be
> one part of solution. I think that to be useful, there should
> also be an annotation @HoldsResourcesUntilClosed that can
> be placed on those implementation classes etc that do
> in general want to be used with TWR, so IDEs and tools can help
> people do the right thing.

Here's the current draft spec for interface and annotation.  Bikeshed 
opportunity: should the annotation be nested or at top level?

/**
  * An object that may, or may not, hold a reference to a resource that 
should be
  * closed when it is no longer needed.  Such objects always <em>may</em> be
  * closed safely, and may be used with try-with-resources, but users 
may want to
  * omit resource release code when they know that no such resource is held.
  *
  * <p>For example, the {@link java.util.stream.Stream} classes may have 
as their
  * data source an array, {@code Collection}, generator function, IO 
channel,
  * etc.  Most of these do not hold resources requiring closing, so in those
  * common cases, no additional resource management code is needed when 
executing
  * a stream operation.  Since handling resource release requires users to
  * restructure their code, users who know it is unnecessary (for 
example, when
  * the source is an array or collection) may use this knowledge to omit
  * resource-release code.
  *
  * <p>Static analysis tools should not treat failure to close a
  * {@code MayHoldCloseableResource} as indicating a potential problem, 
unless
  * they can further prove that it <em>does</em> in fact hold a reference to
  * a resource that requires closing.
  */
public interface MayHoldCloseableResource extends AutoCloseable {
     /**
      * Closes this resource, relinquishing any underlying resources.
      * This method is invoked automatically on objects managed by the
      * {@code try}-with-resources statement.
      *
      * Implementers of this interface are strongly encouraged
      * to make their {@code close} methods idempotent.
      *
      * @see AutoCloseable#close()
      */
     @Override
     void close();

     /**
      * Indicates that a variable holding a {@code 
MayHoldCloseableResource} or
      * a method returning a {@code MayHoldCloseableResource} definitely 
does
      * hold a closeable resource.
      */
     @Retention(RetentionPolicy.CLASS)
     @Documented
     @Target({ElementType.FIELD, ElementType.LOCAL_VARIABLE, 
ElementType.METHOD })
     @interface DefinitelyHoldsCloseableResource { }
}