org.apache.commons.collections4

## Interface MultiValuedMap<K,V>

- All Known Subinterfaces:
    ListValuedMap<K,V>, SetValuedMap<K,V>
  All Known Implementing Classes:
    AbstractListValuedMap, AbstractMultiValuedMap, AbstractMultiValuedMapDecorator, AbstractSetValuedMap, ArrayListValuedHashMap, HashSetValuedHashMap, TransformedMultiValuedMap, UnmodifiableMultiValuedMap

      public interface MultiValuedMap<K,V>

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

  A `MultiValuedMap` 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:

       MultiValuedMap<K, String> map = new MultiValuedHashMap<K, String>();
       map.put(key, "A");
       map.put(key, "B");
       map.put(key, "C");
       Collection<String> coll = map.get(key);

  `coll` will be a collection containing "A", "B", "C".

  Since:
    4.1
  Version:
    $Id: MultiValuedMap.java 1716537 2015-11-25 20:27:24Z tn $

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Map<K,Collection<V>>` | `asMap()` Returns a view of this multi-valued map as a `Map` from each distinct key to the non-empty collection of that key's associated values.
    `void` | `clear()` Removes all of the mappings from this map (optional operation).
    `boolean` | `containsKey(Object key)` Returns `true` if this map contains a mapping for the specified key.
    `boolean` | `containsMapping(Object key, Object value)` Checks whether the map contains a mapping for the specified key and value.
    `boolean` | `containsValue(Object value)` Checks whether the map contains at least one mapping for the specified value.
    `Collection<Map.Entry<K,V>>` | `entries()` Returns a `Collection` view of the mappings contained in this multi-valued map.
    `Collection<V>` | `get(K key)` Returns a view collection of the values associated with the specified key.
    `boolean` | `isEmpty()` Returns `true` if this map contains no key-value mappings.
    `MultiSet<K>` | `keys()` Returns a `MultiSet` view of the keys contained in this multi-valued map.
    `Set<K>` | `keySet()` Returns a `Set` view of the keys contained in this multi-valued map.
    `MapIterator<K,V>` | `mapIterator()` Obtains a `MapIterator` over this multi-valued map.
    `boolean` | `put(K key, V value)` Adds a key-value mapping to this multi-valued map.
    `boolean` | `putAll(K key, Iterable<? extends V> values)` Adds a mapping to the specified key for all values contained in the given Iterable.
    `boolean` | `putAll(Map<? extends K,? extends V> map)` Copies all mappings from the specified map to this multi-valued map (optional operation).
    `boolean` | `putAll(MultiValuedMap<? extends K,? extends V> map)` Copies all mappings from the specified map to this multi-valued map (optional operation).
    `Collection<V>` | `remove(Object key)` Removes all values associated with the specified key.
    `boolean` | `removeMapping(Object key, Object item)` Removes a key-value mapping from the map.
    `int` | `size()` Gets the total size of the map.
    `Collection<V>` | `values()` Gets a `Collection` view of all values contained in this multi-valued map.

- - ### Method Detail

    - #### size

          int size()

      Gets the total size of the map.

      Implementations would return the total size of the map which is the count of the values from all keys.

      Returns:
        the total size of the map

    - #### isEmpty

          boolean isEmpty()

      Returns `true` if this map contains no key-value mappings.
      Returns:
        `true` if this map contains no key-value mappings

    - #### containsKey

          boolean containsKey(Object key)

      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.)
      Parameters:
        `key` - key whose presence in this map is to be tested
      Returns:
        true if this map contains a mapping for the specified key
      Throws:
        `NullPointerException` - if the specified key is null and this map does not permit null keys (optional)

    - #### containsValue

          boolean containsValue(Object value)

      Checks whether the map contains at least one mapping for the specified value.
      Parameters:
        `value` - the value to search for
      Returns:
        true if the map contains the value
      Throws:
        `NullPointerException` - if the value is null and null values are not supported by the used collection types (optional)

    - #### containsMapping

          boolean containsMapping(Object key,
                                Object value)

      Checks whether the map contains a mapping for the specified key and value.
      Parameters:
        `key` - the key to search for
        `value` - the value to search for
      Returns:
        true if the map contains the value

    - #### get

          Collection<V> get(K key)

      Returns a view collection of the values associated with the specified key.

      This method will return an empty collection if `containsKey(Object)` returns `false`. Changes to the returned collection will update the underlying `MultiValuedMap` and vice-versa.

      Parameters:
        `key` - the key to retrieve
      Returns:
        the `Collection` of values, implementations should return an empty collection for no mapping
      Throws:
        `NullPointerException` - if the key is null and null keys are invalid (optional)

    - #### put

          boolean put(K key,
                    V value)

      Adds a key-value mapping to this multi-valued map.

      Unlike a normal `Map` the previous value is not replaced. Instead the new value is added to the collection stored against the key. Depending on the collection type used, duplicate key-value mappings may be allowed.

      The method will return `true` if the size of the multi-valued map has been increased because of this operation.

      Parameters:
        `key` - the key to store against
        `value` - the value to add to the collection at the key
      Returns:
        true if the map changed as a result of this put operation, or false if the map already contained the key-value mapping and the collection type does not allow duplicate values, e.g. when using a Set
      Throws:
        `UnsupportedOperationException` - if the put operation is not supported by this multi-valued map, e.g. if it is unmodifiable
        `NullPointerException` - if the key or value is null and null is invalid (optional)
        `IllegalArgumentException` - if some aspect of the specified key or value prevents it from being stored in this multi-valued map

    - #### putAll

          boolean putAll(K key,
                       Iterable<? extends V> values)

      Adds a mapping to the specified key for all values contained in the given Iterable.
      Parameters:
        `key` - the key to store against
        `values` - the values to add to the collection at the key, may not be null
      Returns:
        true if the map changed as a result of this operation
      Throws:
        `NullPointerException` - if the specified iterable is null, or if this map does not permit null keys or values, and the specified key or values contain null (optional)

    - #### putAll

          boolean putAll(Map<? extends K,? extends V> map)

      Copies all mappings from the specified map to this multi-valued 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 undefined if the specified map is modified while the operation is in progress.

      Parameters:
        `map` - mappings to be stored in this map, may not be null
      Returns:
        true if the map changed as a result of this operation
      Throws:
        `UnsupportedOperationException` - if the `putAll` operation is not supported by this map
        `NullPointerException` - if the specified map is null, or if this map does not permit null keys or values, and the specified map contains null keys or values (optional)
        `IllegalArgumentException` - if some property of a key or value in the specified map prevents it from being stored in this map

    - #### putAll

          boolean putAll(MultiValuedMap<? extends K,? extends V> map)

      Copies all mappings from the specified map to this multi-valued 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 undefined if the specified map is modified while the operation is in progress.

      Parameters:
        `map` - mappings to be stored in this map, may not be null
      Returns:
        true if the map changed as a result of this operation
      Throws:
        `UnsupportedOperationException` - if the `putAll` operation is not supported by this map
        `NullPointerException` - if the specified map is null, or if this map does not permit null keys or values, and the specified map contains null keys or values (optional)
        `IllegalArgumentException` - if some property of a key or value in the specified map prevents it from being stored in this map

    - #### remove

          Collection<V> remove(Object key)

      Removes all values associated with the specified key.

      The returned collection may be modifiable, but updates will not be propagated to this multi-valued map. In case no mapping was stored for the specified key, an empty, unmodifiable collection will be returned.

      Parameters:
        `key` - the key to remove values from
      Returns:
        the values that were removed
      Throws:
        `UnsupportedOperationException` - if the map is unmodifiable
        `NullPointerException` - if the key is null and null keys are invalid (optional)

    - #### removeMapping

          boolean removeMapping(Object key,
                              Object item)

      Removes a key-value mapping from the 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 an empty collection from a subsequent `get(Object)`.

      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
        `NullPointerException` - if the key or value is null and null is invalid (optional)

    - #### clear

          void clear()

      Removes all of the mappings from this map (optional operation).

      The map will be empty after this call returns.

      Throws:
        `UnsupportedOperationException` - if the map is unmodifiable

    - #### entries

          Collection<Map.Entry<K,V>> entries()

      Returns a `Collection` view of the mappings contained in this multi-valued map.

      The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa.

      Returns:
        a set view of the mappings contained in this map

    - #### keys

          MultiSet<K> keys()

      Returns a `MultiSet` view of the keys contained in this multi-valued map.

      The `MultiSet.getCount(Object)` method of the returned multiset will give the same result a calling `get(Object).size()` for the same key.

      This multiset is backed by the map, so any changes in the map are reflected in the multiset.

      Returns:
        a multiset view of the keys contained in this map

    - #### keySet

          Set<K> keySet()

      Returns a `Set` view of the keys contained in this multi-valued 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 result of the iteration is 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.

      Returns:
        a set view of the keys contained in this map

    - #### values

          Collection<V> values()

      Gets a `Collection` view of all values contained in this multi-valued map.

      Implementations typically return a collection containing the combination of values from all keys.

      Returns:
        a collection view of the values contained in this multi-valued map

    - #### asMap

          Map<K,Collection<V>> asMap()

      Returns a view of this multi-valued map as a `Map` from each distinct key to the non-empty collection of that key's associated values.

      Note that `this.asMap().get(k)` is equivalent to `this.get(k)` only when `k` is a key contained in the multi-valued map; otherwise it returns `null` as opposed to an empty collection.

      Changes to the returned map or the collections that serve as its values will update the underlying multi-valued map, and vice versa. The map does not support `put` or `putAll`, nor do its entries support `setValue`.

      Returns:
        a map view of the mappings in this multi-valued map

    - #### mapIterator

          MapIterator<K,V> mapIterator()

      Obtains a `MapIterator` over this multi-valued map.

      A map iterator is an efficient way of iterating over maps. There is no need to access the entries collection or use `Map.Entry` objects.

      Returns:
        a map iterator

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