org.apache.commons.collections15
Interface MultiMap<K,V>

All Known Implementing Classes:
MultiHashMap

public interface MultiMap<K,V>

Defines a map that holds a collection of values against each key.

A MultiMap is a Map with slightly different semantics. Putting a value into the map will add the value to a Collection at that key. Getting a value will return a Collection, holding all the values put to that key.

For example:

 Number key = new Integer(5);
 MultiMap<Number,String> mhm = new MultiHashMap<Number,String>();
 mhm.put(key, "A");
 mhm.put(key, "B");
 mhm.put(key, "C");
 Collection<String> coll = mhm.get(key);

coll will be a collection containing "A", "B", "C".

NOTE: Note: this new, generics-friendly version of the MultiMap interface does NOT extend java.util.Map! This is because MultiMap breaks the Map contract in too many ways to allow generics support. However, you can get a live java.util.Map for a MultiMap with the method map().

Since:
Commons Collections 2.0
Version:
$Revision: 1.1 $ $Date: 2005/10/11 17:05:19 $
Author:
Christopher Berry, James Strachan, Matt Hall, John Watkinson, Stephen Colebourne

Method Summary
 void clear()
          Removes all mappings from this map (optional operation).
 boolean containsKey(Object key)
          Returns true if this map contains a mapping for the specified key.
 boolean containsValue(Object value)
          Checks whether the map contains the value specified.
 boolean containsValue(Object key, Object value)
          Checks whether the map contains the value specified, at the key specified.
 Set<Map.Entry<K,Collection<V>>> entrySet()
          Returns a set view of the mappings contained in this map.
 boolean equals(Object o)
          Compares the specified object with this map for equality.
 Collection<V> get(Object key)
          Gets the collection of values associated with the specified key.
 int hashCode()
          Returns the hash code value for this map.
 boolean isEmpty()
          Returns true if this map contains no key-value mappings.
 Iterator<V> iterator(Object key)
           
 Set<K> keySet()
          Returns a set view of the keys contained in this map.
 Map<K,Collection<V>> map()
          Returns a java.util.Map<K,Collection<V>> for this MultiMap.
 V put(K key, V value)
          Adds the value to the collection associated with the specified key.
 boolean putAll(K key, Collection<? extends V> values)
          Copies all of the values in the given collection in to the multimap against the given key.
 void putAll(Map<? extends K,? extends V> t)
          Copies all of the mappings from the specified map to this map (optional operation).
 void putAll(MultiMap<? extends K,? extends V> t)
          Copies all of the mappings from the specified multimap to this multimap (optional operation).
 Collection<V> remove(Object key)
          Removes all values associated with the specified key.
 V remove(Object key, Object item)
          Removes a specific value from map.
 int size()
          Gets the number of keys in this map.
 int size(Object key)
          Gets the number of values in this map for the given key.
 Collection<V> values()
          Gets a collection containing all the values in the map.
 

Method Detail

remove

V remove(Object key,
         Object item)
Removes a specific value from map.

The item is removed from the collection mapped to the specified key. Other values attached to that key are unaffected.

If the last value for a key is removed, implementations typically return null from a subsequant get(Object), however they may choose to return an empty collection.

Parameters:
key - the key to remove from
item - the item to remove
Returns:
the value removed (which was passed in), null if nothing removed
Throws:
UnsupportedOperationException - if the map is unmodifiable
ClassCastException - if the key or value is of an invalid type
NullPointerException - if the key or value is null and null is invalid

size

int size(Object key)
Gets the number of values in this map for the given key.

Implementations return the count of keys in the map, or 0 if there are no values for the given key.

Returns:
the number of values in this map for the given key.

size

int size()
Gets the number of keys in this map.

Implementations return the count of keys in the map.

Returns:
the number of key-collection mappings in this map

get

Collection<V> get(Object key)
Gets the collection of values associated with the specified key.

The returned value will implement Collection. Implementations are free to declare that they return Collection subclasses such as List or Set.

Implementations return null if no values have been mapped to the key.

Implementations may choose to return a clone of the internal collection.

Parameters:
key - the key to retrieve
Returns:
the Collection of values, implementations should return null for no mapping, but may return an empty collection
Throws:
ClassCastException - if the key is of an invalid type
NullPointerException - if the key is null and null keys are invalid

containsValue

boolean containsValue(Object value)
Checks whether the map contains the value specified.

Implementations check all collections15 against all keys for the value.

Parameters:
value - the value to search for
Returns:
true if the map contains the value
Throws:
ClassCastException - if the value is of an invalid type
NullPointerException - if the value is null and null value are invalid

containsValue

boolean containsValue(Object key,
                      Object value)
Checks whether the map contains the value specified, at the key specified.

Parameters:
value - the value to search for
key - the key against which to search for the value
Returns:
true if the map contains the value
Throws:
ClassCastException - if the value is of an invalid type
NullPointerException - if the value is null and null value are invalid

put

V put(K key,
      V value)
Adds the value to the collection associated with the specified key.

Unlike a normal Map the previous value is not replaced. Instead the new value is added to the collection stored against the key. The collection may be a List, Set or other collection dependent on implementation.

Parameters:
key - the key to store against
value - the value to add to the collection at the key
Returns:
typically the value added if the map changed and null if the map did not change
Throws:
UnsupportedOperationException - if the map is unmodifiable
ClassCastException - if the key or value is of an invalid type
NullPointerException - if the key or value is null and null is invalid
IllegalArgumentException - if the key or value is invalid

remove

Collection<V> remove(Object key)
Removes all values associated with the specified key.

Implementations typically return null from a subsequent get(Object), however they may choose to return an empty collection.

Parameters:
key - the key to remove values from
Returns:
the Collection of values removed, implementations should return null for no mapping found, but may return an empty collection
Throws:
UnsupportedOperationException - if the map is unmodifiable
ClassCastException - if the key is of an invalid type
NullPointerException - if the key is null and null keys are invalid

values

Collection<V> values()
Gets a collection containing all the values in the map.

Inplementations return a collection containing the combination of values from all keys.

Returns:
a collection view of the values contained in this map

isEmpty

boolean isEmpty()
Returns true if this map contains no key-value mappings.

Returns:
true if this map contains no key-value mappings.

containsKey

boolean containsKey(Object key)
Returns true if this map contains a mapping for the specified key. More formally, returns true if and only if this map contains a mapping for a key k such that (key==null ? k==null : key.equals(k)). (There can be at most one such mapping.)

Parameters:
key - key whose presence in this map is to be tested.
Returns:
true if this map contains a mapping for the specified key.
Throws:
ClassCastException - if the key is of an inappropriate type for this map (optional).
NullPointerException - if the key is null and this map does not permit null keys (optional).

putAll

void putAll(Map<? extends K,? extends V> t)
Copies all of the mappings from the specified map to this map (optional operation). The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key k to value v in the specified map. The behavior of this operation is unspecified if the specified map is modified while the operation is in progress.

Parameters:
t - Mappings to be stored in this map.
Throws:
UnsupportedOperationException - if the putAll method is not supported by this map.
ClassCastException - if the class of a key or value in the specified map prevents it from being stored in this map.
IllegalArgumentException - some aspect of a key or value in the specified map prevents it from being stored in this map.
NullPointerException - if the specified map is null, or if this map does not permit null keys or values, and the specified map contains null keys or values.

putAll

void putAll(MultiMap<? extends K,? extends V> t)
Copies all of the mappings from the specified multimap to this multimap (optional operation). The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key to collections15 of values in the specified multimap. The behavior of this operation is unspecified if the specified multimap is modified while the operation is in progress.

Parameters:
t - Mappings to be stored in this map.
Throws:
UnsupportedOperationException - if the putAll method is not supported by this map.
ClassCastException - if the class of a key or value in the specified map prevents it from being stored in this map.
IllegalArgumentException - some aspect of a key or value in the specified map prevents it from being stored in this map.
NullPointerException - if the specified map is null, or if this map does not permit null keys or values, and the specified map contains null keys or values.

putAll

boolean putAll(K key,
               Collection<? extends V> values)
Copies all of the values in the given collection in to the multimap against the given key.

Parameters:
key - the key against which to store the values.
values - the collection of values to map to the key.

iterator

Iterator<V> iterator(Object key)

clear

void clear()
Removes all mappings from this map (optional operation).

Throws:
UnsupportedOperationException - clear is not supported by this map.

keySet

Set<K> keySet()
Returns a set view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation), the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll retainAll, and clear operations. It does not support the add or addAll operations.

Returns:
a set view of the keys contained in this map.

entrySet

Set<Map.Entry<K,Collection<V>>> entrySet()
Returns a set view of the mappings contained in this map. Each element in the returned set is a Map.Entry. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation, or through the setValue operation on a map entry returned by the iterator) the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Returns:
a set view of the mappings contained in this map.

map

Map<K,Collection<V>> map()
Returns a java.util.Map<K,Collection<V>> for this MultiMap.

Returns:
the underlying java.util.Map for this MultiMap.

equals

boolean equals(Object o)
Compares the specified object with this map for equality. Returns true if the given object is also a map and the two Maps represent the same mappings. More formally, two maps t1 and t2 represent the same mappings if t1.entrySet().equals(t2.entrySet()). This ensures that the equals method works properly across different implementations of the Map interface.

Overrides:
equals in class Object
Parameters:
o - object to be compared for equality with this map.
Returns:
true if the specified object is equal to this map.

hashCode

int hashCode()
Returns the hash code value for this map. The hash code of a map is defined to be the sum of the hashCodes of each entry in the map's entrySet view. This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two maps t1 and t2, as required by the general contract of Object.hashCode.

Overrides:
hashCode in class Object
Returns:
the hash code value for this map.
See Also:
Map.Entry#hashCode(), Object.hashCode(), Object.equals(Object), equals(Object)


Copyright © 2001-2010 Apache Software Foundation. All Rights Reserved.