## org.apache.commons.collections
Class MultiHashMap

    java.lang.Object
      java.util.AbstractMap
          java.util.HashMap
              org.apache.commons.collections.MultiHashMap

All Implemented Interfaces:
  Cloneable, Map, MultiMap, Serializable

public class MultiHashMap
extends HashMap
implements MultiMap

`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.20 $ $Date: 2004/06/09 22:11:54 $
Author:
  Christopher Berry, James Strachan, Steve Downey, Stephen Colebourne, Julien Buret, Serhiy Yevtushenko
See Also:
  Serialized Form

Nested Class Summary

Nested classes inherited from class java.util.Map
`Map.Entry`

Constructor Summary
`MultiHashMap()` Constructor.
`MultiHashMap(int initialCapacity)` Constructor.
`MultiHashMap(int initialCapacity, float loadFactor)` Constructor.
`MultiHashMap(Map 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` `createCollection(Collection coll)` Creates a new instance of the map value Collection container.
`Collection` `getCollection(Object key)` Gets the collection mapped to the specified key.
`Iterator` `iterator(Object key)` Gets an iterator for the collection mapped to the specified key.
`Object` `put(Object key, Object value)` Adds the value to the collection associated with the specified key.
`boolean` `putAll(Object key, Collection values)` Adds a collection of values to the collection associated with the specified key.
`Object` `remove(Object key, Object item)` Removes a specific value from map.
`int` `size(Object 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` `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 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 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.

  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 iterator(Object 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 Object 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 `MultiMap`
  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(Object key,
                          Collection 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 `MultiMap`
  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 Object 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`
  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`

### values

    public Collection 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`
  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.

  Returns:
    the cloned map

### createCollection

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

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