Package net.cscott.jutil

Interface MultiMap<K,V>

All Superinterfaces:
Map<K,V>
All Known Subinterfaces:
InvertibleMultiMap<K,V>
All Known Implementing Classes:
AbstractMultiMap, GenericInvertibleMultiMap, GenericMultiMap, UnmodifiableMultiMap
public interface MultiMap<K,V> extends Map<K,V>
MultiMap maps a key to a collection of values. These collections are created as needed using a CollectionFactory. Any constraints on the collections produced by this factory thus hold for the values that this maps to.
Formally, a MultiMap is a Multiple Associative Container. It associates key objects with value objects. The difference between a MultiMap and a standard Map is that MultiMap extends the Map interface to allow for the same key to map to multiple values.
Thus, the type signature for a MultiMap is :: Map[keytype -> [valtype] ]
Note that an association (known as a (Key, Value) pair or a Map.Entry in the Java Collections API) is only defined to exist if the collection of objects mapped to by some key is non-empty. This has a number of implications for the behavior of MultiMap:
Let
  1. mm be a MultiMap,
  2. k be an Object (which may or may not be a Key in mm)
  3. c be the Collection returned by mm.getValues(k).

Then c will either be a non-empty Collection (the case where k is a Key in mm) or it will be an empty collection (the case where k is not a Key in mm). In the latter case, however, k is still considered to not be a Key in mm until c is made non-empty. We chose to return an empty Collection instead of null to allow for straightforward addition to the collection of values mapped to by k.
To conform to the Map interface, the put(key, value) method has a non-intuitive behavior; it throws away all values previously associated with key and creates a new mapping from key to a singleton collection containing value. Use add(key, value) to preserve the old collection of associative mappings.
The default methods of Map which are not overridden here, such as putIfAbsent(), computeIfPresent(), compute() and merge(), are built on get(), put() and remove(): they see an arbitrary one of the values of a key, and replace or remove all of them. replace(Object,Object,Object) and replaceAll(java.util.function.BiFunction<? super K, ? super V, ? extends V>) treat each mapping separately.

Note that the behavior of MultiMap is indistinquishable from that of a Map if none of the extensions of MultiMap are utilized. Thus, users should take care to ensure that other code relying on the constraints enforced by the Map interface does not ever attempt to use a MultiMap when any of its Keys map to more than one value.

Author:
Felix S. Klock II <pnkfelix@mit.edu>
Tests:
<code>add()</code> adds a value to those of a key, while <code>put()</code> replaces them all: 
js> mm = new GenericMultiMap(Factories.treeSetFactory())
{}
js> mm.add("fruit", "pear"); mm.add("fruit", "apple")
true
js> mm.add("nut", "pecan")
true
js> mm.getValues("fruit")
[apple, pear]
js> mm.size() // the number of mappings, not of keys
3
js> mm.put("fruit", "fig") // returns one of the old values
apple
js> mm.getValues("fruit")
[fig]

  • Nested Class Summary

    Nested classes/interfaces inherited from interface java.util.Map

    Map.Entry<K,V>

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    add(K key, V value)
    Ensures that this contains an association from key to value.
    boolean
    addAll(K key, Collection<? extends V> values)
    Adds to the current mappings: associations for key to each value in values.
    boolean
    addAll(MultiMap<? extends K,? extends V> mm)
    Adds all mappings in the given multimap to this multimap.
    boolean
    contains(Object a, Object b)
    Returns true if a has a mapping to b in this.
    MultiMapSet<K,V>
    entrySet()
    Returns a Set view that allows you to recapture the MultiMap view.
    V
    get(Object key)
    Returns some arbitrary value from the collection of values to which this map maps the specified key.
    Collection<V>
    getValues(K key)
    Returns the collection of Values associated with key.
    V
    put(K key, V value)
    Associates the specified value with the specified key in this map, after removing all old values associated with the key.
    void
    putAll(Map<? extends K,? extends V> t)
    Copies the mappings from the specified map to this map, after removing all old values associated with the key.
    V
    remove(Object key)
    Removes mappings from key to all associated values from this map.
    boolean
    remove(Object key, Object value)
    Removes a mapping from key to value from this map if present
    boolean
    removeAll(K key, Collection<?> values)
    Removes from the current mappings: associations for key to any value in values.
    default boolean
    replace(K key, V oldValue, V newValue)
    Replaces the mapping from key to oldValue, if there is one, with a mapping from key to newValue.
    default void
    replaceAll(BiFunction<? super K,? super V,? extends V> function)
    Replaces each mapping from a key k to a value v with a mapping from k to function.apply(k, v).
    boolean
    retainAll(K key, Collection<?> values)
    Removes from the current mappings: associations for key to any value not in values.
    int
    size()
    Returns the number of key-value mappings in this map (keys which map to multiple values count multiple times).

    Methods inherited from interface java.util.Map

    clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, equals, forEach, getOrDefault, hashCode, isEmpty, keySet, merge, putIfAbsent, replace, values

  • Method Details

    • get

      V get(Object key)
      Returns some arbitrary value from the collection of values to which this map maps the specified key. Returns null if the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. The containsKey operation may be used to distinquish these two cases. Note that if only the put method is used to modify this, then get will operate just as it would in any other Map.
      Specified by:
      get in interface Map<K,V>

    • put

      V put(K key, V value)
      Associates the specified value with the specified key in this map, after removing all old values associated with the key. Returns some value that was previously associated with the specified key, or null if no values were associated previously.
      Specified by:
      put in interface Map<K,V>

    • putAll

      void putAll(Map<? extends K,? extends V> t)
      Copies the mappings from the specified map to this map, after removing all old values associated with the key. Note that putAll(mm) where mm is a MultiMap will NOT add all of the mappings in mm; it will only add all of the Keys in mm, mapping each Key to one of the Values it mapped to in mm. To add all of the mappings from another MultiMap, use addAll(MultiMap).
      Specified by:
      putAll in interface Map<K,V>

    • remove

      V remove(Object key)
      Removes mappings from key to all associated values from this map. This is consistent with the Map definition of remove.
      Specified by:
      remove in interface Map<K,V>
      Returns:
      one of the previous values associated with the key, or null if Map associated no values with the key. Note that a zero-sized collection is not returned in the latter case, and that a null return value may be ambiguous if the map associated null with the given key (in addition to possibly other values).

    • remove

      boolean remove(Object key, Object value)
      Removes a mapping from key to value from this map if present. (MultiMap specific operation). Note that if multiple mappings from key to value are permitted by this map, then only one is guaranteed to be removed. Returns true if this was modified as a result of this operation, else returns false.
      Specified by:
      remove in interface Map<K,V>

    • add

      boolean add(K key, V value)
      Ensures that this contains an association from key to value. (MultiMap specific operation).
      Returns:
      true if this mapping changed as a result of the call

    • addAll

      boolean addAll(K key, Collection<? extends V> values)
      Adds to the current mappings: associations for key to each value in values. (MultiMap specific operation).
      Returns:
      true if this mapping changed as a result of the call

    • addAll

      boolean addAll(MultiMap<? extends K,? extends V> mm)
      Adds all mappings in the given multimap to this multimap.

    • retainAll

      boolean retainAll(K key, Collection<?> values)
      Removes from the current mappings: associations for key to any value not in values. (MultiMap specific operation).
      Returns:
      true if this mapping changed as a result of the call

    • removeAll

      boolean removeAll(K key, Collection<?> values)
      Removes from the current mappings: associations for key to any value in values. (MultiMap specific operation).
      Returns:
      true if this mapping changed as a result of the call

    • getValues

      Collection<V> getValues(K key)
      Returns the collection of Values associated with key. Modifications to the returned Collection affect this as well. If there are no Values currently associated with key, constructs a new, potentially mutable, empty Collection and returns it. (MultiMap specific operation).

    • contains

      boolean contains(Object a, Object b)
      Returns true if a has a mapping to b in this. (MultiMap specific operation).

    • size

      int size()
      Returns the number of key-value mappings in this map (keys which map to multiple values count multiple times).
      Specified by:
      size in interface Map<K,V>

    • entrySet

      MultiMapSet<K,V> entrySet()
      Returns a Set view that allows you to recapture the MultiMap view.
      Specified by:
      entrySet in interface Map<K,V>

    • replace

      default boolean replace(K key, V oldValue, V newValue)
      Replaces the mapping from key to oldValue, if there is one, with a mapping from key to newValue. The other values of key are kept. (Map's default implementation would compare oldValue to an arbitrary one of the values of key, and then replace all of them.)
      Specified by:
      replace in interface Map<K,V>
      Returns:
      true if key mapped to oldValue.
      Since:
      2.0

    • replaceAll

      default void replaceAll(BiFunction<? super K,? super V,? extends V> function)
      Replaces each mapping from a key k to a value v with a mapping from k to function.apply(k, v). The new mappings are added after all of the new values are computed, so this map is unchanged if function throws. (Map's default implementation would call Map.Entry.setValue(V) while iterating, which a MultiMap's entries do not support.)
      Specified by:
      replaceAll in interface Map<K,V>
      Since:
      2.0