You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sc...@apache.org on 2004/03/14 16:33:57 UTC
cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections MultiMap.java MultiHashMap.java
scolebourne 2004/03/14 07:33:57
Modified: collections RELEASE-NOTES.html
collections/src/java/org/apache/commons/collections
MultiMap.java MultiHashMap.java
Log:
MultiMap,MultiHashMap, add extra documentation to clarify the interface
Revision Changes Path
1.15 +1 -0 jakarta-commons/collections/RELEASE-NOTES.html
Index: RELEASE-NOTES.html
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/RELEASE-NOTES.html,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- RELEASE-NOTES.html 13 Mar 2004 17:17:03 -0000 1.14
+++ RELEASE-NOTES.html 14 Mar 2004 15:33:56 -0000 1.15
@@ -44,4 +44,5 @@
<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>
1.12 +109 -9 jakarta-commons/collections/src/java/org/apache/commons/collections/MultiMap.java
Index: MultiMap.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/MultiMap.java,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- MultiMap.java 18 Feb 2004 01:15:42 -0000 1.11
+++ MultiMap.java 14 Mar 2004 15:33:57 -0000 1.12
@@ -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
- * 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.
* <p>
* For example:
* <pre>
@@ -34,7 +33,11 @@
* 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$ $Date$
@@ -44,16 +47,113 @@
* @author Stephen Colebourne
*/
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();
+
}
1.16 +36 -26 jakarta-commons/collections/src/java/org/apache/commons/collections/MultiHashMap.java
Index: MultiHashMap.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/MultiHashMap.java,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- MultiHashMap.java 18 Feb 2004 01:15:42 -0000 1.15
+++ MultiHashMap.java 14 Mar 2004 15:33:57 -0000 1.16
@@ -31,10 +31,13 @@
* {@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
- * 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.
+ * <p>
+ * 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,9 +45,9 @@
* 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$ $Date$
@@ -58,7 +61,7 @@
*/
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 @@
}
}
}
-
+
+ //-----------------------------------------------------------------------
/**
- * 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
- * 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, <code>null</code> otherwise
+ * 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.
+ *
+ * @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 @@
return (results ? value : null);
}
-
+
/**
- * 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 @@
* 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);
@@ -215,18 +223,19 @@
super.clear();
}
- /**
- * 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.
- *
- * @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 @@
}
+ //-----------------------------------------------------------------------
/**
* Clone the map.
* <p>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org