org.apache.commons.collections15.multimap
Class MultiHashMap<K,V>

java.lang.Object
  extended by org.apache.commons.collections15.multimap.MultiHashMap<K,V>
All Implemented Interfaces:
Serializable, Cloneable, MultiMap<K,V>

public class MultiHashMap<K,V>
extends Object
implements MultiMap<K,V>, Serializable, Cloneable

MultiHashMap is the default implementation of the MultiMap interface.

A MultiMap is like a Map, but 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.

This implementation uses an ArrayList as the collection. The internal storage list is made available without cloning via the get(Object) and entrySet() methods. The implementation returns null when there are no values mapped to a key.

For example:

 Number key = new Integer(5);
 MultiMap<Number,String> mhm = new MultiHashMap<Number,String>();
 mhm.put(key, "A");
 mhm.put(key, "B");
 mhm.put(key, "C");
 Collection<String> coll = mhm.get(key);

list will be a list containing "A", "B", "C".

Since:
Commons Collections 2.0
Version:
$Revision: 1.2 $ $Date: 2006/06/08 15:19:55 $
Author:
Christopher Berry, James Strachan, Steve Downey, Stephen Colebourne, Julien Buret, Matt Hall, John Watkinson, Serhiy Yevtushenko
See Also:
Serialized Form

Constructor Summary
MultiHashMap()
          Constructor.
MultiHashMap(int initialCapacity)
          Constructor.
MultiHashMap(int initialCapacity, float loadFactor)
          Constructor.
MultiHashMap(Map<K,V> mapToCopy)
          Constructor that copies the input map creating an independent copy.
MultiHashMap(MultiMap<K,V> mapToCopy)
          Constructor that copies the input MultiMap creating an independent copy.
 
Method Summary
 void clear()
          Clear the map.
 Object clone()
          Clones the map creating an independent copy.
 boolean containsKey(Object key)
          Returns true if this map contains a mapping for the specified key.
 boolean containsValue(Object value)
          Checks whether the map contains the value specified.
 boolean containsValue(Object key, Object value)
          Checks whether the collection at the specified key contains the value.
protected  Collection<V> createCollection(Collection<? extends V> coll)
          Creates a new instance of the map value Collection container.
 Set<Map.Entry<K,Collection<V>>> entrySet()
          Returns a set view of the mappings contained in this map.
 boolean equals(Object obj)
          Compares the specified object with this map for equality.
 Collection<V> get(Object key)
          Gets the collection of values associated with the specified key.
 Collection<V> getCollection(Object key)
          Gets the collection mapped to the specified key.
 int hashCode()
          Returns the hash code value for this map.
 boolean isEmpty()
          Returns true if this map contains no key-value mappings.
 Iterator<V> iterator(Object key)
          Gets an iterator for the collection mapped to the specified key.
 Set<K> keySet()
          Returns a set view of the keys contained in this map.
 Map<K,Collection<V>> map()
          Returns a java.util.Map<K,Collection<V>> for this MultiMap.
 V put(K key, V value)
          Adds the value to the collection associated with the specified key.
 boolean putAll(K key, Collection<? extends V> values)
          Adds a collection of values to the collection associated with the specified key.
 void putAll(Map<? extends K,? extends V> map)
          Copies all of the mappings from the specified map to this map (optional operation).
 void putAll(MultiMap<? extends K,? extends V> map)
          Copies all of the mappings from the specified multimap to this multimap (optional operation).
 Collection<V> remove(Object key)
          Removes all values associated with the specified key.
 V remove(Object key, Object item)
          Removes a specific value from map.
 int size()
          Gets the number of keys in this map.
 int size(Object key)
          Gets the size of the collection mapped to the specified key.
 String toString()
           
 int totalSize()
          Gets the total size of the map by counting all the values.
 Collection<V> values()
          Gets a collection containing all the values in the map.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

MultiHashMap

public MultiHashMap()
Constructor.


MultiHashMap

public MultiHashMap(int initialCapacity)
Constructor.

Parameters:
initialCapacity - the initial map capacity

MultiHashMap

public MultiHashMap(int initialCapacity,
                    float loadFactor)
Constructor.

Parameters:
initialCapacity - the initial map capacity
loadFactor - the amount 0.0-1.0 at which to resize the map

MultiHashMap

public MultiHashMap(Map<K,V> mapToCopy)
Constructor that copies the input map creating an independent copy.

The values are not cloned.

Parameters:
mapToCopy - a Map to copy

MultiHashMap

public MultiHashMap(MultiMap<K,V> mapToCopy)
Constructor that copies the input MultiMap creating an independent copy.

Each internal collection is also cloned.

NOTE: From Commons Collections 3.1 this method correctly copies a MultiMap to form a truly independent new map.

Parameters:
mapToCopy - a Map to copy
Method Detail

totalSize

public int totalSize()
Gets the total size of the map by counting all the values.

Returns:
the total size of the map counting all values
Since:
Commons Collections 3.1

getCollection

public Collection<V> getCollection(Object key)
Gets the collection mapped to the specified key. This method is a convenience method to typecast the result of get(key).

Parameters:
key - the key to retrieve
Returns:
the collection mapped to the key, null if no mapping
Since:
Commons Collections 3.1

size

public int size(Object key)
Gets the size of the collection mapped to the specified key.

Specified by:
size in interface MultiMap<K,V>
Parameters:
key - the key to get size for
Returns:
the size of the collection at the key, zero if key not in map
Since:
Commons Collections 3.1

iterator

public Iterator<V> iterator(Object key)
Gets an iterator for the collection mapped to the specified key.

Specified by:
iterator in interface MultiMap<K,V>
Parameters:
key - the key to get an iterator for
Returns:
the iterator of the collection at the key, empty iterator if key not in map
Since:
Commons Collections 3.1

put

public V put(K key,
             V value)
Adds the value to the collection associated with the specified key.

Unlike a normal Map the previous value is not replaced. Instead the new value is added to the collection stored against the key.

Specified by:
put in interface MultiMap<K,V>
Parameters:
key - the key to store against
value - the value to add to the collection at the key
Returns:
the value added if the map changed and null if the map did not change

putAll

public boolean putAll(K key,
                      Collection<? extends V> values)
Adds a collection of values to the collection associated with the specified key.

Specified by:
putAll in interface MultiMap<K,V>
Parameters:
key - the key to store against
values - the values to add to the collection at the key, null ignored
Returns:
true if this map changed
Since:
Commons Collections 3.1

containsValue

public boolean containsValue(Object value)
Checks whether the map contains the value specified.

This checks all collections15 against all keys for the value, and thus could be slow.

Specified by:
containsValue in interface MultiMap<K,V>
Parameters:
value - the value to search for
Returns:
true if the map contains the value

containsValue

public boolean containsValue(Object key,
                             Object value)
Checks whether the collection at the specified key contains the value.

Specified by:
containsValue in interface MultiMap<K,V>
Parameters:
value - the value to search for
key - the key against which to search for the value
Returns:
true if the map contains the value
Since:
Commons Collections 3.1

remove

public V remove(Object key,
                Object item)
Removes a specific value from map.

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, null will be returned from a subsequant get(key).

Specified by:
remove in interface MultiMap<K,V>
Parameters:
key - the key to remove from
item - the value to remove
Returns:
the value removed (which was passed in), null if nothing removed

clear

public void clear()
Clear the map.

This clears each collection in the map, and so may be slow.

Specified by:
clear in interface MultiMap<K,V>

size

public int size()
Description copied from interface: MultiMap
Gets the number of keys in this map.

Implementations return the count of keys in the map.

Specified by:
size in interface MultiMap<K,V>
Returns:
the number of key-collection mappings in this map

get

public Collection<V> get(Object key)
Description copied from interface: MultiMap
Gets the collection of values associated with the specified key.

The returned value will implement Collection. Implementations are free to declare that they return Collection subclasses such as List or Set.

Implementations return null if no values have been mapped to the key.

Implementations may choose to return a clone of the internal collection.

Specified by:
get in interface MultiMap<K,V>
Parameters:
key - the key to retrieve
Returns:
the Collection of values, implementations should return null for no mapping, but may return an empty collection

remove

public Collection<V> remove(Object key)
Description copied from interface: MultiMap
Removes all values associated with the specified key.

Implementations typically return null from a subsequent get(Object), however they may choose to return an empty collection.

Specified by:
remove in interface MultiMap<K,V>
Parameters:
key - the key to remove values from
Returns:
the Collection of values removed, implementations should return null for no mapping found, but may return an empty collection

isEmpty

public boolean isEmpty()
Description copied from interface: MultiMap
Returns true if this map contains no key-value mappings.

Specified by:
isEmpty in interface MultiMap<K,V>
Returns:
true if this map contains no key-value mappings.

containsKey

public boolean containsKey(Object key)
Description copied from interface: MultiMap
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.)

Specified by:
containsKey in interface MultiMap<K,V>
Parameters:
key - key whose presence in this map is to be tested.
Returns:
true if this map contains a mapping for the specified key.

putAll

public void putAll(Map<? extends K,? extends V> map)
Description copied from interface: MultiMap
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 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 unspecified if the specified map is modified while the operation is in progress.

Specified by:
putAll in interface MultiMap<K,V>
Parameters:
map - Mappings to be stored in this map.

putAll

public void putAll(MultiMap<? extends K,? extends V> map)
Description copied from interface: MultiMap
Copies all of the mappings from the specified multimap to this multimap (optional operation). The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key to collections15 of values in the specified multimap. The behavior of this operation is unspecified if the specified multimap is modified while the operation is in progress.

Specified by:
putAll in interface MultiMap<K,V>
Parameters:
map - Mappings to be stored in this map.

keySet

public Set<K> keySet()
Description copied from interface: MultiMap
Returns a set view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation), the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll retainAll, and clear operations. It does not support the add or addAll operations.

Specified by:
keySet in interface MultiMap<K,V>
Returns:
a set view of the keys contained in this map.

entrySet

public Set<Map.Entry<K,Collection<V>>> entrySet()
Description copied from interface: MultiMap
Returns a set view of the mappings contained in this map. Each element in the returned set is a Map.Entry. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation, or through the setValue operation on a map entry returned by the iterator) the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Specified by:
entrySet in interface MultiMap<K,V>
Returns:
a set view of the mappings contained in this map.

map

public Map<K,Collection<V>> map()
Description copied from interface: MultiMap
Returns a java.util.Map<K,Collection<V>> for this MultiMap.

Specified by:
map in interface MultiMap<K,V>
Returns:
the underlying java.util.Map for this MultiMap.

values

public Collection<V> values()
Gets a collection containing all the values in the map.

This returns a collection containing the combination of values from all keys.

Specified by:
values in interface MultiMap<K,V>
Returns:
a collection view of the values contained in this map

clone

public Object clone()
Clones the map creating an independent copy.

The clone will shallow clone the collections15 as well as the map.

Overrides:
clone in class Object
Returns:
the cloned map

equals

public boolean equals(Object obj)
Description copied from interface: MultiMap
Compares the specified object with this map for equality. Returns true if the given object is also a map and the two Maps represent the same mappings. More formally, two maps t1 and t2 represent the same mappings if t1.entrySet().equals(t2.entrySet()). This ensures that the equals method works properly across different implementations of the Map interface.

Specified by:
equals in interface MultiMap<K,V>
Overrides:
equals in class Object
Parameters:
obj - object to be compared for equality with this map.
Returns:
true if the specified object is equal to this map.

hashCode

public int hashCode()
Description copied from interface: MultiMap
Returns the hash code value for this map. The hash code of a map is defined to be the sum of the hashCodes of each entry in the map's entrySet view. This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two maps t1 and t2, as required by the general contract of Object.hashCode.

Specified by:
hashCode in interface MultiMap<K,V>
Overrides:
hashCode in class Object
Returns:
the hash code value for this map.
See Also:
Map.Entry#hashCode(), Object.hashCode(), Object.equals(Object), MultiMap.equals(Object)

createCollection

protected Collection<V> createCollection(Collection<? extends V> coll)
Creates a new instance of the map value Collection container.

This method can be overridden to use your own collection type.

Parameters:
coll - the collection to copy, may be null
Returns:
the new collection

toString

public String toString()
Overrides:
toString in class Object


Copyright © 2001-2010 Apache Software Foundation. All Rights Reserved.