org.apache.commons.collections4.multimap

## Class UnmodifiableMultiValuedMap<K,V>

- java.lang.Object
- - org.apache.commons.collections4.multimap.AbstractMultiValuedMapDecorator<K,V>
  - - org.apache.commons.collections4.multimap.UnmodifiableMultiValuedMap<K,V>

- Type Parameters:
    `K` - the type of key elements
    `V` - the type of value elements
  All Implemented Interfaces:
    Serializable, MultiValuedMap<K,V>, Unmodifiable

      public final class UnmodifiableMultiValuedMap<K,V>
      extends AbstractMultiValuedMapDecorator<K,V>
      implements Unmodifiable

  Decorates another `MultiValuedMap` to ensure it can't be altered.

  Attempts to modify it will result in an UnsupportedOperationException.

  Since:
    4.1
  See Also:
    Serialized Form

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete 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).
    `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.
    `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.
    `static <K,V> UnmodifiableMultiValuedMap<K,V>` | `unmodifiableMultiValuedMap(MultiValuedMap<? extends K,? extends V> map)` Factory method to create an unmodifiable MultiValuedMap.
    `Collection<V>` | `values()` Gets a `Collection` view of all values contained in this multi-valued map.

    - ### Methods inherited from class org.apache.commons.collections4.multimap.AbstractMultiValuedMapDecorator

      `containsKey, containsMapping, containsValue, decorated, equals, hashCode, isEmpty, size, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### unmodifiableMultiValuedMap

          public static <K,V> UnmodifiableMultiValuedMap<K,V> unmodifiableMultiValuedMap(MultiValuedMap<? extends K,? extends V> map)

      Factory method to create an unmodifiable MultiValuedMap.

      If the map passed in is already unmodifiable, it is returned.

      Type Parameters:
        `K` - the type of key elements
        `V` - the type of value elements
      Parameters:
        `map` - the map to decorate, may not be null
      Returns:
        an unmodifiable MultiValuedMap
      Throws:
        `NullPointerException` - if map is null

    - #### remove

          public Collection<V> remove(Object key)

      Description copied from interface: `MultiValuedMap`
      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.

      Specified by:
        `remove` in interface `MultiValuedMap<K,V>`
      Overrides:
        `remove` in class `AbstractMultiValuedMapDecorator<K,V>`
      Parameters:
        `key` - the key to remove values from
      Returns:
        the values that were removed

    - #### removeMapping

          public boolean removeMapping(Object key,
                                       Object item)

      Description copied from interface: `MultiValuedMap`
      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)`.

      Specified by:
        `removeMapping` in interface `MultiValuedMap<K,V>`
      Overrides:
        `removeMapping` in class `AbstractMultiValuedMapDecorator<K,V>`
      Parameters:
        `key` - the key to remove from
        `item` - the item to remove
      Returns:
        true if the mapping was removed, false otherwise

    - #### clear

          public void clear()

      Description copied from interface: `MultiValuedMap`
      Removes all of the mappings from this map (optional operation).

      The map will be empty after this call returns.

      Specified by:
        `clear` in interface `MultiValuedMap<K,V>`
      Overrides:
        `clear` in class `AbstractMultiValuedMapDecorator<K,V>`

    - #### get

          public Collection<V> get(K key)

      Description copied from interface: `MultiValuedMap`
      Returns a view collection of the values associated with the specified key.

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

      Specified by:
        `get` in interface `MultiValuedMap<K,V>`
      Overrides:
        `get` in class `AbstractMultiValuedMapDecorator<K,V>`
      Parameters:
        `key` - the key to retrieve
      Returns:
        the `Collection` of values, implementations should return an empty collection for no mapping

    - #### put

          public boolean put(K key,
                             V value)

      Description copied from interface: `MultiValuedMap`
      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.

      Specified by:
        `put` in interface `MultiValuedMap<K,V>`
      Overrides:
        `put` in class `AbstractMultiValuedMapDecorator<K,V>`
      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

    - #### keySet

          public Set<K> keySet()

      Description copied from interface: `MultiValuedMap`
      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.

      Specified by:
        `keySet` in interface `MultiValuedMap<K,V>`
      Overrides:
        `keySet` in class `AbstractMultiValuedMapDecorator<K,V>`
      Returns:
        a set view of the keys contained in this map

    - #### entries

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

      Description copied from interface: `MultiValuedMap`
      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.

      Specified by:
        `entries` in interface `MultiValuedMap<K,V>`
      Overrides:
        `entries` in class `AbstractMultiValuedMapDecorator<K,V>`
      Returns:
        a set view of the mappings contained in this map

    - #### keys

          public MultiSet<K> keys()

      Description copied from interface: `MultiValuedMap`
      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.

      Specified by:
        `keys` in interface `MultiValuedMap<K,V>`
      Overrides:
        `keys` in class `AbstractMultiValuedMapDecorator<K,V>`
      Returns:
        a multiset view of the keys contained in this map

    - #### values

          public Collection<V> values()

      Description copied from interface: `MultiValuedMap`
      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.

      Specified by:
        `values` in interface `MultiValuedMap<K,V>`
      Overrides:
        `values` in class `AbstractMultiValuedMapDecorator<K,V>`
      Returns:
        a collection view of the values contained in this multi-valued map

    - #### asMap

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

      Description copied from interface: `MultiValuedMap`
      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`.

      Specified by:
        `asMap` in interface `MultiValuedMap<K,V>`
      Overrides:
        `asMap` in class `AbstractMultiValuedMapDecorator<K,V>`
      Returns:
        a map view of the mappings in this multi-valued map

    - #### mapIterator

          public MapIterator<K,V> mapIterator()

      Description copied from interface: `MultiValuedMap`
      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.

      Specified by:
        `mapIterator` in interface `MultiValuedMap<K,V>`
      Overrides:
        `mapIterator` in class `AbstractMultiValuedMapDecorator<K,V>`
      Returns:
        a map iterator

    - #### putAll

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

      Description copied from interface: `MultiValuedMap`
      Adds a mapping to the specified key for all values contained in the given Iterable.
      Specified by:
        `putAll` in interface `MultiValuedMap<K,V>`
      Overrides:
        `putAll` in class `AbstractMultiValuedMapDecorator<K,V>`
      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

    - #### putAll

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

      Description copied from interface: `MultiValuedMap`
      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.

      Specified by:
        `putAll` in interface `MultiValuedMap<K,V>`
      Overrides:
        `putAll` in class `AbstractMultiValuedMapDecorator<K,V>`
      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

    - #### putAll

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

      Description copied from interface: `MultiValuedMap`
      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.

      Specified by:
        `putAll` in interface `MultiValuedMap<K,V>`
      Overrides:
        `putAll` in class `AbstractMultiValuedMapDecorator<K,V>`
      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

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