MumbleCloseable

[Doug Lea]

On 06/28/13 17:59, Brian Goetz wrote:

> Here's the current draft spec for interface and annotation.

Pasted below is version after an edit pass between Brian and me.

> Bikeshed opportunity: should the annotation be nested or at top level?

I think nested, but if so, it seems cruel to give it such a long name:

@MayHoldCloseableResource.DefinitelyHoldsCloseableResource

So the remaining bikeshed opportunity is what's shorter
but still crystal-clear? We probably can't get away with
just:

@MayHoldCloseableResource.Yes

Any ideas?

...

/**
  * An object that may (but need not) hold one or more references to
  * resources that will be released when closed.  Such objects may be
  * used with try-with-resources or related {@code try...finally}
  * constructions that ensure they are closed as soon as they are no
  * longer needed.  Interface MayHoldCloseableResource indicates that
  * only a minority of usages warrant resource control constructions:
  * those specialized to known resource-bearing instances, or those
  * that must operate in complete generality.
  *
  * <p>For example, most usages of the {@link java.util.stream.Stream}
  * classes operate on data sources such as an array, {@code
  * Collection}, or generator function that do not require or benefit
  * from explicit resource control.  However, some uses of IO channels
  * as data sources do -- a stream operation that opens many files may
  * exhaust available system resources unless each is closed promptly,
  * rather than waiting for them to be garbage collected.
  *
  * <p>Annotation {@code DefinitelyHoldsCloseableResource} may be used
  * to guide users deciding whether resource-control constructions are
  * warranted when using particular implementations of
  * MayHoldCloseableResource.
  */
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 { }
}