org.apache.commons.collections4

## Interface MultiMap<K,V>

- All Superinterfaces:
    Get<K,Object>, IterableGet<K,Object>, IterableMap<K,Object>, Map<K,Object>, Put<K,Object>
  All Known Implementing Classes:
    MultiValueMap

  Deprecated.
  since 4.1, use `MultiValuedMap` instead

      @Deprecated
      public interface MultiMap<K,V>
      extends IterableMap<K,Object>

  Defines a map that holds a collection of values against each key.

  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 MultiValueMap();
       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:
    2.0
  Version:
    $Id: MultiMap.java 1683018 2015-06-01 22:41:31Z tn $

- - ### Nested Class Summary

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

      `Map.Entry<K,V>`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `containsValue(Object value)` Deprecated. Checks whether the map contains the value specified.
    `Object` | `get(Object key)` Deprecated. Gets the collection of values associated with the specified key.
    `Object` | `put(K key, Object value)` Deprecated. Adds the value to the collection associated with the specified key.
    `Object` | `remove(Object key)` Deprecated. Removes all values associated with the specified key.
    `boolean` | `removeMapping(K key, V item)` Deprecated. Removes a specific value from map.
    `int` | `size()` Deprecated. Gets the number of keys in this map.
    `Collection<Object>` | `values()` Deprecated. Gets a collection containing all the values in the map.

    - ### Methods inherited from interface java.util.Map

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

    - ### Methods inherited from interface org.apache.commons.collections4.Put

      `clear, putAll`

    - ### Methods inherited from interface org.apache.commons.collections4.IterableGet

      `mapIterator`

    - ### Methods inherited from interface org.apache.commons.collections4.Get

      `containsKey, entrySet, isEmpty, keySet`

- - ### Method Detail

    - #### removeMapping

          boolean removeMapping(K key,
                              V 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, implementations typically return `null` from a subsequent `get(Object)`, however they may choose to return an empty collection.

      Parameters:
        `key` - the key to remove from
        `item` - the item to remove
      Returns:
        `true` if the mapping was removed, `false` otherwise
      Throws:
        `UnsupportedOperationException` - if the map is unmodifiable
        `ClassCastException` - if the key or value is of an invalid type
        `NullPointerException` - if the key or value is null and null is invalid
      Since:
        4.0 (signature in previous releases: V remove(K, V))

    - #### size

          int size()

      Deprecated.
      Gets the number of keys in this map.

      Implementations typically return only the count of keys in the map This cannot be mandated due to backwards compatibility of this interface.

      Specified by:
        `size` in interface `Get<K,Object>`
      Specified by:
        `size` in interface `Map<K,Object>`
      Returns:
        the number of key-collection mappings in this map
      See Also:
        `Map.size()`

    - #### get

          Object get(Object key)

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

      Specified by:
        `get` in interface `Get<K,Object>`
      Specified by:
        `get` in interface `Map<K,Object>`
      Parameters:
        `key` - the key to retrieve
      Returns:
        the `Collection` of values, implementations should return `null` for no mapping, but may return an empty collection
      Throws:
        `ClassCastException` - if the key is of an invalid type
        `NullPointerException` - if the key is null and null keys are invalid
      See Also:
        `Map.get(Object)`

    - #### containsValue

          boolean containsValue(Object value)

      Deprecated.
      Checks whether the map contains the value specified.

      Implementations typically check all collections against all keys for the value. This cannot be mandated due to backwards compatibility of this interface.

      Specified by:
        `containsValue` in interface `Get<K,Object>`
      Specified by:
        `containsValue` in interface `Map<K,Object>`
      Parameters:
        `value` - the value to search for
      Returns:
        true if the map contains the value
      Throws:
        `ClassCastException` - if the value is of an invalid type
        `NullPointerException` - if the value is null and null value are invalid
      See Also:
        `Map.containsValue(Object)`

    - #### put

          Object put(K 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. The collection may be a `List`, `Set` or other collection dependent on implementation.

      Specified by:
        `put` in interface `Map<K,Object>`
      Specified by:
        `put` in interface `Put<K,Object>`
      Parameters:
        `key` - the key to store against
        `value` - the value to add to the collection at the key
      Returns:
        typically the value added if the map changed and null if the map did not change
      Throws:
        `UnsupportedOperationException` - if the map is unmodifiable
        `ClassCastException` - if the key or value is of an invalid type
        `NullPointerException` - if the key or value is null and null is invalid
        `IllegalArgumentException` - if the key or value is invalid
      See Also:
        `Map.put(Object, Object)`

    - #### remove

          Object remove(Object key)

      Deprecated.
      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 `Get<K,Object>`
      Specified by:
        `remove` in interface `Map<K,Object>`
      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
      Throws:
        `UnsupportedOperationException` - if the map is unmodifiable
        `ClassCastException` - if the key is of an invalid type
        `NullPointerException` - if the key is null and null keys are invalid
      See Also:
        `Map.remove(Object)`

    - #### values

          Collection<Object> values()

      Deprecated.
      Gets a collection containing all the values in the map.

      Implementations typically return a collection containing the combination of values from all keys. This cannot be mandated due to backwards compatibility of this interface.

      Specified by:
        `values` in interface `Get<K,Object>`
      Specified by:
        `values` in interface `Map<K,Object>`
      Returns:
        a collection view of the values contained in this map
      See Also:
        `Map.values()`

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.