Java Doc for MultiMap.java in  » Library » Apache-common-Collections » org » apache » commons » collections » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 return a Collection, holding all the values put to that key.

For example:

 MultiMap mhm = new MultiHashMap();
 mhm.put(key, "A");
 mhm.put(key, "B");
 mhm.put(key, "C");
 Collection coll = (Collection) mhm.get(key);

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: 155406 $ $Date: 2005-02-26 12:55:26 +0000 (Sat, 26 Feb 2005) $
author:
   Christopher Berry
author:
   James Strachan
author:
   Stephen Colebourne

The returned value will implement Collection.

Implementations typically check all collections against all keys for the value. This cannot be mandated due to backwards compatability of this interface.
Parameters:
  value - the value to search for 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

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.
Parameters:
  key - the key to retrieve the Collection of values, implementations shouldreturn 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

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.
Parameters:
  key - the key to store against
Parameters:
  value - the value to add to the collection at the key 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

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.
Parameters:
  key - the key to remove from
Parameters:
  item - the item to remove 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

Implementations typically return null from a subsequant get(Object), however they may choose to return an empty collection.
Parameters:
  key - the key to remove values from the Collection of values removed, implementations shouldreturn 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

Implementations typically return only the count of keys in the map This cannot be mandated due to backwards compatability of this interface. the number of key-collection mappings in this 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. a collection view of the values contained in this map