[PATCH] Re: Incomplete JavaDoc for Collections.synchronizedXYZ

[Tagir F. Valeev]

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 <amaembo at 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.
>> 
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: synch-doc-patch.txt
URL: <http://mail.openjdk.java.net/pipermail/core-libs-dev/attachments/20151025/84978970/synch-doc-patch.txt>