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
This commit is contained in:
Stephen Colebourne
parent
5bd1ed25de
commit
17e27dbcd3
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
* 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,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
|
||||
|
|
@ -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.
|
||||
* <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 @@ 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.
|
||||
* <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);
|
||||
|
|
@ -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.
|
||||
* <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 @@ public class MultiHashMap extends HashMap implements MultiMap {
|
|||
|
||||
}
|
||||
|
||||
//-----------------------------------------------------------------------
|
||||
/**
|
||||
* Clone the map.
|
||||
* <p>
|
||||
|
|
|
|||
|
|
@ -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,26 +33,127 @@ 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
|
||||
* @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();
|
||||
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue