# HG changeset patch # User psandoz # Date 1375795594 -3600 # Node ID 9d7530ff42cb8a3520ba908185b8a67dd7fafd60 # Parent 83132c40a5850d7cb666e4d56f0c7a561e7a784e 8014824: Document Spliterator characteristics and binding policy of java util collection impls Reviewed-by: chegar diff -r 83132c40a585 -r 9d7530ff42cb jdk/src/share/classes/java/util/ArrayDeque.java --- a/jdk/src/share/classes/java/util/ArrayDeque.java Mon Aug 19 11:04:21 2013 +0100 +++ b/jdk/src/share/classes/java/util/ArrayDeque.java Tue Aug 06 14:26:34 2013 +0100 @@ -888,6 +888,19 @@ elements[i] = s.readObject(); } + /** + * Creates a late-binding + * and fail-fast {@link Spliterator} over the elements in this + * deque. + * + *

The {@code Spliterator} reports {@link Spliterator#SIZED}, + * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and + * {@link Spliterator#NONNULL}. Overriding implementations should document + * the reporting of additional characteristic values. + * + * @return a {@code Spliterator} over the elements in this deque + * @since 1.8 + */ public Spliterator spliterator() { return new DeqSpliterator(this, -1, -1); } diff -r 83132c40a585 -r 9d7530ff42cb jdk/src/share/classes/java/util/ArrayList.java --- a/jdk/src/share/classes/java/util/ArrayList.java Mon Aug 19 11:04:21 2013 +0100 +++ b/jdk/src/share/classes/java/util/ArrayList.java Tue Aug 06 14:26:34 2013 +0100 @@ -1238,6 +1238,20 @@ } } + /** + * Creates a late-binding + * and fail-fast {@link Spliterator} over the elements in this + * list. + * + *

The {@code Spliterator} reports {@link Spliterator#SIZED}, + * {@link Spliterator#SUBSIZED}, and {@link Spliterator#ORDERED}. + * Overriding implementations should document the reporting of additional + * characteristic values. + * + * @return a {@code Spliterator} over the elements in this list + * @since 1.8 + */ + @Override public Spliterator spliterator() { return new ArrayListSpliterator<>(this, 0, -1, 0); } diff -r 83132c40a585 -r 9d7530ff42cb jdk/src/share/classes/java/util/HashSet.java --- a/jdk/src/share/classes/java/util/HashSet.java Mon Aug 19 11:04:21 2013 +0100 +++ b/jdk/src/share/classes/java/util/HashSet.java Tue Aug 06 14:26:34 2013 +0100 @@ -312,6 +312,18 @@ } } + /** + * Creates a late-binding + * and fail-fast {@link Spliterator} over the elements in this + * set. + * + *

The {@code Spliterator} reports {@link Spliterator#SIZED} and + * {@link Spliterator#DISTINCT}. Overriding implementations should document + * the reporting of additional characteristic values. + * + * @return a {@code Spliterator} over the elements in this set + * @since 1.8 + */ public Spliterator spliterator() { return new HashMap.KeySpliterator(map, 0, -1, 0, 0); } diff -r 83132c40a585 -r 9d7530ff42cb jdk/src/share/classes/java/util/LinkedHashMap.java --- a/jdk/src/share/classes/java/util/LinkedHashMap.java Mon Aug 19 11:04:21 2013 +0100 +++ b/jdk/src/share/classes/java/util/LinkedHashMap.java Tue Aug 06 14:26:34 2013 +0100 @@ -129,10 +129,20 @@ * exception for its correctness: the fail-fast behavior of iterators * should be used only to detect bugs. * + *

The spliterators returned by the spliterator method of the collections + * returned by all of this class's collection view methods are + * late-binding, + * fail-fast, and additionally report {@link Spliterator#ORDERED}. + * *

This class is a member of the * * Java Collections Framework. * + * @implNote + * The spliterators returned by the spliterator method of the collections + * returned by all of this class's collection view methods are created from + * the iterators of the corresponding collections. + * * @param the type of keys maintained by this map * @param the type of mapped values * diff -r 83132c40a585 -r 9d7530ff42cb jdk/src/share/classes/java/util/LinkedHashSet.java --- a/jdk/src/share/classes/java/util/LinkedHashSet.java Mon Aug 19 11:04:21 2013 +0100 +++ b/jdk/src/share/classes/java/util/LinkedHashSet.java Tue Aug 06 14:26:34 2013 +0100 @@ -170,13 +170,23 @@ } /** - * Creates a {@code Spliterator}, over the elements in this set, that - * reports {@code SIZED}, {@code DISTINCT} and {@code ORDERED}. - * Overriding implementations are expected to document if the - * {@code Spliterator} reports any additional and relevant characteristic - * values. + * Creates a late-binding + * and fail-fast {@code Spliterator} over the elements in this set. + * + *

The {@code Spliterator} reports {@link Spliterator#SIZED}, + * {@link Spliterator#DISTINCT}, and {@code ORDERED}. Implementations + * should document the reporting of additional characteristic values. + * + * @implNote + * The implementation creates a + * late-binding spliterator + * from the set's {@code Iterator}. The spliterator inherits the + * fail-fast properties of the set's iterator. + * The created {@code Spliterator} additionally reports + * {@link Spliterator#SUBSIZED}. * * @return a {@code Spliterator} over the elements in this set + * @since 1.8 */ @Override public Spliterator spliterator() { diff -r 83132c40a585 -r 9d7530ff42cb jdk/src/share/classes/java/util/LinkedList.java --- a/jdk/src/share/classes/java/util/LinkedList.java Mon Aug 19 11:04:21 2013 +0100 +++ b/jdk/src/share/classes/java/util/LinkedList.java Tue Aug 06 14:26:34 2013 +0100 @@ -1149,6 +1149,23 @@ linkLast((E)s.readObject()); } + /** + * Creates a late-binding + * and fail-fast {@link Spliterator} over the elements in this + * list. + * + *

The {@code Spliterator} reports {@link Spliterator#SIZED} and + * {@link Spliterator#ORDERED}. Overriding implementations should document + * the reporting of additional characteristic values. + * + * @implNote + * The {@code Spliterator} additionally reports {@link Spliterator#SUBSIZED} + * and implements {@code trySplit} to permit limited parallelism.. + * + * @return a {@code Spliterator} over the elements in this list + * @since 1.8 + */ + @Override public Spliterator spliterator() { return new LLSpliterator(this, -1, 0); } diff -r 83132c40a585 -r 9d7530ff42cb jdk/src/share/classes/java/util/List.java --- a/jdk/src/share/classes/java/util/List.java Mon Aug 19 11:04:21 2013 +0100 +++ b/jdk/src/share/classes/java/util/List.java Tue Aug 06 14:26:34 2013 +0100 @@ -671,7 +671,7 @@ * The default implementation creates a * late-binding spliterator * from the list's {@code Iterator}. The spliterator inherits the - * fail-fast properties of the collection's iterator. + * fail-fast properties of the list's iterator. * * @implNote * The created {@code Spliterator} additionally reports diff -r 83132c40a585 -r 9d7530ff42cb jdk/src/share/classes/java/util/PriorityQueue.java --- a/jdk/src/share/classes/java/util/PriorityQueue.java Mon Aug 19 11:04:21 2013 +0100 +++ b/jdk/src/share/classes/java/util/PriorityQueue.java Tue Aug 06 14:26:34 2013 +0100 @@ -795,6 +795,19 @@ heapify(); } + /** + * Creates a late-binding + * and fail-fast {@link Spliterator} over the elements in this + * queue. + * + *

The {@code Spliterator} reports {@link Spliterator#SIZED}, + * {@link Spliterator#SUBSIZED}, and {@link Spliterator#NONNULL}. + * Overriding implementations should document the reporting of additional + * characteristic values. + * + * @return a {@code Spliterator} over the elements in this queue + * @since 1.8 + */ public final Spliterator spliterator() { return new PriorityQueueSpliterator(this, 0, -1, 0); } diff -r 83132c40a585 -r 9d7530ff42cb jdk/src/share/classes/java/util/Set.java --- a/jdk/src/share/classes/java/util/Set.java Mon Aug 19 11:04:21 2013 +0100 +++ b/jdk/src/share/classes/java/util/Set.java Tue Aug 06 14:26:34 2013 +0100 @@ -394,7 +394,7 @@ * The default implementation creates a * late-binding spliterator * from the set's {@code Iterator}. The spliterator inherits the - * fail-fast properties of the collection's iterator. + * fail-fast properties of the set's iterator. * * @implNote * The created {@code Spliterator} additionally reports diff -r 83132c40a585 -r 9d7530ff42cb jdk/src/share/classes/java/util/SortedSet.java --- a/jdk/src/share/classes/java/util/SortedSet.java Mon Aug 19 11:04:21 2013 +0100 +++ b/jdk/src/share/classes/java/util/SortedSet.java Tue Aug 06 14:26:34 2013 +0100 @@ -238,7 +238,7 @@ * The default implementation creates a * late-binding spliterator * from the sorted set's {@code Iterator}. The spliterator inherits the - * fail-fast properties of the collection's iterator. The + * fail-fast properties of the set's iterator. The * spliterator's comparator is the same as the sorted set's comparator. * * @implNote diff -r 83132c40a585 -r 9d7530ff42cb jdk/src/share/classes/java/util/Spliterator.java --- a/jdk/src/share/classes/java/util/Spliterator.java Mon Aug 19 11:04:21 2013 +0100 +++ b/jdk/src/share/classes/java/util/Spliterator.java Tue Aug 06 14:26:34 2013 +0100 @@ -74,7 +74,11 @@ * source prior to binding are reflected when the Spliterator is traversed. * After binding a Spliterator should, on a best-effort basis, throw * {@link ConcurrentModificationException} if structural interference is - * detected. Spliterators that do this are called fail-fast. + * detected. Spliterators that do this are called fail-fast. The + * bulk traversal method ({@link #forEachRemaining forEachRemaining()}) of a + * Spliterator may optimize traversal and check for structural interference + * after all elements have been traversed, rather than checking per-element and + * failing immediately. * *

Spliterators can provide an estimate of the number of remaining elements * via the {@link #estimateSize} method. Ideally, as reflected in characteristic diff -r 83132c40a585 -r 9d7530ff42cb jdk/src/share/classes/java/util/TreeMap.java --- a/jdk/src/share/classes/java/util/TreeMap.java Mon Aug 19 11:04:21 2013 +0100 +++ b/jdk/src/share/classes/java/util/TreeMap.java Tue Aug 06 14:26:34 2013 +0100 @@ -790,8 +790,19 @@ /** * Returns a {@link Set} view of the keys contained in this map. - * The set's iterator returns the keys in ascending order. - * The set is backed by the map, so changes to the map are + * + *

The set's iterator returns the keys in ascending order. + * The set's spliterator is + * late-binding, + * fail-fast, and additionally reports {@link Spliterator#SORTED} + * and {@link Spliterator#ORDERED} with an encounter order that is ascending + * key order. The spliterator's comparator (see + * {@link java.util.Spliterator#getComparator()}) is {@code null} if + * the tree map's comparator (see {@link #comparator()}) is {@code null}. + * Otherwise, the spliterator's comparator is the same as or imposes the + * same total ordering as the tree map's comparator. + * + *

The set is backed by the map, so changes to the map are * reflected in the set, and vice-versa. If the map is modified * while an iteration over the set is in progress (except through * the iterator's own {@code remove} operation), the results of @@ -823,9 +834,15 @@ /** * Returns a {@link Collection} view of the values contained in this map. - * The collection's iterator returns the values in ascending order - * of the corresponding keys. - * The collection is backed by the map, so changes to the map are + * + *

The collection's iterator returns the values in ascending order + * of the corresponding keys. The collection's spliterator is + * late-binding, + * fail-fast, and additionally reports {@link Spliterator#ORDERED} + * with an encounter order that is ascending order of the corresponding + * keys. + * + *

The collection is backed by the map, so changes to the map are * reflected in the collection, and vice-versa. If the map is * modified while an iteration over the collection is in progress * (except through the iterator's own {@code remove} operation), @@ -843,8 +860,15 @@ /** * Returns a {@link Set} view of the mappings contained in this map. - * The set's iterator returns the entries in ascending key order. - * The set is backed by the map, so changes to the map are + * + *

The set's iterator returns the entries in ascending key order. The + * sets's spliterator is + * late-binding, + * fail-fast, and additionally reports {@link Spliterator#SORTED} and + * {@link Spliterator#ORDERED} with an encounter order that is ascending key + * order. + * + *

The set is backed by the map, so changes to the map are * reflected in the set, and vice-versa. If the map is modified * while an iteration over the set is in progress (except through * the iterator's own {@code remove} operation, or through the diff -r 83132c40a585 -r 9d7530ff42cb jdk/src/share/classes/java/util/TreeSet.java --- a/jdk/src/share/classes/java/util/TreeSet.java Mon Aug 19 11:04:21 2013 +0100 +++ b/jdk/src/share/classes/java/util/TreeSet.java Tue Aug 06 14:26:34 2013 +0100 @@ -533,6 +533,25 @@ tm.readTreeSet(size, s, PRESENT); } + /** + * Creates a late-binding + * and fail-fast {@link Spliterator} over the elements in this + * set. + * + *

The {@code Spliterator} reports {@link Spliterator#SIZED}, + * {@link Spliterator#DISTINCT}, {@link Spliterator#SORTED}, and + * {@link Spliterator#ORDERED}. Overriding implementations should document + * the reporting of additional characteristic values. + * + *

The spliterator's comparator (see + * {@link java.util.Spliterator#getComparator()}) is {@code null} if + * the tree set's comparator (see {@link #comparator()}) is {@code null}. + * Otherwise, the spliterator's comparator is the same as or imposes the + * same total ordering as the tree set's comparator. + * + * @return a {@code Spliterator} over the elements in this set + * @since 1.8 + */ public Spliterator spliterator() { return TreeMap.keySpliteratorFor(m); } diff -r 83132c40a585 -r 9d7530ff42cb jdk/src/share/classes/java/util/Vector.java --- a/jdk/src/share/classes/java/util/Vector.java Mon Aug 19 11:04:21 2013 +0100 +++ b/jdk/src/share/classes/java/util/Vector.java Tue Aug 06 14:26:34 2013 +0100 @@ -1323,6 +1323,19 @@ modCount++; } + /** + * Creates a late-binding + * and fail-fast {@link Spliterator} over the elements in this + * list. + * + *

The {@code Spliterator} reports {@link Spliterator#SIZED}, + * {@link Spliterator#SUBSIZED}, and {@link Spliterator#ORDERED}. + * Overriding implementations should document the reporting of additional + * characteristic values. + * + * @return a {@code Spliterator} over the elements in this list + * @since 1.8 + */ @Override public Spliterator spliterator() { return new VectorSpliterator<>(this, null, 0, -1, 0);