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.
MultiMap and a standard
Map is that MultiMap extends the
Map interface to allow for the same key to map to
multiple values.
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:
mm be a MultiMap,
k be an Object (which may or may
not be a Key in mm)
c be the Collection returned by
mm.getValues(k).
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.
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.
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.
| Modifier and Type | Method and 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()
|
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. |
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).
|
clear, containsKey, containsValue, equals, hashCode, isEmpty, keySet, valuesV get(Object key)
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.V put(K key, V value)
null if no values were
associated previously.void putAll(Map<? extends K,? extends V> t)
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).V remove(Object key)
Map definition of
remove.remove in interface Map<K,V>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).boolean remove(Object key, Object value)
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.boolean addAll(K key, Collection<? extends V> values)
key to each value in values.
(MultiMap specific operation).true if this mapping changed as a result
of the callboolean addAll(MultiMap<? extends K,? extends V> mm)
boolean retainAll(K key, Collection<?> values)
key to any value not in values.
(MultiMap specific operation).true if this mapping changed as a result
of the callboolean removeAll(K key, Collection<?> values)
key to any value in values.
(MultiMap specific operation).true if this mapping changed as a result
of the callCollection<V> getValues(K key)
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).int size()
Copyright (c) 2006 C. Scott Ananian