[PATCH] Re: Incomplete JavaDoc for Collections.synchronizedXYZ (original) (raw)
Tagir F. Valeev amaembo at gmail.com
Sun Oct 25 09:29:03 UTC 2015
- Previous message: Incomplete JavaDoc for Collections.synchronizedXYZ
- Next message: RFR 8068887 : java.lang.Throwable could use Collections.emptyList for suppressedException
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
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.
* * 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).
* * 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).
* * 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.
* * 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.
* * 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).
* * 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).
* * 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>
- Previous message: Incomplete JavaDoc for Collections.synchronizedXYZ
- Next message: RFR 8068887 : java.lang.Throwable could use Collections.emptyList for suppressedException
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]