net.cscott.jutil
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.
FSK: This data type is a bit experimental; a few changes may be coming:
Map
interface, because it inherently violates the
constraints of the Map interface once
multiple values are added for one key.
Collection views returned right now
don't offer very much in terms of modifying the
state of this internally.
this. This is a gross
oversight of Collection's interface
on my part and I need to fix it, which I will do when I
have free time.
Version: $Id: MultiMap.java,v 1.2 2004/01/13 20:47:05 cananian Exp $
| 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). |
this contains an association from
key to value.
(MultiMap specific operation).Returns: true if this mapping changed as a result of
the call
key to each value in values.
(MultiMap specific operation).Returns: true if this mapping changed as a result
of the call
a has a mapping to b
in this.
(MultiMap specific operation).Set view that allows you to recapture
the MultiMap view.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.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).null if no values were
associated previously.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).Map definition of
remove.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).
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.key to any value in values.
(MultiMap specific operation).Returns: true if this mapping changed as a result
of the call
key to any value not in values.
(MultiMap specific operation).Returns: true if this mapping changed as a result
of the call