org.apache.commons.collections
Class MultiHashMap<K,V>

java.lang.Object
  java.util.AbstractMap<K,V>
      java.util.HashMap
          org.apache.commons.collections.MultiHashMap<K,V>

All Implemented Interfaces:

Serializable, Cloneable, Map, MultiMap<K,V>

public class MultiHashMap<K,V>
extends HashMap
implements MultiMap<K,V>

MultiHashMap is the default implementation of the MultiMap interface.

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.

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:

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

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

Since:

Commons Collections 2.0

Version:

$Revision: 1.1.1.1 $ $Date: 2005/05/23 04:33:14 $

Author:

Christopher Berry, James Strachan, Steve Downey, Stephen Colebourne, Julien Buret, Matt Hall, John Watkinson, Serhiy Yevtushenko

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

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.

Method Summary

void	clear() Clear the map.
Object	clone() Clones the map creating an independent copy.
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<V> coll) Creates a new instance of the map value Collection container.
Collection<V>	getCollection(K key) Gets the collection mapped to the specified key.
Iterator<V>	iterator(K key) Gets an iterator for the collection mapped to the specified key.
V	put(Object key, Object value) Adds the value to the collection associated with the specified key.
boolean	putAll(K key, Collection<V> values) Adds a collection of values to the collection associated with the specified key.
V	remove(K key, V item) Removes a specific value from map.
int	size(K key) Gets the size of the collection mapped to the specified key.
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.util.HashMap

containsKey, entrySet, get, isEmpty, keySet, putAll, remove, size

Methods inherited from class java.util.AbstractMap

equals, hashCode, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.commons.collections.MultiMap

get, remove, size

Methods inherited from interface java.util.Map

containsKey, entrySet, equals, hashCode, isEmpty, keySet, putAll

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.

This method performs different behaviour depending on whether the map specified is a MultiMap or not. If a MultiMap is specified, each internal collection is also cloned. If the specified map only implements Map, then the values are not 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(K 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(K key)

Gets the size of the collection mapped to the specified key.

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(K key)

Gets an iterator for the collection mapped to the specified key.

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(Object key,
             Object 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 Map

Specified by:

put in interface MultiMap<K,V>

Overrides:

put in class HashMap

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<V> values)

Adds a collection of values to the collection associated with the specified key.

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 collections against all keys for the value, and thus could be slow.

Specified by:

containsValue in interface Map

Specified by:

containsValue in interface MultiMap<K,V>

Overrides:

containsValue in class HashMap

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.

Parameters:

value - the value to search for

Returns:

true if the map contains the value

Since:

Commons Collections 3.1

remove

public V remove(K key,
                V 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 Map

Overrides:

clear in class HashMap

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 Map

Specified by:

values in interface MultiMap<K,V>

Overrides:

values in class HashMap

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 collections as well as the map.

Overrides:

clone in class HashMap

Returns:

the cloned map

createCollection

protected Collection<V> createCollection(Collection<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