JDK-8181334 : add spec for Deque.addAll
  • Type: Bug
  • Component: core-libs
  • Sub-Component: java.util:collections
  • Affected Version: 9
  • Priority: P3
  • Status: Closed
  • Resolution: Fixed
  • Submitted: 2017-05-31
  • Updated: 2017-07-18
  • Resolved: 2017-06-17
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 10 JDK 9
10Fixed 9 b175Fixed
Related Reports
Relates :  
JDK-8164793 - new ArrayDeque(2**N) allocates backing array of size 2**(N+1)
Relates :  
JDK-8181580 - No CCC for LinkedBlockingDeque#addAll
Relates :  
JDK-8167202 - ArrayDeque improvements
Description
ArrayDeque#addAll spec says:
Adds all of the elements in the specified collection at the end of this deque, as if by calling addLast(E) on each one, in the order that they are returned by the collection's iterator.

Because we feel that two below aspects of the aforementioned spec of overriding method are not mentioned in the super class spec  of overridden method and hence we believe this change requires a CCC  approval request and we noticed that there is no CCC request created.
1. calling addLast
2. in the order returned by the iterator

Overridden method in the base class (or super class) has the following specification from AbstractCollection#addAll (below) which does not confirm to overriding method spec because 
1.it does not mentions explicitly about the order of the given collectors iterator and
2.it does not state adding means adding elements at the end or calling add / addLast method.

AbstractCollection#addAll specification:

"Adds all of the elements in the specified collection to this collection (optional operation). The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (This implies that the behavior of this call is undefined if the specified collection is this collection, and this collection is nonempty.)"
Comments
The CCC request for this change has been approved.
16-06-2017
spec/docs only changes do not need to go through the JDK 9 approval process.
01-06-2017
OK, CCC's filed: 8167202 -- to cover ArrayDeque.addAll, retroactively 8181334 -- to cover the new Deque.addAll specification
31-05-2017
Since ArrayDeque is not capacity limited and only cares about null-ness of its elements, it's hardly worth including the paragraph about what happens if an exception is thrown in the middle. I'm happy enough with what we have in CVS. --- (we believe there is no user-visible change in behavior of ArrayDeque#addAll in jdk9)
31-05-2017
This should go into 9 so it'll have to go through the Oracle-internal legacy CCC system (as opposed to the open CSR, which is for Java SE 10 and later). I can handle this. The CCC request should cover spec changes relative to the previous release (Java 8). It looks like this is a new specification for Deque.addAll that supersedes having Deque inherit Collection.addAll as it did in 8. The ArrayDeque.addAll spec should conceptually inherit Deque.addAll, but the existing wording in JDK 9 master may need some adjustment. It doesn't need the "When using a capacity-restricted deque,..." paragraph, nor does it need the @throws tags for IllegalStateException, ClassCastException, or IllegalArgumentException. Should it have the paragraph that begins "An exception encountered while trying..." ? It seems like that would be a useful clause for ArrayDeque.addAll to include.
31-05-2017
The resolution to this issue is filing one or more retroactive ccc requests for the changes that have already been made in ArrayDeque using the exiting bug ids. In other words, do *not* file a ccc under the JDK-8181334 bug id. This bug should be closed once the ccc request(s) is filed.
31-05-2017
The spec for Deque is now checked in to CVS http://cr.openjdk.java.net/~martin/webrevs/openjdk10/jsr166-integration/addAll-spec/ Please help move this through CCC.
31-05-2017
/** * Adds all of the elements in the specified collection at the end * of this deque, as if by calling {@link #addLast} on each one, * in the order that they are returned by the collection's * iterator. * * <p>When using a capacity-restricted deque, it is generally preferable * to call {@link #offer(Object) offer} separately on each element. * * <p>An exception encountered while trying to add an element may result * in only some of the elements having been successfully added when * the associated exception is thrown. * * @param c the elements to be inserted into this deque * @return {@code true} if this deque changed as a result of the call * @throws IllegalStateException if not all the elements can be added at * this time due to insertion restrictions * @throws ClassCastException if the class of an element of the specified * collection prevents it from being added to this deque * @throws NullPointerException if the specified collection contains a * null element and this deque does not permit null elements, * or if the specified collection is null * @throws IllegalArgumentException if some property of an element of the * specified collection prevents it from being added to this deque */ boolean addAll(Collection<? extends E> c);
31-05-2017
The intent of the original change was just to implement addAll. But now I see that the Deque interface doesn't have any spec for addAll, and probably it should. Of course, since add is equivalent to addLast, users will expect that addAll will be equivalent to repeated addLast
31-05-2017
Related changeset is here: http://hg.openjdk.java.net/jdk9/jdk9/jdk/rev/a15610e000ba which includes fixes for 8167202: ArrayDeque improvements 8164793: new ArrayDeque(2**N) allocates backing array of size 2**(N+1)
31-05-2017