Hello!
Here's the patch. I updated JavaDoc for synchronizedSet,
synchronizedSortedSet, synchronizedNavigableSet, synchronizedList,
synchronizedMap, synchronizedSortedMap and synchronizedNavigableMap.
Hopefully my wording is correct (English is not my native language).
With best regards,
Tagir Valeev.
diff --git a/src/java.base/share/classes/java/util/Collections.java
b/src/java.base/share/classes/java/util/Collections.java
--- a/src/java.base/share/classes/java/util/Collections.java
+++ b/src/java.base/share/classes/java/util/Collections.java
@@ -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:
+ * set 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,9 @@
* 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
- * collections views of any of its {@code subMap}, {@code headMap} or
- * {@code tailMap} views.
+ * sorted map when traversing via {@link Iterator}, {@link Spliterator}
+ * or {@link Stream} any of its collection views, or the collections views
+ * of any of its {@code subMap}, {@code headMap} or {@code tailMap} views:
* <pre>
* SortedMap m = Collections.synchronizedSortedMap(new TreeMap());
* ...
@@ -2797,9 +2802,9 @@
* 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
- * collections views of any of its {@code subMap}, {@code headMap} or
- * {@code tailMap} views.
+ * navigable map when traversing via {@link Iterator}, {@link Spliterator}
+ * or {@link Stream} any of its collection views, or the collections views
+ * of any of its {@code subMap}, {@code headMap} or {@code tailMap} views:
* <pre>
* NavigableMap m = Collections.synchronizedNavigableMap(new TreeMap());
* ...
PS> Hi Tagir,
PS> Agreed. If you wanna send a patch to this list with updates to
PS> the other synchronized* methods i can review push it for you.
PS> Paul.
>> On 12 Oct 2015, at 15:18, Tagir F. Valeev <amae...@gmail.com> wrote:
>>
>> Hello!
>>
>> With the introduction of Stream API the JavaDoc for
>> Collections.synchronizedCollection was updated (as part of work on
>> JDK-8023275):
>>
>> * It is imperative that the user manually synchronize on the returned
>> * collection when traversing it via {@link Iterator}, {@link Spliterator}
>> * or {@link Stream}:
>>
>> This sounds fine, but the same update is missing on other
>> synchronizedXYZ methods. For example, Collections.synchronizedList
>> documentation still states:
>>
>> * It is imperative that the user manually synchronize on the returned
>> * list when iterating over it:
>>
>> Nothing about Spliterator and especially about Stream. The same for
>> synchronizedSet, synchronizedSortedSet, synchronizedNavigableSet. Even
>> though internally all of them inherit the SynchronizedCollection
>> implementation, it's not specified that, for example, synchronizedSet
>> behavior is somehow connected with synchronizedCollection behavior.
>>
>> I think, the corresponding documentation update should be added. It's
>> especially important for the Stream as many people see no difference
>> between
>>
>> collection.forEach(...);
>>
>> And
>>
>> collection.stream().forEach(...);
>>
>> But with synchronized collections these two lines are very different:
>> the second call is not synchronized.
>>
>> What do you think?
>>
>> With best regards,
>> Tagir Valeev.
>> diff --git a/src/java.base/share/classes/java/util/Collections.java
b/src/java.base/share/classes/java/util/Collections.java
--- a/src/java.base/share/classes/java/util/Collections.java
+++ b/src/java.base/share/classes/java/util/Collections.java
@@ -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:
+ * set 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,9 @@
* 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
- * collections views of any of its {@code subMap}, {@code headMap} or
- * {@code tailMap} views.
+ * sorted map when traversing via {@link Iterator}, {@link Spliterator}
+ * or {@link Stream} any of its collection views, or the collections views
+ * of any of its {@code subMap}, {@code headMap} or {@code tailMap} views:
* <pre>
* SortedMap m = Collections.synchronizedSortedMap(new TreeMap());
* ...
@@ -2797,9 +2802,9 @@
* 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
- * collections views of any of its {@code subMap}, {@code headMap} or
- * {@code tailMap} views.
+ * navigable map when traversing via {@link Iterator}, {@link Spliterator}
+ * or {@link Stream} any of its collection views, or the collections views
+ * of any of its {@code subMap}, {@code headMap} or {@code tailMap} views:
* <pre>
* NavigableMap m = Collections.synchronizedNavigableMap(new TreeMap());
* ...
