8141630: Specification of Collections.synchronized* need to state traversal constraints
Reviewed-by: psandoz
Contributed-by: Tagir Valeev <amaembo@gmail.com>
--- a/jdk/src/java.base/share/classes/java/util/Collections.java Wed Jul 05 20:59:28 2017 +0200
+++ b/jdk/src/java.base/share/classes/java/util/Collections.java Mon Nov 09 09:23:49 2015 +0100
@@ -2090,7 +2090,8 @@
* through the returned set.<p>
*
* It is imperative that the user manually synchronize on the returned
- * set when iterating over it:
+ * collection when traversing it via {@link Iterator}, {@link Spliterator}
+ * or {@link Stream}:
* <pre>
* Set s = Collections.synchronizedSet(new HashSet());
* ...
@@ -2149,8 +2150,9 @@
* through the returned sorted set (or its views).<p>
*
* It is imperative that the user manually synchronize on the returned
- * sorted set when iterating over it or any of its {@code subSet},
- * {@code headSet}, or {@code tailSet} views.
+ * sorted set when traversing it or any of its {@code subSet},
+ * {@code headSet}, or {@code tailSet} views via {@link Iterator},
+ * {@link Spliterator} or {@link Stream}:
* <pre>
* SortedSet s = Collections.synchronizedSortedSet(new TreeSet());
* ...
@@ -2240,8 +2242,9 @@
* accomplished through the returned navigable set (or its views).<p>
*
* It is imperative that the user manually synchronize on the returned
- * navigable set when iterating over it or any of its {@code subSet},
- * {@code headSet}, or {@code tailSet} views.
+ * navigable set when traversing it, or any of its {@code subSet},
+ * {@code headSet}, or {@code tailSet} views, via {@link Iterator},
+ * {@link Spliterator} or {@link Stream}:
* <pre>
* NavigableSet s = Collections.synchronizedNavigableSet(new TreeSet());
* ...
@@ -2355,7 +2358,8 @@
* through the returned list.<p>
*
* It is imperative that the user manually synchronize on the returned
- * list when iterating over it:
+ * list when traversing it via {@link Iterator}, {@link Spliterator}
+ * or {@link Stream}:
* <pre>
* List list = Collections.synchronizedList(new ArrayList());
* ...
@@ -2523,7 +2527,8 @@
* through the returned map.<p>
*
* It is imperative that the user manually synchronize on the returned
- * map when iterating over any of its collection views:
+ * map when traversing any of its collection views via {@link Iterator},
+ * {@link Spliterator} or {@link Stream}:
* <pre>
* Map m = Collections.synchronizedMap(new HashMap());
* ...
@@ -2700,9 +2705,10 @@
* through the returned sorted map (or its views).<p>
*
* It is imperative that the user manually synchronize on the returned
- * sorted map when iterating over any of its collection views, or the
+ * sorted map when traversing any of its collection views, or the
* collections views of any of its {@code subMap}, {@code headMap} or
- * {@code tailMap} views.
+ * {@code tailMap} views, via {@link Iterator}, {@link Spliterator} or
+ * {@link Stream}:
* <pre>
* SortedMap m = Collections.synchronizedSortedMap(new TreeMap());
* ...
@@ -2797,9 +2803,10 @@
* accomplished through the returned navigable map (or its views).<p>
*
* It is imperative that the user manually synchronize on the returned
- * navigable map when iterating over any of its collection views, or the
+ * navigable map when traversing any of its collection views, or the
* collections views of any of its {@code subMap}, {@code headMap} or
- * {@code tailMap} views.
+ * {@code tailMap} views, via {@link Iterator}, {@link Spliterator} or
+ * {@link Stream}:
* <pre>
* NavigableMap m = Collections.synchronizedNavigableMap(new TreeMap());
* ...