Package 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

  Modifier and Type
  Method
  Description
  `Map<K,Collection<V>>`
  `asMap()`
  Returns a view of this multivalued map as a `Map` from each distinct key to the non-empty collection of that key's associated values.
  `void`
  `clear()`
  Always throws `UnsupportedOperationException`.
  `Collection<Map.Entry<K,V>>`
  `entries()`
  Returns a `Collection` view of the mappings contained in this multivalued map.
  `Collection<V>`
  `get(K key)`
  Gets a view collection of the values associated with the specified key.
  `MultiSet<K>`
  `keys()`
  Returns a `MultiSet` view of the keys contained in this multivalued map.
  `Set<K>`
  `keySet()`
  Returns a `Set` view of the keys contained in this multivalued map.
  `MapIterator<K,V>`
  `mapIterator()`
  Obtains a `MapIterator` over this multivalued map.
  `boolean`
  `put(K key, V value)`
  Always throws `UnsupportedOperationException`.
  `boolean`
  `putAll(Map<? extends K,? extends V> map)`
  Always throws `UnsupportedOperationException`.
  `boolean`
  `putAll(K key, Iterable<? extends V> values)`
  Always throws `UnsupportedOperationException`.
  `boolean`
  `putAll(MultiValuedMap<? extends K,? extends V> map)`
  Always throws `UnsupportedOperationException`.
  `Collection<V>`
  `remove(Object key)`
  Always throws `UnsupportedOperationException`.
  `boolean`
  `removeMapping(Object key, Object item)`
  Always throws `UnsupportedOperationException`.
  `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 multivalued 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`

  ### Methods inherited from interface org.apache.commons.collections4.MultiValuedMap

  `inverted`

- ## Method Details

  - ### 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

  - ### asMap

    public Map<K,Collection<V>> asMap()
    Description copied from interface: `MultiValuedMap`
    Returns a view of this multivalued 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 multivalued 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 multivalued 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 multivalued map.

  - ### clear

    public void clear()
    Always throws `UnsupportedOperationException`.
    Specified by:
      `clear` in interface `MultiValuedMap<K,V>`
    Overrides:
      `clear` in class `AbstractMultiValuedMapDecorator<K,V>`
    Throws:
      `UnsupportedOperationException` - Always thrown.

  - ### entries

    public Collection<Map.Entry<K,V>> entries()
    Description copied from interface: `MultiValuedMap`
    Returns a `Collection` view of the mappings contained in this multivalued 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.

  - ### get

    public Collection<V> get(K key)
    Description copied from interface: `MultiValuedMap`
    Gets 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.

  - ### keys

    public MultiSet<K> keys()
    Description copied from interface: `MultiValuedMap`
    Returns a `MultiSet` view of the keys contained in this multivalued 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.

  - ### keySet

    public Set<K> keySet()
    Description copied from interface: `MultiValuedMap`
    Returns a `Set` view of the keys contained in this multivalued 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.

  - ### mapIterator

    public MapIterator<K,V> mapIterator()
    Obtains a `MapIterator` over this multivalued 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.

    The returned map iterator's `MapIterator.setValue(Object)` method is not supported and will throw an `UnsupportedOperationException`.

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

  - ### put

    public boolean put(K key, V value)
    Always throws `UnsupportedOperationException`.
    Specified by:
      `put` in interface `MultiValuedMap<K,V>`
    Overrides:
      `put` in class `AbstractMultiValuedMapDecorator<K,V>`
    Parameters:
      `key` - Ignored.
      `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, for example when using a Set.
    Throws:
      `UnsupportedOperationException` - Always thrown.

  - ### putAll

    public boolean putAll(K key, Iterable<? extends V> values)
    Always throws `UnsupportedOperationException`.
    Specified by:
      `putAll` in interface `MultiValuedMap<K,V>`
    Overrides:
      `putAll` in class `AbstractMultiValuedMapDecorator<K,V>`
    Parameters:
      `key` - Ignored.
      `values` - Ignored.
    Returns:
      true if the map changed as a result of this operation.
    Throws:
      `UnsupportedOperationException` - Always thrown.

  - ### putAll

    public boolean putAll(Map<? extends K,? extends V> map)
    Always throws `UnsupportedOperationException`.
    Specified by:
      `putAll` in interface `MultiValuedMap<K,V>`
    Overrides:
      `putAll` in class `AbstractMultiValuedMapDecorator<K,V>`
    Parameters:
      `map` - Ignored.
    Returns:
      true if the map changed as a result of this operation.
    Throws:
      `UnsupportedOperationException` - Always thrown.

  - ### putAll

    public boolean putAll(MultiValuedMap<? extends K,? extends V> map)
    Always throws `UnsupportedOperationException`.
    Specified by:
      `putAll` in interface `MultiValuedMap<K,V>`
    Overrides:
      `putAll` in class `AbstractMultiValuedMapDecorator<K,V>`
    Parameters:
      `map` - Ignored.
    Returns:
      true if the map changed as a result of this operation.
    Throws:
      `UnsupportedOperationException` - Always thrown.

  - ### remove

    public Collection<V> remove(Object key)
    Always throws `UnsupportedOperationException`.
    Specified by:
      `remove` in interface `MultiValuedMap<K,V>`
    Overrides:
      `remove` in class `AbstractMultiValuedMapDecorator<K,V>`
    Parameters:
      `key` - Ignored.
    Returns:
      The values that were removed.
    Throws:
      `UnsupportedOperationException` - Always thrown.

  - ### removeMapping

    public boolean removeMapping(Object key, Object item)
    Always throws `UnsupportedOperationException`.
    Specified by:
      `removeMapping` in interface `MultiValuedMap<K,V>`
    Overrides:
      `removeMapping` in class `AbstractMultiValuedMapDecorator<K,V>`
    Parameters:
      `key` - Ignored.
      `item` - Ignored.
    Returns:
      true if the mapping was removed, false otherwise.
    Throws:
      `UnsupportedOperationException` - Always thrown.

  - ### values

    public Collection<V> values()
    Description copied from interface: `MultiValuedMap`
    Gets a `Collection` view of all values contained in this multivalued 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 multivalued map.