|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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.
Nested Class Summary | |
static class |
MultiMap.Factory
MultiMap.Factory is a MultiMap
generator. |
Nested classes inherited from class java.util.Map |
Map.Entry |
Method Summary | |
boolean |
add(Object key,
Object value)
Ensures that this contains an association from
key to value . |
boolean |
addAll(MultiMap mm)
Adds all mappings in the given multimap to this multimap. |
boolean |
addAll(Object key,
Collection values)
Adds to the current mappings: associations for key to each value in values . |
boolean |
contains(Object a,
Object b)
Returns true if a has a mapping to b
in this . |
Object |
get(Object key)
Returns some arbitrary value from the collection of values to which this map maps the specified key. |
Collection |
getValues(Object key)
Returns the collection of Values associated with key . |
Object |
put(Object key,
Object value)
Associates the specified value with the specified key in this map, after removing all old values associated with the key. |
void |
putAll(Map t)
Copies the mappings from the specified map to this map, after removing all old values associated with the key. |
Object |
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(Object key,
Collection values)
Removes from the current mappings: associations for key to any value in values . |
boolean |
retainAll(Object 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, entrySet, equals, hashCode, isEmpty, keySet, values |
Method Detail |
public Object 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
public Object put(Object key, Object value)
null
if no values were
associated previously.
put
in interface Map
public void putAll(Map 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
public Object remove(Object key)
Map
definition of
remove
.
remove
in interface Map
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).public 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.
public boolean add(Object key, Object value)
this
contains an association from
key
to value
.
(MultiMap
specific operation).
true
if this mapping changed as a result of
the callpublic boolean addAll(Object key, Collection values)
key
to each value in values
.
(MultiMap
specific operation).
true
if this mapping changed as a result
of the callpublic boolean addAll(MultiMap mm)
public boolean retainAll(Object key, Collection values)
key
to any value not in values
.
(MultiMap
specific operation).
true
if this mapping changed as a result
of the callpublic boolean removeAll(Object key, Collection values)
key
to any value in values
.
(MultiMap
specific operation).
true
if this mapping changed as a result
of the callpublic Collection getValues(Object 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).
public boolean contains(Object a, Object b)
a
has a mapping to b
in this
.
(MultiMap
specific operation).
contains
in interface BinaryRelation
public int size()
size
in interface Map
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |