MumbleCloseable

[Brian Goetz]

A small wrinkle has emerged here; if you look at the Javadoc for Stream:

 
http://cr.openjdk.java.net/~briangoetz/doctmp/doc/java/util/stream/Stream.html

the nested annotation HoldsResource bleeds through into the Javadoc for 
any subtype of MHCR.  This is really leaky; this should not be 
considered a nested member, and its presence in the docs will be 
confusing to users of Stream, who will wonder "WTF is this?"

Options:
  - Kill the annotation for now, and revisit at a later time.  This 
deprives APIs of the ability to say "Hey, I really do return a 
resource-ful stream" and deprives static analysis tools of the ability 
to perform sharper inspections.  Since a Javadoc reboot is on the board 
for Java 9, we may be able to get finer control over doc generation like 
this in the future, making this a more useful tool for API designers, 
but right now, its pretty ugly.

  - Move the annotation to top level.  Would need a longer name, but 
that's probably OK as @HoldsCloseableResource is still shorter than 
@MayHoldCloseableResource.HoldsResource.  Crappy namespace management, 
but that's life in java.util.

  - Leave as is.

In order, my preferences are #2, #1, and #3.

Other opinions?

On 6/30/2013 9:32 AM, Doug Lea wrote:
> 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 { }
> }
>