|
JUtil | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
public interface MultiMap<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
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.
| Nested Class Summary |
|---|
| Nested classes/interfaces inherited from interface java.util.Map |
|---|
Map.Entry<K,V> |
| Method Summary | |
|---|---|
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. |
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, containsKey, containsValue, equals, hashCode, isEmpty, keySet, values |
| Method Detail |
|---|
V 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.
get in interface Map<K,V>
V put(K key,
V value)
null if no values were
associated previously.
put in interface Map<K,V>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).
putAll in interface Map<K,V>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 add(K key,
V value)
this contains an association from
key to value.
(MultiMap specific operation).
true if this mapping changed as a result of
the call
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 call
boolean 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).
boolean contains(Object a,
Object b)
a has a mapping to b
in this.
(MultiMap specific operation).
int size()
size in interface Map<K,V>MultiMapSet<K,V> entrySet()
Set view that allows you to recapture
the MultiMap view.
entrySet in interface Map<K,V>
|
JUtil | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||