From 2724728c2c875c22e093503b893c873eb1e5c1a6 Mon Sep 17 00:00:00 2001
From: Stephen Colebourne <scolebourne@apache.org>
Date: Mon, 21 Nov 2005 22:52:57 +0000
Subject: [PATCH] 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
---
 .../commons/collections/map/CaseInsensitiveMap.java      | 8 +++++++-
 .../org/apache/commons/collections/map/CompositeMap.java | 6 ++++++
 .../org/apache/commons/collections/map/DefaultedMap.java | 8 +++++++-
 .../org/apache/commons/collections/map/FixedSizeMap.java | 6 ++++++
 .../commons/collections/map/FixedSizeSortedMap.java      | 6 ++++++
 .../org/apache/commons/collections/map/Flat3Map.java     | 8 +++++++-
 .../org/apache/commons/collections/map/HashedMap.java    | 6 ++++++
 .../org/apache/commons/collections/map/IdentityMap.java  | 8 +++++++-
 src/java/org/apache/commons/collections/map/LRUMap.java  | 9 +++++----
 src/java/org/apache/commons/collections/map/LazyMap.java | 6 ++++++
 .../apache/commons/collections/map/LazySortedMap.java    | 6 ++++++
 .../org/apache/commons/collections/map/LinkedMap.java    | 8 +++++++-
 .../apache/commons/collections/map/ListOrderedMap.java   | 6 ++++++
 .../org/apache/commons/collections/map/MultiKeyMap.java  | 5 +++++
 .../apache/commons/collections/map/MultiValueMap.java    | 5 +++++
 .../apache/commons/collections/map/PredicatedMap.java    | 6 ++++++
 .../commons/collections/map/PredicatedSortedMap.java     | 6 ++++++
 .../commons/collections/map/ReferenceIdentityMap.java    | 6 ++++++
 .../org/apache/commons/collections/map/ReferenceMap.java | 6 ++++++
 .../apache/commons/collections/map/TransformedMap.java   | 6 ++++++
 .../commons/collections/map/TransformedSortedMap.java    | 6 ++++++
 .../org/apache/commons/collections/map/TypedMap.java     | 6 ++++++
 .../apache/commons/collections/map/TypedSortedMap.java   | 6 ++++++
 23 files changed, 140 insertions(+), 9 deletions(-)

diff --git a/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java b/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java
index 32c5dfd1c..a933a4802 100644
--- a/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java
+++ b/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$
  *
diff --git a/src/java/org/apache/commons/collections/map/CompositeMap.java b/src/java/org/apache/commons/collections/map/CompositeMap.java
index 0b4c5b6e3..99cae3fd0 100644
--- a/src/java/org/apache/commons/collections/map/CompositeMap.java
+++ b/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$
diff --git a/src/java/org/apache/commons/collections/map/DefaultedMap.java b/src/java/org/apache/commons/collections/map/DefaultedMap.java
index 3a3f754da..f9f201687 100644
--- a/src/java/org/apache/commons/collections/map/DefaultedMap.java
+++ b/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$
  * 
diff --git a/src/java/org/apache/commons/collections/map/FixedSizeMap.java b/src/java/org/apache/commons/collections/map/FixedSizeMap.java
index fc7d9602b..d04d1896a 100644
--- a/src/java/org/apache/commons/collections/map/FixedSizeMap.java
+++ b/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
diff --git a/src/java/org/apache/commons/collections/map/FixedSizeSortedMap.java b/src/java/org/apache/commons/collections/map/FixedSizeSortedMap.java
index 92a67a061..87c200a09 100644
--- a/src/java/org/apache/commons/collections/map/FixedSizeSortedMap.java
+++ b/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
diff --git a/src/java/org/apache/commons/collections/map/Flat3Map.java b/src/java/org/apache/commons/collections/map/Flat3Map.java
index 18c38d518..8acc0021b 100644
--- a/src/java/org/apache/commons/collections/map/Flat3Map.java
+++ b/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$
  *
diff --git a/src/java/org/apache/commons/collections/map/HashedMap.java b/src/java/org/apache/commons/collections/map/HashedMap.java
index e7414fb6f..4f9cafcf2 100644
--- a/src/java/org/apache/commons/collections/map/HashedMap.java
+++ b/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$
  *
diff --git a/src/java/org/apache/commons/collections/map/IdentityMap.java b/src/java/org/apache/commons/collections/map/IdentityMap.java
index 408e4fb22..28bab75b5 100644
--- a/src/java/org/apache/commons/collections/map/IdentityMap.java
+++ b/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$
  *
diff --git a/src/java/org/apache/commons/collections/map/LRUMap.java b/src/java/org/apache/commons/collections/map/LRUMap.java
index 038753f9a..72553c850 100644
--- a/src/java/org/apache/commons/collections/map/LRUMap.java
+++ b/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$
  *
diff --git a/src/java/org/apache/commons/collections/map/LazyMap.java b/src/java/org/apache/commons/collections/map/LazyMap.java
index ebcd91965..da1031088 100644
--- a/src/java/org/apache/commons/collections/map/LazyMap.java
+++ b/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
diff --git a/src/java/org/apache/commons/collections/map/LazySortedMap.java b/src/java/org/apache/commons/collections/map/LazySortedMap.java
index e78d28ae6..52dc9cbd9 100644
--- a/src/java/org/apache/commons/collections/map/LazySortedMap.java
+++ b/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
diff --git a/src/java/org/apache/commons/collections/map/LinkedMap.java b/src/java/org/apache/commons/collections/map/LinkedMap.java
index 9c733cd34..e3ce3c1ec 100644
--- a/src/java/org/apache/commons/collections/map/LinkedMap.java
+++ b/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$
  *
diff --git a/src/java/org/apache/commons/collections/map/ListOrderedMap.java b/src/java/org/apache/commons/collections/map/ListOrderedMap.java
index c92e5dfb6..cdb78e9ba 100644
--- a/src/java/org/apache/commons/collections/map/ListOrderedMap.java
+++ b/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
diff --git a/src/java/org/apache/commons/collections/map/MultiKeyMap.java b/src/java/org/apache/commons/collections/map/MultiKeyMap.java
index dc90f8e11..8df5efb53 100644
--- a/src/java/org/apache/commons/collections/map/MultiKeyMap.java
+++ b/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$
diff --git a/src/java/org/apache/commons/collections/map/MultiValueMap.java b/src/java/org/apache/commons/collections/map/MultiValueMap.java
index f247bc2af..81e86be93 100644
--- a/src/java/org/apache/commons/collections/map/MultiValueMap.java
+++ b/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
diff --git a/src/java/org/apache/commons/collections/map/PredicatedMap.java b/src/java/org/apache/commons/collections/map/PredicatedMap.java
index c6844da56..ef06566ce 100644
--- a/src/java/org/apache/commons/collections/map/PredicatedMap.java
+++ b/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
diff --git a/src/java/org/apache/commons/collections/map/PredicatedSortedMap.java b/src/java/org/apache/commons/collections/map/PredicatedSortedMap.java
index 552d346d4..e4c7e75a7 100644
--- a/src/java/org/apache/commons/collections/map/PredicatedSortedMap.java
+++ b/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
diff --git a/src/java/org/apache/commons/collections/map/ReferenceIdentityMap.java b/src/java/org/apache/commons/collections/map/ReferenceIdentityMap.java
index f639735ae..b36b5b33a 100644
--- a/src/java/org/apache/commons/collections/map/ReferenceIdentityMap.java
+++ b/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
  * 
diff --git a/src/java/org/apache/commons/collections/map/ReferenceMap.java b/src/java/org/apache/commons/collections/map/ReferenceMap.java
index 4d0d933fc..3f6a1eb61 100644
--- a/src/java/org/apache/commons/collections/map/ReferenceMap.java
+++ b/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>.
diff --git a/src/java/org/apache/commons/collections/map/TransformedMap.java b/src/java/org/apache/commons/collections/map/TransformedMap.java
index eaa999902..138b7c767 100644
--- a/src/java/org/apache/commons/collections/map/TransformedMap.java
+++ b/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
diff --git a/src/java/org/apache/commons/collections/map/TransformedSortedMap.java b/src/java/org/apache/commons/collections/map/TransformedSortedMap.java
index 01121ee58..973083365 100644
--- a/src/java/org/apache/commons/collections/map/TransformedSortedMap.java
+++ b/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
diff --git a/src/java/org/apache/commons/collections/map/TypedMap.java b/src/java/org/apache/commons/collections/map/TypedMap.java
index 78af31b8e..cc0628930 100644
--- a/src/java/org/apache/commons/collections/map/TypedMap.java
+++ b/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
diff --git a/src/java/org/apache/commons/collections/map/TypedSortedMap.java b/src/java/org/apache/commons/collections/map/TypedSortedMap.java
index d01c7a537..62b9ec357 100644
--- a/src/java/org/apache/commons/collections/map/TypedSortedMap.java
+++ b/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