From 17e27dbcd3cd8a3701c1af5029024ea8da8d1f07 Mon Sep 17 00:00:00 2001 From: Stephen Colebourne Date: Sun, 14 Mar 2004 15:33:57 +0000 Subject: [PATCH] MultiMap,MultiHashMap, add extra documentation to clarify the interface git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@131606 13f79535-47bb-0310-9956-ffa450edef68 --- RELEASE-NOTES.html | 1 + .../commons/collections/MultiHashMap.java | 62 +++++---- .../apache/commons/collections/MultiMap.java | 118 ++++++++++++++++-- 3 files changed, 146 insertions(+), 35 deletions(-) diff --git a/RELEASE-NOTES.html b/RELEASE-NOTES.html index da5d396b9..1a85ceea5 100644 --- a/RELEASE-NOTES.html +++ b/RELEASE-NOTES.html @@ -44,4 +44,5 @@ No interface changes, or deprecations have occurred. diff --git a/src/java/org/apache/commons/collections/MultiHashMap.java b/src/java/org/apache/commons/collections/MultiHashMap.java index e645c074e..1d831287d 100644 --- a/src/java/org/apache/commons/collections/MultiHashMap.java +++ b/src/java/org/apache/commons/collections/MultiHashMap.java @@ -31,10 +31,13 @@ import java.util.Set; * {@link org.apache.commons.collections.MultiMap MultiMap} interface. *

* A MultiMap is a Map with slightly different semantics. - * Putting a value into the map will add the value to a Collection at that - * key. Getting a value will always return a Collection, holding all the - * values put to that key. This implementation uses an ArrayList as the - * collection. + * Putting a value into the map will add the value to a Collection at that key. + * Getting a value will return a Collection, holding all the values put to that key. + *

+ * This implementation uses an ArrayList as the collection. + * The internal storage list is made available without cloning via the + * get(Object) and entrySet() methods. + * The implementation returns null when there are no values mapped to a key. *

* For example: * 

@@ -42,12 +45,12 @@ import java.util.Set;
  * mhm.put(key, "A");
  * mhm.put(key, "B");
  * mhm.put(key, "C");
- * Collection coll = mhm.get(key);
+ * List list = (List) mhm.get(key); *

- * coll will be a list containing "A", "B", "C". + * list will be a list containing "A", "B", "C". * * @since Commons Collections 2.0 - * @version $Revision: 1.15 $ $Date: 2004/02/18 01:15:42 $ + * @version $Revision: 1.16 $ $Date: 2004/03/14 15:33:57 $ * * @author Christopher Berry * @author James Strachan @@ -58,7 +61,7 @@ import java.util.Set; */ public class MultiHashMap extends HashMap implements MultiMap { - //backed values collection + // backed values collection private transient Collection values = null; // compatibility with commons-collection releases 2.0/2.1 @@ -125,16 +128,17 @@ public class MultiHashMap extends HashMap implements MultiMap { } } } - + + //----------------------------------------------------------------------- /** - * Put a key and value into the map. + * Adds the value to the collection associated with the specified key. *

- * The value is added to a collection mapped to the key instead of - * replacing the previous value. - * - * @param key the key to set - * @param value the value to set the key to - * @return the value added if the add is successful, null otherwise + * Unlike a normal Map the previous value is not replaced. + * Instead the new value is added to the collection stored against the key. + * + * @param key the key to store against + * @param value the value to add to the collection at the key + * @return the value added if the map changed and null if the map did not change */ public Object put(Object key, Object value) { // NOTE:: put is called during deserialization in JDK < 1.4 !!!!!! @@ -148,14 +152,14 @@ public class MultiHashMap extends HashMap implements MultiMap { return (results ? value : null); } - + /** - * Does the map contain a specific value. + * Checks whether the map contains the value specified. *

- * This searches the collection mapped to each key, and thus could be slow. + * This checks all collections against all keys for the value, and thus could be slow. * * @param value the value to search for - * @return true if the list contains the value + * @return true if the map contains the value */ public boolean containsValue(Object value) { Set pairs = super.entrySet(); @@ -178,10 +182,14 @@ public class MultiHashMap extends HashMap implements MultiMap { * Removes a specific value from map. *

* The item is removed from the collection mapped to the specified key. + * Other values attached to that key are unaffected. + *

+ * If the last value for a key is removed, null will be returned + * from a subsequant get(key). * * @param key the key to remove from * @param item the value to remove - * @return the value removed (which was passed in) + * @return the value removed (which was passed in), null if nothing removed */ public Object remove(Object key, Object item) { Collection valuesForKey = (Collection) super.get(key); @@ -215,18 +223,19 @@ public class MultiHashMap extends HashMap implements MultiMap { super.clear(); } - /** - * Gets a view over all the values in the map. + /** + * Gets a collection containing all the values in the map. *

- * The values view includes all the entries in the collections at each map key. - * - * @return the collection view of all the values in the map + * This returns a collection containing the combination of values from all keys. + * + * @return a collection view of the values contained in this map */ public Collection values() { Collection vs = values; return (vs != null ? vs : (values = new Values())); } + //----------------------------------------------------------------------- /** * Inner class to view the elements. */ @@ -293,6 +302,7 @@ public class MultiHashMap extends HashMap implements MultiMap { } + //----------------------------------------------------------------------- /** * Clone the map. *

diff --git a/src/java/org/apache/commons/collections/MultiMap.java b/src/java/org/apache/commons/collections/MultiMap.java index c199646fd..784dfa5cd 100644 --- a/src/java/org/apache/commons/collections/MultiMap.java +++ b/src/java/org/apache/commons/collections/MultiMap.java @@ -15,16 +15,15 @@ */ package org.apache.commons.collections; +import java.util.Collection; import java.util.Map; /** * Defines a map that holds a collection of values against each key. *

* A MultiMap is a Map with slightly different semantics. - * Putting a value into the map will add the value to a Collection at that - * key. Getting a value will always return a Collection, holding all the - * values put to that key. This implementation uses an ArrayList as the - * collection. + * Putting a value into the map will add the value to a Collection at that key. + * Getting a value will return a Collection, holding all the values put to that key. *

* For example: * 

@@ -34,26 +33,127 @@ import java.util.Map;
  * mhm.put(key, "C");
  * Collection coll = (Collection) mhm.get(key);
*

- * coll will be a list containing "A", "B", "C". + * coll will be a collection containing "A", "B", "C". + *

+ * NOTE: Additional methods were added to this interface in Commons Collections 3.1. + * These were added solely for documentation purposes and do not change the interface + * as they were defined in the superinterface Map anyway. * * @since Commons Collections 2.0 - * @version $Revision: 1.11 $ $Date: 2004/02/18 01:15:42 $ + * @version $Revision: 1.12 $ $Date: 2004/03/14 15:33:57 $ * * @author Christopher Berry * @author James Strachan * @author Stephen Colebourne */ public interface MultiMap extends Map { - + /** * Removes a specific value from map. *

* The item is removed from the collection mapped to the specified key. + * Other values attached to that key are unaffected. + *

+ * If the last value for a key is removed, implementations typically + * return null from a subsequant get(Object), however + * they may choose to return an empty collection. * * @param key the key to remove from * @param item the item to remove - * @return the value removed (which was passed in) + * @return the value removed (which was passed in), null if nothing removed + * @throws UnsupportedOperationException if the map is unmodifiable + * @throws ClassCastException if the key or value is of an invalid type + * @throws NullPointerException if the key or value is null and null is invalid */ public Object remove(Object key, Object item); - + + //----------------------------------------------------------------------- + /** + * Gets the number of keys in this map. + *

+ * Implementations typically return only the count of keys in the map + * This cannot be mandated due to backwards compatability of this interface. + * + * @return the number of key-collection mappings in this map + */ + int size(); + + /** + * Gets the collection of values associated with the specified key. + *

+ * The returned value will implement Collection. Implementations + * are free to declare that they return Collection subclasses + * such as List or Set. + *

+ * Implementations typically return null if no values have + * been mapped to the key, however the implementation may choose to + * return an empty collection. + *

+ * Implementations may choose to return a clone of the internal collection. + * + * @param key the key to retrieve + * @return the Collection of values, implementations should + * return null for no mapping, but may return an empty collection + * @throws ClassCastException if the key is of an invalid type + * @throws NullPointerException if the key is null and null keys are invalid + */ + Object get(Object key); + + /** + * Checks whether the map contains the value specified. + *

+ * Implementations typically check all collections against all keys for the value. + * This cannot be mandated due to backwards compatability of this interface. + * + * @param value the value to search for + * @return true if the map contains the value + * @throws ClassCastException if the value is of an invalid type + * @throws NullPointerException if the value is null and null value are invalid + */ + boolean containsValue(Object value); + + /** + * Adds the value to the collection associated with the specified key. + *

+ * Unlike a normal Map the previous value is not replaced. + * Instead the new value is added to the collection stored against the key. + * The collection may be a List, Set or other + * collection dependent on implementation. + * + * @param key the key to store against + * @param value the value to add to the collection at the key + * @return typically the value added if the map changed and null if the map did not change + * @throws UnsupportedOperationException if the map is unmodifiable + * @throws ClassCastException if the key or value is of an invalid type + * @throws NullPointerException if the key or value is null and null is invalid + * @throws IllegalArgumentException if the key or value is invalid + */ + Object put(Object key, Object value); + + /** + * Removes all values associated with the specified key. + *

+ * Implementations typically return null from a subsequant + * get(Object), however they may choose to return an empty collection. + * + * @param key the key to remove values from + * @return the Collection of values removed, implementations should + * return null for no mapping found, but may return an empty collection + * @throws UnsupportedOperationException if the map is unmodifiable + * @throws ClassCastException if the key is of an invalid type + * @throws NullPointerException if the key is null and null keys are invalid + */ + Object remove(Object key); + + /** + * Gets a collection containing all the values in the map. + *

+ * Inplementations typically return a collection containing the combination + * of values from all keys. + * This cannot be mandated due to backwards compatability of this interface. + * + * @return a collection view of the values contained in this map + */ + Collection values(); + }