# 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 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 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 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 {@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 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 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 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 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