Package 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 behavior.

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

Since:
  4.1
See Also:
  - Serialized Form

- ## Constructor Summary

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

- ## 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()`
  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 multivalued map.
  `Collection<Map.Entry<K,V>>`
  `entries()`
  Returns a `Collection` view of the mappings contained in this multivalued map.
  `boolean`
  `equals(Object object)`
  `Collection<V>`
  `get(K key)`
  Gets 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 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)`
  Adds a key-value mapping to this multivalued map.
  `boolean`
  `putAll(Map<? extends K,? extends V> map)`
  Copies all mappings from the specified map to this multivalued map (optional operation).
  `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(MultiValuedMap<? extends K,? extends V> map)`
  Copies all mappings from the specified map to this multivalued 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 multivalued map.

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

- ## Constructor Details

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

  - ### 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>`
    Returns:
      A map view of the mappings in this multivalued map.

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

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

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

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

  - ### decorated

    protected MultiValuedMap<K,V> decorated()
    The decorated multivalued map.
    Returns:
      The map to decorate

  - ### 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>`
    Returns:
      A set view of the mappings contained in this map.

  - ### equals

    public boolean equals(Object object)
    Overrides:
      `equals` in class `Object`

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

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

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

  - ### 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>`
    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>`
    Returns:
      A set view of the keys contained in this map.

  - ### mapIterator

    public MapIterator<K,V> mapIterator()
    Description copied from interface: `MultiValuedMap`
    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.

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

  - ### put

    public boolean put(K key, V value)
    Description copied from interface: `MultiValuedMap`
    Adds a key-value mapping to this multivalued 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 multivalued 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, for example when using a Set.

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

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

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

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### 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>`
    Returns:
      A collection view of the values contained in this multivalued map.