Incomplete JavaDoc for Collections.synchronizedXYZ

[Paul Sandoz]

Hi Tagir,

Agreed. If you wanna send a patch to this list with updates to the other synchronized* methods i can review push it for you.

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.
>