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

@@ -44,4 +44,5 @@ No interface changes, or deprecations have occurred.
 <ul>
 <li>TreeBidiMap - Add javadoc about requiring Comparable entries [26470]</li>
 <li>MultiKey - Add extra explanatations, examples and warnings</li>
+<li>MultiMap,MultiHashMap - Add extra documentation to clarify the interface and implementation</li>
 </ul>

src/java/org/apache/commons/collections/MultiHashMap.java

@@ -31,10 +31,13 @@ import java.util.Set;
  * {@link org.apache.commons.collections.MultiMap MultiMap} interface.
  * <p>
  * A <code>MultiMap</code> is a Map with slightly different semantics.
- * Putting a value into the map will add the value to a Collection at that
+ * Putting a value into the map will add the value to a Collection at that key.
- * key. Getting a value will always return a Collection, holding all the
+ * Getting a value will return a Collection, holding all the values put to that key.
- * values put to that key. This implementation uses an ArrayList as the 
+ * <p>
- * collection.
+ * This implementation uses an <code>ArrayList</code> as the collection.
+ * The internal storage list is made available without cloning via the
+ * <code>get(Object)</code> and <code>entrySet()</code> methods.
+ * The implementation returns <code>null</code> when there are no values mapped to a key.
  * <p>
  * For example:
  * <pre>
@@ -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);</pre>
+ * List list = (List) mhm.get(key);</pre>
  * <p>
- * <code>coll</code> will be a list containing "A", "B", "C".
+ * <code>list</code> 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
@@ -126,15 +129,16 @@ 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.
      * <p>
-     * The value is added to a collection mapped to the key instead of 
+     * Unlike a normal <code>Map</code> the previous value is not replaced.
-     * replacing the previous value.
+     * Instead the new value is added to the collection stored against the key.
      *
-     * @param key  the key to set
+     * @param key  the key to store against
-     * @param value  the value to set the key to
+     * @param value  the value to add to the collection at the key
-     * @return the value added if the add is successful, <code>null</code> otherwise
+     * @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 !!!!!!
@@ -150,12 +154,12 @@ public class MultiHashMap extends HashMap implements MultiMap {
     }
 
     /**
-     * Does the map contain a specific value.
+     * Checks whether the map contains the value specified.
      * <p>
-     * 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.
      * <p>
      * The item is removed from the collection mapped to the specified key.
+     * Other values attached to that key are unaffected.
+     * <p>
+     * If the last value for a key is removed, <code>null</code> will be returned
+     * from a subsequant <code>get(key)</code>.
      * 
      * @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);
@@ -216,17 +224,18 @@ public class MultiHashMap extends HashMap implements MultiMap {
     }
 
     /**
-     * Gets a view over all the values in the map.
+     * Gets a collection containing all the values in the map.
      * <p>
-     * The values view includes all the entries in the collections at each map key.
+     * This returns a collection containing the combination of values from all keys.
      *
-     * @return the collection view of all the values in the map
+     * @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.
      * <p>

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.
  * <p>
  * A <code>MultiMap</code> is a Map with slightly different semantics.
- * Putting a value into the map will add the value to a Collection at that
+ * Putting a value into the map will add the value to a Collection at that key.
- * key. Getting a value will always return a Collection, holding all the
+ * Getting a value will return a Collection, holding all the values put to that key.
- * values put to that key. This implementation uses an ArrayList as the 
- * collection.
  * <p>
  * For example:
  * <pre>
@@ -34,10 +33,14 @@ import java.util.Map;
  * mhm.put(key, "C");
  * Collection coll = (Collection) mhm.get(key);</pre>
  * <p>
- * <code>coll</code> will be a list containing "A", "B", "C".
+ * <code>coll</code> will be a collection containing "A", "B", "C".
+ * <p>
+ * 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 <code>Map</code> 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
@@ -49,11 +52,108 @@ public interface MultiMap extends Map {
      * Removes a specific value from map.
      * <p>
      * The item is removed from the collection mapped to the specified key.
+     * Other values attached to that key are unaffected.
+     * <p>
+     * If the last value for a key is removed, implementations typically
+     * return <code>null</code> from a subsequant <code>get(Object)</code>, 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.
+     * <p>
+     * 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.
+     * <p>
+     * The returned value will implement <code>Collection</code>. Implementations
+     * are free to declare that they return <code>Collection</code> subclasses
+     * such as <code>List</code> or <code>Set</code>.
+     * <p>
+     * Implementations typically return <code>null</code> if no values have
+     * been mapped to the key, however the implementation may choose to
+     * return an empty collection.
+     * <p>
+     * Implementations may choose to return a clone of the internal collection.
+     *
+     * @param key  the key to retrieve
+     * @return the <code>Collection</code> of values, implementations should
+     *  return <code>null</code> 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.
+     * <p>
+     * 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.
+     * <p>
+     * Unlike a normal <code>Map</code> the previous value is not replaced.
+     * Instead the new value is added to the collection stored against the key.
+     * The collection may be a <code>List</code>, <code>Set</code> 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.
+     * <p>
+     * Implementations typically return <code>null</code> from a subsequant
+     * <code>get(Object)</code>, however they may choose to return an empty collection.
+     *
+     * @param key  the key to remove values from
+     * @return the <code>Collection</code> of values removed, implementations should
+     *  return <code>null</code> 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.
+     * <p>
+     * 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();
+
 }