+ * A ListValuedMap is a Map with slightly different semantics:
+ *
+ * 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
+ * Implementations typically return
+ * A
+ * For example:
+ *
+ *
+ *
+ * @since 4.1
+ * @version $Id$
+ */
+public interface MultiValuedMap
+ * Implementations would return the total size of the map which is the count
+ * of the values from all keys.
+ *
+ * @return the total size of the map
+ */
+ int size();
+
+ /**
+ * Returns true if this map contains no key-value mappings.
+ *
+ * @return true if this map contains no key-value mappings
+ */
+ boolean isEmpty();
+
+ /**
+ * Returns true if this map contains a mapping for the specified
+ * key. More formally, returns true if and only if this map
+ * contains a mapping for a key k such that
+ * (key==null ? k==null : key.equals(k)). (There can be at most one
+ * such mapping.)
+ *
+ * @param key key whose presence in this map is to be tested
+ * @return true if this map contains a mapping for the specified key
+ * @throws ClassCastException if the key is of an inappropriate type for this map (optional)
+ * @throws NullPointerException if the specified key is null and this map
+ * does not permit null keys (optional)
+ */
+ boolean containsKey(Object key);
+
+ /**
+ * Checks whether the map contains at least one mapping for the specified value.
+ *
+ * @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);
+
+ /**
+ * Checks whether the map contains a mapping for the specified key and value.
+ *
+ * @param key the key to search for
+ * @param value the value to search for
+ * @return true if the map contains the value
+ */
+ boolean containsMapping(Object key, Object value);
+
+ /**
+ * Gets the collection of values associated with the specified key.
+ *
+ * Implementations are free to declare that they return
+ *
+ * Implementations typically return
+ * Implementations may choose to return a clone of the internal collection.
+ *
+ * @param key the key to retrieve
+ * @return the
+ * Unlike a normal
+ * Implementations typically return
+ * 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
+ *
+ * Implementations typically return a Bag of keys with its values count as
+ * the count of the Bag. This bag is backed by the map, so any changes in
+ * the map is reflected here.
+ *
+ * @return a bag view of the key mapping contained in this map
+ */
+ Bag
+ * Implementations typically return a collection containing the combination
+ * of values from all keys.
+ *
+ * @return a collection view of the values contained in this map
+ */
+ Collection
+ * Subclasses specify a Map implementation to use as the internal storage.
+ *
+ * @since 4.1
+ * @version $Id$
+ */
+public class AbstractMultiValuedMap
+ * A subsequent
+ * 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,
+ * Returns a collection containing all the values from all keys.
+ *
+ * @return a collection view of the values contained in this map
+ */
+ public Collection
+ * Unlike a normal
+ * Returns a Bag of keys with its values count as the count of the Bag. This
+ * bag is backed by the map, so any changes in the map is reflected here.
+ * Any method which modifies this bag like add, remove,
+ * Iterator.remove etc throws
+ * 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
+ */
+ Listnull from a subsequent
+ * 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
+ */
+ ListMultiValuedMap is a Map with slightly different semantics:
+ *
+ *
+ *
+ * MultiValuedMap<K, String> map = new MultiValuedHashMap<K, String>();
+ * map.put(key, "A");
+ * map.put(key, "B");
+ * map.put(key, "C");
+ * Collection<String> coll = map.get(key);
+ *
+ * coll will be a collection containing "A", "B", "C".
+ * Collection subclasses such as List or
+ * Set.
+ * null if no values have been
+ * mapped to the key, however the implementation may choose to return an
+ * empty collection.
+ * 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
+ */
+ CollectionMap 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
+ */
+ V put(K key, V value);
+
+ /**
+ * Adds Iterable values to the collection associated with the specified key.
+ *
+ * @param key the key to store against
+ * @param values the values to add to the collection at the key, null ignored
+ * @return true if this map changed
+ */
+ boolean putAll(K key, Iterable values);
+
+ /**
+ * Copies all of the mappings from the specified map to this map (optional
+ * operation). The effect of this call is equivalent to that of calling
+ * {@link #put(Object,Object) put(k, v)} on this map once for each mapping
+ * from key k to value v in the specified map. The
+ * behavior of this operation is undefined if the specified map is modified
+ * while the operation is in progress.
+ *
+ * @param m mappings to be stored in this map
+ * @throws UnsupportedOperationException if the putAll operation is
+ * not supported by this map
+ * @throws ClassCastException if the class of a key or value in the
+ * specified map prevents it from being stored in this map
+ * @throws NullPointerException if the specified map is null, or if this map
+ * does not permit null keys or values, and the specified map
+ * contains null keys or values
+ * @throws IllegalArgumentException if some property of a key or value in
+ * the specified map prevents it from being stored in this map
+ */
+ void putAll(Map m);
+
+ /**
+ * Copies all of the mappings from the specified MultiValuedMap to this map
+ * (optional operation). The effect of this call is equivalent to that of
+ * calling {@link #put(Object,Object) put(k, v)} on this map once for each
+ * mapping from key k to value v in the specified map. The
+ * behavior of this operation is undefined if the specified map is modified
+ * while the operation is in progress.
+ *
+ * @param m mappings to be stored in this map
+ * @throws UnsupportedOperationException if the putAll operation is
+ * not supported by this map
+ * @throws ClassCastException if the class of a key or value in the
+ * specified map prevents it from being stored in this map
+ * @throws NullPointerException if the specified map is null, or if this map
+ * does not permit null keys or values, and the specified map
+ * contains null keys or values
+ * @throws IllegalArgumentException if some property of a key or value in
+ * the specified map prevents it from being stored in this map
+ */
+ void putAll(MultiValuedMap m);
+
+ /**
+ * Removes all values associated with the specified key.
+ * null from a subsequent
+ * 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
+ */
+ Collectionnull from a subsequent 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 {@code true} if the mapping was removed, {@code false} otherwise
+ * @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
+ */
+ boolean removeMapping(K key, V item);
+
+ /**
+ * Removes all of the mappings from this map (optional operation).
+ * The map will be empty after this call returns.
+ *
+ * @throws UnsupportedOperationException if the map is unmodifiable
+ */
+ void clear();
+
+ // Views
+
+ /**
+ * Returns a {@link Collection} view of the mappings contained in this map.
+ * The collection is backed by the map, so changes to the map are reflected
+ * in this, and vice-versa.
+ *
+ * @return a set view of the mappings contained in this map
+ */
+ CollectionCollection of values, will return
+ * null for no mapping
+ * @throws ClassCastException if the key is of an invalid type
+ */
+ public Collectionget(Object) would return null collection.
+ *
+ * @param key the key to remove values from
+ * @return the Collection of values removed, will return
+ * null for no mapping found.
+ * @throws ClassCastException if the key is of an invalid type
+ */
+ public Collectionnull would be
+ * returned from a subsequent get(Object).
+ *
+ * @param key the key to remove from
+ * @param item the item to remove
+ * @return {@code true} if the mapping was removed, {@code false} otherwise
+ */
+ public boolean removeMapping(K key, V item) {
+ boolean result = false;
+ final CollectionMap 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 V put(K key, V value) {
+ boolean result = false;
+ CollectionUnsupportedOperationException
+ *
+ * @return a bag view of the key mapping contained in this map
+ */
+ public Bag