Document thread-safety of Multimaps.new*Multimap(...) methods

[GoogleCodeExporter]

Many of the implementations returned from the Multimaps factory methods extend 
StandardMultimap in one form or another. The StandardMultimap class 
documentation has the 
following to say on its thread safety:

This class is not threadsafe when any concurrent operations update the 
multimap, even if the 
underlying map and {@link #createCollection()} method return threadsafe 
classes. Concurrent 
read operations will work correctly. To allow concurrent update operations, 
wrap your multimap 
with a call to {@link Multimaps#synchronizedMultimap}.

This is not repeated for the factory calls and the fact that a StandardMultimap 
(or any of its 
extensions such as Tree/Hash/StandardSortedSet etc.) is returned is not obvious 
to the casual 
observer.

A note should be added to the Multimaps class documentation that explains this 
in detail and a 
warning put on each factory method.

The same documentation requirement applies to Multisets.

Original issue reported on code.google.com by jed.wesl...@gmail.com on 15 Jun 2008 at 3:58

[GoogleCodeExporter]

Thanks for bringing this up. We should definitely review the Javadoc to make 
sure
we're mentioning thread-safety when appropriate.

Since the Multimap implementation classes like HashMultimap already document 
that
they're not threadsafe, the factory methods like Multimaps.newHashMultimap 
don't need
to repeat that fact. However, the Multimaps methods newMultimap(), 
newListMultimap(),
newSetMultimap(), newSortedSetMultimap(), and forMap() should document 
thread-safety,
as should Multisets.forSet().

Original comment by jared.l....@gmail.com on 16 Jun 2008 at 4:42

[GoogleCodeExporter]

Original comment by jared.l....@gmail.com on 16 Jun 2008 at 4:47

[GoogleCodeExporter]

Original comment by jared.l....@gmail.com on 16 Jun 2008 at 4:48

• Changed state: Accepted

[GoogleCodeExporter]

Fair enough with the concrete classes. I brought it up specifically for the 
Standard** classes as they are package 
private and not mentioned on the factory methods.

Original comment by jed.wesl...@gmail.com on 17 Jun 2008 at 9:21

[GoogleCodeExporter]

The Javadoc of those methods now describes the thread-safety of the generated
multimap or multiset. The revised Javadoc will be in the next Google 
Collections release.

Original comment by jared.l....@gmail.com on 7 Jul 2008 at 6:03

• Changed state: Fixed