Javadoc lack of thread-safety

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@348007 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java

@@ -44,7 +44,13 @@ import java.util.Map;
  * <code>map.get(null)</code> returns <code>"Three"</code> and <code>map.get("ONE")</code>
  * returns <code>"Four".</code>  The <code>Set</code> returned by <code>keySet()</code>
  * equals <code>{"one", "two", null}.</code>
- * 
+ * <p>
+ * <strong>Note that CaseInsensitiveMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ *
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$
  *

src/java/org/apache/commons/collections/map/CompositeMap.java

@@ -30,6 +30,12 @@ import org.apache.commons.collections.set.CompositeSet;
  * Changes made to this map will actually be made on the decorated map.
  * Add and remove operations require the use of a pluggable strategy. If no
  * strategy is provided then add and remove are unsupported.
+ * <p>
+ * <strong>Note that CompositeMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
  *
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$

src/java/org/apache/commons/collections/map/DefaultedMap.java

@@ -48,7 +48,13 @@ import org.apache.commons.collections.functors.FactoryTransformer;
  * // obj == "NULL"
  * </pre>
  * After the above code is executed the map is still empty.
- * 
+ * <p>
+ * <strong>Note that DefaultedMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ *
  * @since Commons Collections 3.2
  * @version $Revision: 1.7 $ $Date$
  * 

src/java/org/apache/commons/collections/map/FixedSizeMap.java

@@ -41,6 +41,12 @@ import org.apache.commons.collections.set.UnmodifiableSet;
  * succeed if the mapping's key already exists in the map, so the put method
  * is not always unsupported.
  * <p>
+ * <strong>Note that FixedSizeMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ * <p>
  * This class is Serializable from Commons Collections 3.1.
  *
  * @since Commons Collections 3.0

src/java/org/apache/commons/collections/map/FixedSizeSortedMap.java

@@ -42,6 +42,12 @@ import org.apache.commons.collections.set.UnmodifiableSet;
  * succeed if the mapping's key already exists in the map, so the put method
  * is not always unsupported.
  * <p>
+ * <strong>Note that FixedSizeSortedMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedSortedMap}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ * <p>
  * This class is Serializable from Commons Collections 3.1.
  *
  * @since Commons Collections 3.0

src/java/org/apache/commons/collections/map/Flat3Map.java

@@ -59,7 +59,13 @@ import org.apache.commons.collections.iterators.EmptyMapIterator;
  * This is because it contains no complex objects or arrays which slow the progress.
  * <p>
  * Do not use <code>Flat3Map</code> if the size is likely to grow beyond 3.
- * 
+ * <p>
+ * <strong>Note that Flat3Map is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ *
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$
  *

src/java/org/apache/commons/collections/map/HashedMap.java

@@ -29,6 +29,12 @@ import java.util.Map;
  * {@link org.apache.commons.collections.MapIterator MapIterator}
  * functionality and many methods for subclassing.
  * <p>
+ * <strong>Note that HashedMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ *
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$
  *

src/java/org/apache/commons/collections/map/IdentityMap.java

@@ -27,7 +27,13 @@ import java.util.Map;
  * <p>
  * This map will violate the detail of various Map and map view contracts.
  * As a general rule, don't compare this map to other maps.
- * 
+ * <p>
+ * <strong>Note that IdentityMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ *
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$
  *

src/java/org/apache/commons/collections/map/LRUMap.java

@@ -40,11 +40,12 @@ import org.apache.commons.collections.BoundedMap;
  * All the available iterators can be reset back to the start by casting to
  * <code>ResettableIterator</code> and calling <code>reset()</code>.
  * <p>
- * <strong>Note</strong> as is the usual convention, this map must be protected
- * from concurrent access by multiple threads for example by calling 
- * <code>Collections.synchronizeMap</code>. This class may throw 
+ * <strong>Note that LRUMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
  * <code>NullPointerException</code>'s when accessed by concurrent threads.
- * 
+ *
  * @since Commons Collections 3.0 (previously in main package v1.0)
  * @version $Revision$ $Date$
  *

src/java/org/apache/commons/collections/map/LazyMap.java

@@ -47,6 +47,12 @@ import org.apache.commons.collections.functors.FactoryTransformer;
  * a new <code>Date</code> instance. Furthermore, that <code>Date</code>
  * instance is mapped to the "NOW" key in the map.
  * <p>
+ * <strong>Note that LazyMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ * <p>
  * This class is Serializable from Commons Collections 3.1.
  *
  * @since Commons Collections 3.0

src/java/org/apache/commons/collections/map/LazySortedMap.java

@@ -43,6 +43,12 @@ import org.apache.commons.collections.Transformer;
  * a new <code>Date</code> instance. Furthermore, that <code>Date</code>
  * instance is mapped to the "NOW" key in the map.
  * <p>
+ * <strong>Note that LazySortedMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedSortedMap}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ * <p>
  * This class is Serializable from Commons Collections 3.1.
  *
  * @since Commons Collections 3.0

src/java/org/apache/commons/collections/map/LinkedMap.java

@@ -49,7 +49,13 @@ import org.apache.commons.collections.list.UnmodifiableList;
  * <p>
  * The implementation is also designed to be subclassed, with lots of useful
  * methods exposed.
- * 
+ * <p>
+ * <strong>Note that LinkedMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ *
  * @since Commons Collections 3.0
  * @version $Revision$ $Date$
  *

src/java/org/apache/commons/collections/map/ListOrderedMap.java

@@ -52,6 +52,12 @@ import org.apache.commons.collections.list.UnmodifiableList;
  * If an object is added to the Map for a second time, it will remain in the
  * original position in the iteration.
  * <p>
+ * <strong>Note that ListOrderedMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ * <p>
  * This class is Serializable from Commons Collections 3.1.
  *
  * @since Commons Collections 3.0

src/java/org/apache/commons/collections/map/MultiKeyMap.java

@@ -65,6 +65,11 @@ import org.apache.commons.collections.keyvalue.MultiKey;
  *   return name;
  * }
  * </pre>
+ * <p>
+ * <strong>Note that MultiKeyMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. This class may throw exceptions when accessed
+ * by concurrent threads without synchronization.
  *
  * @since Commons Collections 3.1
  * @version $Revision$ $Date$

src/java/org/apache/commons/collections/map/MultiValueMap.java

@@ -44,6 +44,11 @@ import org.apache.commons.collections.iterators.IteratorChain;
  * for the values to be controlled. By default, an <code>ArrayList</code>
  * is used, however a <code>Class</code> to instantiate may be specified,
  * or a factory that returns a <code>Collection</code> instance.
+ * <p>
+ * <strong>Note that MultiValueMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. This class may throw exceptions when accessed
+ * by concurrent threads without synchronization.
  *
  * @author James Carman
  * @author Christopher Berry

src/java/org/apache/commons/collections/map/PredicatedMap.java

@@ -35,6 +35,12 @@ import org.apache.commons.collections.Predicate;
  * One usage would be to ensure that no null keys are added to the map.
  * <pre>Map map = PredicatedSet.decorate(new HashMap(), NotNullPredicate.INSTANCE, null);</pre>
  * <p>
+ * <strong>Note that PredicatedMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ * <p>
  * This class is Serializable from Commons Collections 3.1.
  *
  * @since Commons Collections 3.0

src/java/org/apache/commons/collections/map/PredicatedSortedMap.java

@@ -31,6 +31,12 @@ import org.apache.commons.collections.Predicate;
  * One usage would be to ensure that no null keys are added to the map.
  * <pre>SortedMap map = PredicatedSortedSet.decorate(new TreeMap(), NotNullPredicate.INSTANCE, null);</pre>
  * <p>
+ * <strong>Note that PredicatedSortedMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedSortedMap}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ * <p>
  * This class is Serializable from Commons Collections 3.1.
  *
  * @since Commons Collections 3.0

src/java/org/apache/commons/collections/map/ReferenceIdentityMap.java

@@ -55,6 +55,12 @@ import java.lang.ref.Reference;
  * <p>
  * All the available iterators can be reset back to the start by casting to
  * <code>ResettableIterator</code> and calling <code>reset()</code>.
+ * <p>
+ * <strong>Note that ReferenceIdentityMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
  *
  * @see java.lang.ref.Reference
  * 

src/java/org/apache/commons/collections/map/ReferenceMap.java

@@ -54,6 +54,12 @@ import java.io.Serializable;
  * All the available iterators can be reset back to the start by casting to
  * <code>ResettableIterator</code> and calling <code>reset()</code>.
  * <p>
+ * <strong>Note that ReferenceMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ * <p>
  * NOTE: As from Commons Collections 3.1 this map extends <code>AbstractReferenceMap</code>
  * (previously it extended AbstractMap). As a result, the implementation is now
  * extensible and provides a <code>MapIterator</code>.

src/java/org/apache/commons/collections/map/TransformedMap.java

@@ -32,6 +32,12 @@ import org.apache.commons.collections.Transformer;
  * For example, if the transformation converts Strings to Integers, you must
  * use the Integer form to remove objects.
  * <p>
+ * <strong>Note that TransformedMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ * <p>
  * This class is Serializable from Commons Collections 3.1.
  *
  * @since Commons Collections 3.0

src/java/org/apache/commons/collections/map/TransformedSortedMap.java

@@ -29,6 +29,12 @@ import org.apache.commons.collections.Transformer;
  * For example, if the transformation converts Strings to Integers, you must
  * use the Integer form to remove objects.
  * <p>
+ * <strong>Note that TransformedSortedMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedSortedMap}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ * <p>
  * This class is Serializable from Commons Collections 3.1.
  *
  * @since Commons Collections 3.0

src/java/org/apache/commons/collections/map/TypedMap.java

@@ -27,6 +27,12 @@ import org.apache.commons.collections.functors.InstanceofPredicate;
  * a specified <code>Class</code>. If an object cannot be added to the
  * collection, an IllegalArgumentException is thrown.
  * <p>
+ * <strong>Note that TypedMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ * <p>
  * The returned implementation is Serializable from Commons Collections 3.1.
  *
  * @since Commons Collections 3.0

src/java/org/apache/commons/collections/map/TypedSortedMap.java

@@ -27,6 +27,12 @@ import org.apache.commons.collections.functors.InstanceofPredicate;
  * a specified <code>Class</code>. If an object cannot be added to the
  * collection, an IllegalArgumentException is thrown.
  * <p>
+ * <strong>Note that TypedSortedMap is not synchronized and is not thread-safe.</strong>
+ * If you wish to use this map from multiple threads concurrently, you must use
+ * appropriate synchronization. The simplest approach is to wrap this map
+ * using {@link java.util.Collections#synchronizedSortedMap}. This class may throw 
+ * exceptions when accessed by concurrent threads without synchronization.
+ * <p>
  * The returned implementation is Serializable from Commons Collections 3.1.
  *
  * @since Commons Collections 3.0