Package org.apache.commons.collections4.multimap

# Class AbstractMultiValuedMap<K,V>

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

Type Parameters:
  `K` - the type of the keys in this map
  `V` - the type of the values in this map

All Implemented Interfaces:
  `MultiValuedMap<K,V>`

Direct Known Subclasses:
  `AbstractListValuedMap`, `AbstractSetValuedMap`

public abstract class AbstractMultiValuedMap<K,V> extends Object implements MultiValuedMap<K,V>
Abstract implementation of the `MultiValuedMap` interface to simplify the creation of subclass implementations.

Subclasses specify a Map implementation to use as the internal storage.

Since:
  4.1

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AbstractMultiValuedMap()`
  Constructor needed for subclass serialisation.
  `protected`
  `AbstractMultiValuedMap(Map<K,? extends Collection<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 abstract Collection<V>`
  `createCollection()`
  Creates a new Collection typed for a given subclass.
  `protected void`
  `doReadObject(ObjectInputStream in)`
  Read the map in using a custom routine.
  `protected void`
  `doWriteObject(ObjectOutputStream out)`
  Write the map out using a custom routine.
  `Collection<Map.Entry<K,V>>`
  `entries()`
  Returns a `Collection` view of the mappings contained in this multivalued map.
  `boolean`
  `equals(Object obj)`
  `Collection<V>`
  `get(K key)`
  Gets the collection of values associated with the specified key.
  `protected Map<K,? extends Collection<V>>`
  `getMap()`
  Gets the map being wrapped.
  `int`
  `hashCode()`
  `boolean`
  `isEmpty()`
  Returns `true` if this map contains no key-value mappings.
  `MultiSet<K>`
  `keys()`
  Returns a `MultiSet` view of the key mapping contained in this 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 the value to the collection associated with the specified key.
  `boolean`
  `putAll(Map<? extends K,? extends V> map)`
  Copies all of the mappings from the specified map to this map.
  `boolean`
  `putAll(K key, Iterable<? extends V> values)`
  Adds Iterable values to the collection associated with the specified key.
  `boolean`
  `putAll(MultiValuedMap<? extends K,? extends V> map)`
  Copies all of the mappings from the specified MultiValuedMap to this map.
  `Collection<V>`
  `remove(Object key)`
  Removes all values associated with the specified key.
  `boolean`
  `removeMapping(Object key, Object value)`
  Removes a specific key/value mapping from the multivalued map.
  `protected void`
  `setMap(Map<K,? extends Collection<V>> map)`
  Sets the map being wrapped.
  `int`
  `size()`
  Gets the total size of the map.
  `String`
  `toString()`
  `Collection<V>`
  `values()`
  Gets a collection containing all the values in the map.

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

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

- ## Constructor Details

  - ### AbstractMultiValuedMap

    protected AbstractMultiValuedMap()
    Constructor needed for subclass serialisation.

  - ### AbstractMultiValuedMap

    protected AbstractMultiValuedMap(Map<K,? extends Collection<V>> map)
    Constructor that wraps (not copies).
    Parameters:
      `map` - the map to wrap, 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

  - ### createCollection

    protected abstract Collection<V> createCollection()
    Creates a new Collection typed for a given subclass.
    Returns:
      a new Collection typed for a given subclass.

  - ### doReadObject

    protected void doReadObject(ObjectInputStream in) throws IOException, ClassNotFoundException
    Read the map in using a custom routine.
    Parameters:
      `in` - the input stream
    Throws:
      `IOException` - any of the usual I/O related exceptions
      `ClassNotFoundException` - if the stream contains an object which class cannot be loaded
      `ClassCastException` - if the stream does not contain the correct objects

  - ### doWriteObject

    protected void doWriteObject(ObjectOutputStream out) throws IOException
    Write the map out using a custom routine.
    Parameters:
      `out` - the output stream
    Throws:
      `IOException` - any of the usual I/O related exceptions

  - ### 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 obj)
    Overrides:
      `equals` in class `Object`

  - ### get

    public Collection<V> get(K key)
    Gets the collection of values associated with the specified key. This would return an empty collection in case the mapping is not present
    Specified by:
      `get` in interface `MultiValuedMap<K,V>`
    Parameters:
      `key` - the key to retrieve
    Returns:
      the `Collection` of values, will return an empty `Collection` for no mapping

  - ### getMap

    protected Map<K,? extends Collection<V>> getMap()
    Gets the map being wrapped.
    Returns:
      the wrapped map

  - ### 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()
    Returns a `MultiSet` view of the key mapping contained in this map.

    Returns a MultiSet of keys with its values count as the count of the MultiSet. This multiset is backed by the map, so any changes in the map is reflected here. Any method which modifies this multiset like `add`, `remove`, `Iterator.remove()` etc throws `UnsupportedOperationException`.

    Specified by:
      `keys` in interface `MultiValuedMap<K,V>`
    Returns:
      a bag view of the key mapping 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)
    Adds the value to the collection associated with the specified key.

    Unlike a normal `Map` the previous value is not replaced. Instead the new value is added to the collection stored against the key.

    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:
      the value added if the map changed and null if the map did not change

  - ### putAll

    public boolean putAll(K key, Iterable<? extends V> values)
    Adds Iterable values to the collection associated with the specified key.
    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 this map changed
    Throws:
      `NullPointerException` - if values is null

  - ### putAll

    public boolean putAll(Map<? extends K,? extends V> map)
    Copies all of the mappings from the specified map to this map. 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
    Throws:
      `NullPointerException` - if map is null

  - ### putAll

    public boolean putAll(MultiValuedMap<? extends K,? extends V> map)
    Copies all of the mappings from the specified MultiValuedMap to this map. 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
    Throws:
      `NullPointerException` - if map is null

  - ### remove

    public Collection<V> remove(Object key)
    Removes all values associated with the specified key.

    A subsequent `get(Object)` would return an empty collection.

    Specified by:
      `remove` in interface `MultiValuedMap<K,V>`
    Parameters:
      `key` - the key to remove values from
    Returns:
      the `Collection` of values removed, will return an empty, unmodifiable collection for no mapping found

  - ### removeMapping

    public boolean removeMapping(Object key, Object value)
    Removes a specific key/value mapping from the multivalued map.

    The value 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, an empty collection would be returned from a subsequent `get(Object)`.

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

  - ### setMap

    protected void setMap(Map<K,? extends Collection<V>> map)
    Sets the map being wrapped.

    NOTE: this method should only be used during deserialization

    Parameters:
      `map` - the map to wrap

  - ### size

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

    This implementation does not cache the total size of the multivalued map, but rather calculates it by iterating over the entries of the underlying map.

    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()
    Gets a collection containing all the values in the map.

    Returns a collection containing all the values from all keys.

    Specified by:
      `values` in interface `MultiValuedMap<K,V>`
    Returns:
      a collection view of the values contained in this map