diff --git a/src/share/classes/java/util/ArrayDeque.java b/src/share/classes/java/util/ArrayDeque.java index 0e20ffc52ef69f6206642196d9dc9abec53e5822..9e77f6dba5fbb9686f511690ebb4da73ce696eee 100644 --- a/src/share/classes/java/util/ArrayDeque.java +++ b/src/share/classes/java/util/ArrayDeque.java @@ -888,6 +888,19 @@ public class ArrayDeque extends AbstractCollection 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 --git a/src/share/classes/java/util/ArrayList.java b/src/share/classes/java/util/ArrayList.java index b7d5349cc00aadad262c6b123dff3f50071d283f..dae280dcde24f96c2904198258bbef6ef0a19dcc 100644 --- a/src/share/classes/java/util/ArrayList.java +++ b/src/share/classes/java/util/ArrayList.java @@ -1238,6 +1238,20 @@ public class ArrayList extends AbstractList } } + /** + * 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 --git a/src/share/classes/java/util/HashSet.java b/src/share/classes/java/util/HashSet.java index 002b80cbe6867ff9284c7f6b29c12dea64400522..6ab58d0edf8a65490f309da12380c33311aa12d4 100644 --- a/src/share/classes/java/util/HashSet.java +++ b/src/share/classes/java/util/HashSet.java @@ -312,6 +312,18 @@ public class HashSet } } + /** + * 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 --git a/src/share/classes/java/util/LinkedHashMap.java b/src/share/classes/java/util/LinkedHashMap.java index ee9c221ef1056a6902f673311a15d773899e38ca..feb1005b2aae4a41513c95ea6bb63c246ac067d1 100644 --- a/src/share/classes/java/util/LinkedHashMap.java +++ b/src/share/classes/java/util/LinkedHashMap.java @@ -129,10 +129,20 @@ import java.util.function.BiFunction; * 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 --git a/src/share/classes/java/util/LinkedHashSet.java b/src/share/classes/java/util/LinkedHashSet.java index c66015aac6f6bb3106cf770f5a3fb6a3a34cf620..08606cfe4cf378847af36ceaa42b1d85a713b9ab 100644 --- a/src/share/classes/java/util/LinkedHashSet.java +++ b/src/share/classes/java/util/LinkedHashSet.java @@ -170,13 +170,23 @@ public class LinkedHashSet } /** - * 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 --git a/src/share/classes/java/util/LinkedList.java b/src/share/classes/java/util/LinkedList.java index 4d0f6dbca92aab05a534bd026e35abe82db88368..6c0626b433f883139cb816940dcfb5a6b6f7e536 100644 --- a/src/share/classes/java/util/LinkedList.java +++ b/src/share/classes/java/util/LinkedList.java @@ -1149,6 +1149,23 @@ public class LinkedList 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 --git a/src/share/classes/java/util/List.java b/src/share/classes/java/util/List.java index 11104ab760ea9f156127dd44bfa082efd59834c8..65ad1404c38447c7101625463368ec02923ae76e 100644 --- a/src/share/classes/java/util/List.java +++ b/src/share/classes/java/util/List.java @@ -671,7 +671,7 @@ public interface List extends Collection { * 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 --git a/src/share/classes/java/util/PriorityQueue.java b/src/share/classes/java/util/PriorityQueue.java index 6a31f3ee292fecfe1ebf2b91e2362e0d37c94f65..645497530a7fe4bc69d8b3a6397f3058564f254b 100644 --- a/src/share/classes/java/util/PriorityQueue.java +++ b/src/share/classes/java/util/PriorityQueue.java @@ -795,6 +795,19 @@ public class PriorityQueue extends AbstractQueue 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 --git a/src/share/classes/java/util/Set.java b/src/share/classes/java/util/Set.java index 78da633f1da9d33de95a8e086cff996f8d00ee82..d47a06a4a8aad5523b36b5ad5ac75b48cc75a030 100644 --- a/src/share/classes/java/util/Set.java +++ b/src/share/classes/java/util/Set.java @@ -394,7 +394,7 @@ public interface Set extends Collection { * 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 --git a/src/share/classes/java/util/SortedSet.java b/src/share/classes/java/util/SortedSet.java index 367d775083fe23d7fb8ac3eb784b094a7ec0ef6b..3e64804e7b52b54b71e0276cdb65aad7b2a0be19 100644 --- a/src/share/classes/java/util/SortedSet.java +++ b/src/share/classes/java/util/SortedSet.java @@ -238,7 +238,7 @@ public interface SortedSet extends Set { * 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 --git a/src/share/classes/java/util/Spliterator.java b/src/share/classes/java/util/Spliterator.java index e3477cf7b7b834ee0d0111db5b182730057244c0..542aec76cdea248d35645cb53587b26f207d59c1 100644 --- a/src/share/classes/java/util/Spliterator.java +++ b/src/share/classes/java/util/Spliterator.java @@ -74,7 +74,11 @@ import java.util.function.LongConsumer; * 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 --git a/src/share/classes/java/util/TreeMap.java b/src/share/classes/java/util/TreeMap.java index 5c61d4f71eeca624dc86a3ebe4b860669d44b4f0..52d9df25a0b218e0e929927c5af951694a333796 100644 --- a/src/share/classes/java/util/TreeMap.java +++ b/src/share/classes/java/util/TreeMap.java @@ -790,8 +790,19 @@ public class TreeMap /** * 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 @@ public class TreeMap /** * 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 @@ public class TreeMap /** * 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 --git a/src/share/classes/java/util/TreeSet.java b/src/share/classes/java/util/TreeSet.java index 9484d5b87c7835faac31c89f2c810d8a06b05763..131de860f57510947dc6e27532748516e1730ad7 100644 --- a/src/share/classes/java/util/TreeSet.java +++ b/src/share/classes/java/util/TreeSet.java @@ -533,6 +533,25 @@ public class TreeSet extends AbstractSet 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 --git a/src/share/classes/java/util/Vector.java b/src/share/classes/java/util/Vector.java index 6146957dfd6f6cc8f62a32f1eba2d0919ffaf153..ef6540e59b0406d2c379e68074e91dc2b3831d2b 100644 --- a/src/share/classes/java/util/Vector.java +++ b/src/share/classes/java/util/Vector.java @@ -1323,6 +1323,19 @@ public class Vector 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);