Incomplete JavaDoc for Collections.synchronizedXYZ

Tagir F. Valeev amaembo at
Mon Oct 12 13:18:16 UTC 2015


With the introduction of Stream API the JavaDoc for
Collections.synchronizedCollection was updated (as part of work on

 * 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



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.

More information about the core-libs-dev mailing list