Package org.apache.commons.collections

Interface MultiMap

All Superinterfaces:
Map
All Known Implementing Classes:
MultiHashMap, MultiValueMap
@Deprecated(since="2021-04-30") public interface MultiMap extends Map
Deprecated.
Apache Commons Collections version 3.x is being deprecated from AEMaaCS. The upgraded version 4.4 of Commons Collections is already included as replacement. Customers are advised to upgrade to this version of the library. Please note: the package name was changed to org.apache.commons.collections4. Further note that there are AEM APIs currently exposing the old collections classes; these will be updated in upcoming releases.
Defines a map that holds a collection of values against each key.

A MultiMap is a Map with slightly different semantics. Putting a value into the map will add the value to a Collection at that key. Getting a value will return a Collection, holding all the values put to that key.

For example: 

  MultiMap mhm = new MultiHashMap();
  mhm.put(key, "A");
  mhm.put(key, "B");
  mhm.put(key, "C");
  Collection coll = (Collection) mhm.get(key);

coll will be a collection containing "A", "B", "C".

NOTE: Additional methods were added to this interface in Commons Collections 3.1. These were added solely for documentation purposes and do not change the interface as they were defined in the superinterface Map anyway.

Since:
Commons Collections 2.0

  • Method Details

    • remove

      Object remove(Object key, Object item)
      Deprecated.
      Removes a specific value from 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 null from a subsequant get(Object), however they may choose to return an empty collection.

      Specified by:
      remove in interface Map
      Parameters:
      key - the key to remove from
      item - the item to remove
      Returns:
      the value removed (which was passed in), null if nothing removed
      Throws:
      UnsupportedOperationException - if the map is unmodifiable
      ClassCastException - if the key or value is of an invalid type
      NullPointerException - if the key or value is null and null is invalid

    • size

      int size()
      Deprecated.
      Gets the number of keys in this map.

      Implementations typically return only the count of keys in the map This cannot be mandated due to backwards compatability of this interface.

      Specified by:
      size in interface Map
      Returns:
      the number of key-collection mappings in this map

    • get

      Object get(Object key)
      Deprecated.
      Gets the collection of values associated with the specified key.

      The returned value will implement Collection. Implementations are free to declare that they return Collection subclasses such as List or Set.

      Implementations typically return null if no values have been mapped to the key, however the implementation may choose to return an empty collection.

      Implementations may choose to return a clone of the internal collection.

      Specified by:
      get in interface Map
      Parameters:
      key - the key to retrieve
      Returns:
      the Collection of values, implementations should return null for no mapping, but may return an empty collection
      Throws:
      ClassCastException - if the key is of an invalid type
      NullPointerException - if the key is null and null keys are invalid

    • containsValue

      boolean containsValue(Object value)
      Deprecated.
      Checks whether the map contains the value specified.

      Implementations typically check all collections against all keys for the value. This cannot be mandated due to backwards compatability of this interface.

      Specified by:
      containsValue in interface Map
      Parameters:
      value - the value to search for
      Returns:
      true if the map contains the value
      Throws:
      ClassCastException - if the value is of an invalid type
      NullPointerException - if the value is null and null value are invalid

    • put

      Object put(Object key, Object value)
      Deprecated.
      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. The collection may be a List, Set or other collection dependent on implementation.

      Specified by:
      put in interface Map
      Parameters:
      key - the key to store against
      value - the value to add to the collection at the key
      Returns:
      typically the value added if the map changed and null if the map did not change
      Throws:
      UnsupportedOperationException - if the map is unmodifiable
      ClassCastException - if the key or value is of an invalid type
      NullPointerException - if the key or value is null and null is invalid
      IllegalArgumentException - if the key or value is invalid

    • remove

      Object remove(Object key)
      Deprecated.
      Removes all values associated with the specified key.

      Implementations typically return null from a subsequant get(Object), however they may choose to return an empty collection.

      Specified by:
      remove in interface Map
      Parameters:
      key - the key to remove values from
      Returns:
      the Collection of values removed, implementations should return null for no mapping found, but may return an empty collection
      Throws:
      UnsupportedOperationException - if the map is unmodifiable
      ClassCastException - if the key is of an invalid type
      NullPointerException - if the key is null and null keys are invalid

    • values

      Collection values()
      Deprecated.
      Gets a collection containing all the values in the map.

      Inplementations typically return a collection containing the combination of values from all keys. This cannot be mandated due to backwards compatability of this interface.

      Specified by:
      values in interface Map
      Returns:
      a collection view of the values contained in this map