commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From joc...@apache.org
Subject svn commit: r1079552 - in /commons/proper/collections: branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/ trunk/src/java/org/apache/commons/collections/map/
Date Tue, 08 Mar 2011 21:27:41 GMT
Author: jochen
Date: Tue Mar  8 21:27:41 2011
New Revision: 1079552

URL: http://svn.apache.org/viewvc?rev=1079552&view=rev
Log:
PR: COLLECTIONS-332
Documented the dependency of ListOrderedMap on the standard Map contract of using equals()
and hashCode().

Modified:
    commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java
    commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/IdentityMap.java
    commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/ListOrderedMap.java
    commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java
    commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/IdentityMap.java
    commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/ListOrderedMap.java

Modified: commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java?rev=1079552&r1=1079551&r2=1079552&view=diff
==============================================================================
--- commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java
(original)
+++ commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java
Tue Mar  8 21:27:41 2011
@@ -46,6 +46,11 @@ import java.util.Map;
  * returns <code>"Four".</code>  The <code>Set</code> returned by
<code>keySet()</code>
  * equals <code>{"one", "two", null}.</code>
  * <p>
+ * <strong>This map will violate the detail of various Map and map view contracts.</note>
+ * As a general rule, don't compare this map to other maps. In particular, you can't
+ * use decorators like {@link ListOrderedMap} on it, which silently assume that these
+ * contracts are fulfilled.
+ * <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

Modified: commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/IdentityMap.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/IdentityMap.java?rev=1079552&r1=1079551&r2=1079552&view=diff
==============================================================================
--- commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/IdentityMap.java
(original)
+++ commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/IdentityMap.java
Tue Mar  8 21:27:41 2011
@@ -26,8 +26,10 @@ import java.util.Map;
  * A <code>Map</code> implementation that matches keys and values based
  * on <code>==</code> not <code>equals()</code>.
  * <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.
+ * <strong>This map will violate the detail of various Map and map view contracts.</note>
+ * As a general rule, don't compare this map to other maps. In particular, you can't
+ * use decorators like {@link ListOrderedMap} on it, which silently assume that these
+ * contracts are fulfilled.
  * <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

Modified: commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/ListOrderedMap.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/ListOrderedMap.java?rev=1079552&r1=1079551&r2=1079552&view=diff
==============================================================================
--- commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/ListOrderedMap.java
(original)
+++ commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH/src/java/org/apache/commons/collections/map/ListOrderedMap.java
Tue Mar  8 21:27:41 2011
@@ -59,6 +59,17 @@ import org.apache.commons.collections.li
  * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
  * exceptions when accessed by concurrent threads without synchronization.
  * <p>
+ * <strong>Note that ListOrderedMap doesn't work with {@link IdentityMap},
+ * {@link CaseInsensitiveMap}, or similar maps that violate the general
+ * contract of {@link java.util.Map}.</strong> The <code>ListOrderedMap</code>
+ * (or, more precisely, the underlying <code>List</code>) is relying on
+ * {@link Object#java.lang.equals(Object) equals()}. This is fine, as long as the
+ * decorated <code>Map</code> is also based on {@link Object#equals(Object) equals()},
+ * and {@link Object#hashCode() hashCode()}, which {@link IdentityMap}, and
+ * {@link CaseInsensitiveMap} don't: The former uses <code>==</code>, and
+ * the latter uses {@link Object#equals(Object) equals()} on a lowercased
+ * key.
+ * <p>
  * This class is Serializable from Commons Collections 3.1.
  *
  * @since Commons Collections 3.0

Modified: commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java?rev=1079552&r1=1079551&r2=1079552&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java
(original)
+++ commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java
Tue Mar  8 21:27:41 2011
@@ -46,6 +46,11 @@ import java.util.Map;
  * returns <code>"Four".</code>  The <code>Set</code> returned by
<code>keySet()</code>
  * equals <code>{"one", "two", null}.</code>
  * <p>
+ * <strong>This map will violate the detail of various Map and map view contracts.</note>
+ * As a general rule, don't compare this map to other maps. In particular, you can't
+ * use decorators like {@link ListOrderedMap} on it, which silently assume that these
+ * contracts are fulfilled.
+ * <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

Modified: commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/IdentityMap.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/IdentityMap.java?rev=1079552&r1=1079551&r2=1079552&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/IdentityMap.java
(original)
+++ commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/IdentityMap.java
Tue Mar  8 21:27:41 2011
@@ -26,8 +26,10 @@ import java.util.Map;
  * A <code>Map</code> implementation that matches keys and values based
  * on <code>==</code> not <code>equals()</code>.
  * <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.
+ * <strong>This map will violate the detail of various Map and map view contracts.</note>
+ * As a general rule, don't compare this map to other maps. In particular, you can't
+ * use decorators like {@link ListOrderedMap} on it, which silently assume that these
+ * contracts are fulfilled.
  * <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

Modified: commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/ListOrderedMap.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/ListOrderedMap.java?rev=1079552&r1=1079551&r2=1079552&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/ListOrderedMap.java
(original)
+++ commons/proper/collections/trunk/src/java/org/apache/commons/collections/map/ListOrderedMap.java
Tue Mar  8 21:27:41 2011
@@ -58,6 +58,17 @@ import org.apache.commons.collections.li
  * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
  * exceptions when accessed by concurrent threads without synchronization.
  * <p>
+ * <strong>Note that ListOrderedMap doesn't work with {@link IdentityMap},
+ * {@link CaseInsensitiveMap}, or similar maps that violate the general
+ * contract of {@link java.util.Map}.</strong> The <code>ListOrderedMap</code>
+ * (or, more precisely, the underlying <code>List</code>) is relying on
+ * {@link Object#java.lang.equals(Object) equals()}. This is fine, as long as the
+ * decorated <code>Map</code> is also based on {@link Object#equals(Object) equals()},
+ * and {@link Object#hashCode() hashCode()}, which {@link IdentityMap}, and
+ * {@link CaseInsensitiveMap} don't: The former uses <code>==</code>, and
+ * the latter uses {@link Object#equals(Object) equals()} on a lowercased
+ * key.
+ * <p>
  * This class is Serializable from Commons Collections 3.1.
  *
  * @since Commons Collections 3.0



Mime
View raw message