MumbleCloseable

[Remi Forax]

On 07/11/2013 07:29 PM, Brian Goetz wrote:
> 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?

Remove the annotation and MayHoldCloseableResource and document in 
Stream that Stream doesn't follow the strict semantics of AutoCloseable.
It will be enough for static analysis tools for 8 and post pone the 
inclusion of MayHoldCloseableResource in 9.

Rémi

>
> 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 { }
>> }
>>