JDK 9 RFR - 8031142 [was: Re: Using @implSpec in AbstractMap, AbstractCollection, AbstractList, etc]

[Mike Duigou]

If you navigate through http://cr.openjdk.java.net/~chegar/8031142/specdiff/java/util/package-summary.html it shows just the relevant diffs. It appears that the specdiff was generated without an explicit --includes option which results in all the extra chaff.

Mike

On Jan 6 2014, at 09:05 , Martin Buchholz <martinrb at google.com> wrote:

> 
> 
> 
> On Mon, Jan 6, 2014 at 8:47 AM, Chris Hegarty <chris.hegarty at oracle.com> wrote:
> Part 2...
> 
> JDK 9 RFR - 8031142: AbstractCollection and AbstractList should specify their default implementation using @implSpec
> 
> http://cr.openjdk.java.net/~chegar/8031142/webrev/
> http://cr.openjdk.java.net/~chegar/8031142/specdiff/
> 
> Is that specdiff link what you want?  I just get a giant tree with javax files in it...
>  
> ---
> 
> In a sane language, the AbstractFoo classes would be traits - they should never contribute to the *specification* of a concrete class, only to its implementation.  Therefore,  in Java, all of the methods should have precisely an {@inheritDoc} followed by an @implSpec.  In particular, for AbstractCollection.toArray I see:
> 
>  114     /**
>  115      * {@inheritDoc}
>  116      *
>  117      * <p>This method is equivalent to:
>  118      *
>  119      *  <pre> {@code
>  120      * List<E> list = new ArrayList<E>(size());
>  121      * for (E e : this)
>  122      *     list.add(e);
>  123      * return list.toArray();
>  124      * }</pre>
>  125      *
>  126      * @implSpec
>  127      * This implementation returns an array containing all the elements
>  128      * returned by this collection's iterator, in the same order, stored in
>  129      * consecutive elements of the array, starting with index {@code 0}.
>  130      * The length of the returned array is equal to the number of elements
>  131      * returned by the iterator, even if the size of this collection changes
>  132      * during iteration, as might happen if the collection permits
>  133      * concurrent modification during iteration.  The {@code size} method is
>  134      * called only as an optimization hint; the correct result is returned
>  135      * even if the iterator returns a different number of elements.
>  136      */
>  137     public Object[] toArray() {
> 
> which must be wrong.  Either the sample code should be moved into the @implSpec or promoted to Collection.java.toArray.  The introduction of default methods ("not quite traits") makes the situation murkier.  Looking more closely, the exact wording cannot be promoted to Collection.java because the behavior may in fact differ from the code sample.  size() may or may not be called.  toArray implementation is more likely to be atomic, etc...  So move it into the @implSpec somehow...