PR: COLLECTIONS-332 Documented the dependency of ListOrderedMap on the standard Map contract of using equals() and hashCode().
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/branches/COLLECTIONS_3_2_BRANCH@1079552 13f79535-47bb-0310-9956-ffa450edef68 Project: http://git-wip-us.apache.org/repos/asf/commons-collections/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-collections/commit/a5f5ec96 Tree: http://git-wip-us.apache.org/repos/asf/commons-collections/tree/a5f5ec96 Diff: http://git-wip-us.apache.org/repos/asf/commons-collections/diff/a5f5ec96 Branch: refs/heads/COLLECTIONS_3_2_BRANCH Commit: a5f5ec96d1dc13f0a2c4b307dc88c0154e2b6be4 Parents: 470db28 Author: Jochen Wiedmann <joc...@apache.org> Authored: Tue Mar 8 21:27:41 2011 +0000 Committer: Jochen Wiedmann <joc...@apache.org> Committed: Tue Mar 8 21:27:41 2011 +0000 ---------------------------------------------------------------------- .../commons/collections/map/CaseInsensitiveMap.java | 5 +++++ .../org/apache/commons/collections/map/IdentityMap.java | 6 ++++-- .../apache/commons/collections/map/ListOrderedMap.java | 11 +++++++++++ 3 files changed, 20 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-collections/blob/a5f5ec96/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java ---------------------------------------------------------------------- diff --git a/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java b/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java index ba9650d..2674349 100644 --- a/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java +++ b/src/java/org/apache/commons/collections/map/CaseInsensitiveMap.java @@ -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 http://git-wip-us.apache.org/repos/asf/commons-collections/blob/a5f5ec96/src/java/org/apache/commons/collections/map/IdentityMap.java ---------------------------------------------------------------------- diff --git a/src/java/org/apache/commons/collections/map/IdentityMap.java b/src/java/org/apache/commons/collections/map/IdentityMap.java index 16edd8b..ee1fa3d 100644 --- a/src/java/org/apache/commons/collections/map/IdentityMap.java +++ b/src/java/org/apache/commons/collections/map/IdentityMap.java @@ -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 http://git-wip-us.apache.org/repos/asf/commons-collections/blob/a5f5ec96/src/java/org/apache/commons/collections/map/ListOrderedMap.java ---------------------------------------------------------------------- diff --git a/src/java/org/apache/commons/collections/map/ListOrderedMap.java b/src/java/org/apache/commons/collections/map/ListOrderedMap.java index 710c6bb..09d3262 100644 --- a/src/java/org/apache/commons/collections/map/ListOrderedMap.java +++ b/src/java/org/apache/commons/collections/map/ListOrderedMap.java @@ -59,6 +59,17 @@ import org.apache.commons.collections.list.UnmodifiableList; * 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
