org.apache.commons.collections4.multimap

## Class AbstractMultiValuedMapDecorator<K,V>

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

- Type Parameters:
    `K` - the type of key elements
    `V` - the type of value elements
  All Implemented Interfaces:
    Serializable, MultiValuedMap<K,V>
  Direct Known Subclasses:
    TransformedMultiValuedMap, UnmodifiableMultiValuedMap

      public abstract class AbstractMultiValuedMapDecorator<K,V>
      extends Object
      implements MultiValuedMap<K,V>, Serializable

  Decorates another `MultiValuedMap` to provide additional behaviour.

  Each method call made on this `MultiValuedMap` is forwarded to the decorated `MultiValuedMap`. This class is used as a framework to build to extensions such as synchronized and unmodifiable behaviour.

  Since:
    4.1
  Version:
    $Id: AbstractMultiValuedMapDecorator.java 1715302 2015-11-19 23:08:01Z tn $
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractMultiValuedMapDecorator(MultiValuedMap<K,V> map)` Constructor that wraps (not copies).

  - ### 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.
    `protected MultiValuedMap<K,V>` | `decorated()` The decorated multi-valued map.
    `Collection<Map.Entry<K,V>>` | `entries()` Returns a `Collection` view of the mappings contained in this multi-valued map.
    `boolean` | `equals(Object object)`
    `Collection<V>` | `get(K key)` Returns a view collection of the values associated with the specified key.
    `int` | `hashCode()`
    `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.
    `String` | `toString()`
    `Collection<V>` | `values()` Gets a `Collection` view of all values contained in this multi-valued map.

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

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

- - ### Constructor Detail

    - #### AbstractMultiValuedMapDecorator

          protected AbstractMultiValuedMapDecorator(MultiValuedMap<K,V> map)

      Constructor that wraps (not copies).
      Parameters:
        `map` - the map to decorate, must not be null
      Throws:
        `NullPointerException` - if the map is null

  - ### Method Detail

    - #### decorated

          protected MultiValuedMap<K,V> decorated()

      The decorated multi-valued map.
      Returns:
        the map to decorate

    - #### size

          public int size()

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

      Specified by:
        `size` in interface `MultiValuedMap<K,V>`
      Returns:
        the total size of the map

    - #### isEmpty

          public boolean isEmpty()

      Description copied from interface: `MultiValuedMap`
      Returns `true` if this map contains no key-value mappings.
      Specified by:
        `isEmpty` in interface `MultiValuedMap<K,V>`
      Returns:
        `true` if this map contains no key-value mappings

    - #### containsKey

          public boolean containsKey(Object key)

      Description copied from interface: `MultiValuedMap`
      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.)
      Specified by:
        `containsKey` in interface `MultiValuedMap<K,V>`
      Parameters:
        `key` - key whose presence in this map is to be tested
      Returns:
        true if this map contains a mapping for the specified key

    - #### containsValue

          public boolean containsValue(Object value)

      Description copied from interface: `MultiValuedMap`
      Checks whether the map contains at least one mapping for the specified value.
      Specified by:
        `containsValue` in interface `MultiValuedMap<K,V>`
      Parameters:
        `value` - the value to search for
      Returns:
        true if the map contains the value

    - #### containsMapping

          public boolean containsMapping(Object key,
                                Object value)

      Description copied from interface: `MultiValuedMap`
      Checks whether the map contains a mapping for the specified key and value.
      Specified by:
        `containsMapping` in interface `MultiValuedMap<K,V>`
      Parameters:
        `key` - the key to search for
        `value` - the value to search for
      Returns:
        true if the map contains the value

    - #### 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>`
      Parameters:
        `key` - the key to retrieve
      Returns:
        the `Collection` of values, implementations should return an empty collection for no mapping

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

    - #### 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>`
      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>`
      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>`
      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>`
      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>`
      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>`
      Returns:
        a map view of the mappings in this multi-valued map

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

    - #### 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>`
      Returns:
        a map iterator

    - #### equals

          public boolean equals(Object object)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

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