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

[Martin Buchholz]

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...