org.apache.commons.collections

## Class MultiHashMap

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

- All Implemented Interfaces:
    Serializable, Cloneable, Map, MultiMap

  Deprecated.
  Class now available as MultiValueMap in map subpackage. This version is due to be removed in collections v4.0.

      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: 646777 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $
  Author:
    Christopher Berry, James Strachan, Steve Downey, Stephen Colebourne, Julien Buret, Serhiy Yevtushenko, Robert Ribnitz
  See Also:
    Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class java.util.AbstractMap

      `AbstractMap.SimpleEntry, AbstractMap.SimpleImmutableEntry`

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

      `Map.Entry`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MultiHashMap()` Deprecated. Constructor.
    `MultiHashMap(int initialCapacity)` Deprecated. Constructor.
    `MultiHashMap(int initialCapacity, float loadFactor)` Deprecated. Constructor.
    `MultiHashMap(Map mapToCopy)` Deprecated. Constructor that copies the input map creating an independent copy.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()` Deprecated. Clear the map.
    `Object` | `clone()` Deprecated. Clones the map creating an independent copy.
    `boolean` | `containsValue(Object value)` Deprecated. Checks whether the map contains the value specified.
    `boolean` | `containsValue(Object key, Object value)` Deprecated. Checks whether the collection at the specified key contains the value.
    `protected Collection` | `createCollection(Collection coll)` Deprecated. Creates a new instance of the map value Collection container.
    `Collection` | `getCollection(Object key)` Deprecated. Gets the collection mapped to the specified key.
    `Iterator` | `iterator(Object key)` Deprecated. Gets an iterator for the collection mapped to the specified key.
    `Object` | `put(Object key, Object value)` Deprecated. Adds the value to the collection associated with the specified key.
    `void` | `putAll(Map map)` Deprecated. Override superclass to ensure that MultiMap instances are correctly handled.
    `boolean` | `putAll(Object key, Collection values)` Deprecated. Adds a collection of values to the collection associated with the specified key.
    `Object` | `remove(Object key, Object item)` Deprecated. Removes a specific value from map.
    `int` | `size(Object key)` Deprecated. Gets the size of the collection mapped to the specified key.
    `int` | `totalSize()` Deprecated. Gets the total size of the map by counting all the values.
    `Collection` | `values()` Deprecated. Gets a collection containing all the values in the map.

    - ### Methods inherited from class java.util.HashMap

      `containsKey, entrySet, get, isEmpty, keySet, 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`

- - ### Constructor Detail

    - #### MultiHashMap

          public MultiHashMap()

      Deprecated.
      Constructor.

    - #### MultiHashMap

          public MultiHashMap(int initialCapacity)

      Deprecated.
      Constructor.
      Parameters:
        `initialCapacity` - the initial map capacity

    - #### MultiHashMap

          public MultiHashMap(int initialCapacity,
                      float loadFactor)

      Deprecated.
      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)

      Deprecated.
      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. NOTE: From Commons Collections 3.2 this method delegates to the newly added putAll(Map) override method.

      Parameters:
        `mapToCopy` - a Map to copy

  - ### Method Detail

    - #### totalSize

          public int totalSize()

      Deprecated.
      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)

      Deprecated.
      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)

      Deprecated.
      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)

      Deprecated.
      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)

      Deprecated.
      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`
      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 void putAll(Map map)

      Deprecated.
      Override superclass to ensure that MultiMap instances are correctly handled.

      NOTE: Prior to version 3.2, putAll(map) did not work properly when passed a MultiMap.

      Specified by:
        `putAll` in interface `Map`
      Overrides:
        `putAll` in class `HashMap`
      Parameters:
        `map` - the map to copy (either a normal or multi map)

    - #### putAll

          public boolean putAll(Object key,
                       Collection values)

      Deprecated.
      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)

      Deprecated.
      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`
      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)

      Deprecated.
      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)

      Deprecated.
      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()

      Deprecated.
      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 values()

      Deprecated.
      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`
      Overrides:
        `values` in class `HashMap`
      Returns:
        a collection view of the values contained in this map

    - #### clone

          public Object clone()

      Deprecated.
      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 createCollection(Collection coll)

      Deprecated.
      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–2015 The Apache Software Foundation. All rights reserved.