org.clapper.util.misc
Class MultiValueMap<K,V>

java.lang.Object
  java.util.AbstractMap<K,V>
      org.clapper.util.misc.MultiValueMap<K,V>

All Implemented Interfaces:

java.lang.Cloneable, java.util.Map<K,V>

public class MultiValueMap<K,V>
extends java.util.AbstractMap<K,V>
implements java.lang.Cloneable

MultivalueMap implements a hash table that permits multiple values per key. It's very similar to the MultiValueMap class provided by the Jakarta Commons Collections API, except that this class uses Java 5 generics.

Any value placed into a MultivalueMap must implement java.lang.Comparable.

Version:

$Revision: 6488 $

Nested Class Summary

static interface

MultiValueMap.ValuesCollectionAllocator<V> Used to allocate a new Collection for the values associated with a key.

Nested classes/interfaces inherited from class java.util.AbstractMap

java.util.AbstractMap.SimpleEntry<K,V>, java.util.AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Constructor Summary

MultiValueMap()
Constructs a new, empty map with a default capacity and load factor.

MultiValueMap(int initialCapacity)
Constructs a new, empty map with the specified initial capacity and the default load factor.

MultiValueMap(int initialCapacity, float loadFactor)
Constructs a new, empty map with the specified initial capacity and the specified load factor.

MultiValueMap(int initialCapacity, float loadFactor, MultiValueMap.ValuesCollectionAllocator<V> valuesCollectionAllocator)
Constructs a new, empty map with the specified initial capacity and the specified load factor.

MultiValueMap(MultiValueMap.ValuesCollectionAllocator<V> valuesCollectionAllocator)
Constructs a new, empty map with a default capacity and load factor.

MultiValueMap(MultiValueMap<K,V> otherMap)
Construct a new map from the contents of an existing map.

Method Summary

void	clear() Removes all mappings from this map.
java.lang.Object	clone() Returns a shallow copy of this MultivalueMap instance.
boolean	containsKey(java.lang.Object key) Returns true if this map contains at least one value for the specified key.
boolean	containsKeyValue(K key, V value) Returns true if this map contains the specified value for the specified key.
boolean	containsValue(java.lang.Object value) Returns true if this map maps one or more keys to the specified value.
java.util.Set<java.util.Map.Entry<K,V>>	entrySet() Returns an unmodifiable Set view of the mappings contained in this map.
boolean	equals(java.lang.Object o) Compares the specified object with this map for equality.
V	get(java.lang.Object key) Synonym for getFirstValueForKey(K), required by the Map interface.
java.util.Collection<V>	getCollection(K key) Returns an unmodifiable Collection containing all values associated with the the specified key.
V	getFirstValueForKey(K key) Returns the first value in the set of values associated with a key.
java.util.Collection<V>	getValuesForKey(K key) Return an unmodifiable Collection of all the values for a specific key.
int	getValuesForKey(K key, java.util.Collection<V> values) Copy all the values for a specific key into a caller-supplied Collection.
int	hashCode() Returns the hash code value for this map.
boolean	isEmpty() Determine whether the map is empty.
java.util.Set<K>	keySet() Returns a Set containing all the keys in this map.
V	put(K key, V value) Associates the specified value with the specified key in this map.
void	putAll(K key, java.util.Collection<V> values) Assocates all the objects in a Collection with a key.
void	putAll(java.util.Map<? extends K,? extends V> fromMap) Copies all of the mappings from the specified Map to this map.
void	putAll(MultiValueMap<K,V> fromMap) Copies all of the mappings from the specified MultivalueMap to this map.
java.util.Collection<V>	remove(K key) Removes all mappings for a key from this map, if present.
boolean	remove(K key, V value) Removes a single value from the set of values associated with a key.
int	size() Returns the number of key-value mappings in this map.
int	totalValuesForKey(K key) Gets the total number of values mapped to a specific key.
java.util.Collection<V>	values() Returns a collection view of the values contained in this map.

Methods inherited from class java.util.AbstractMap

remove, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MultiValueMap

public MultiValueMap()

Constructs a new, empty map with a default capacity and load factor. This class's default load factor is the same as the default load factor for the java.util.HashMap class.

MultiValueMap

public MultiValueMap(MultiValueMap.ValuesCollectionAllocator<V> valuesCollectionAllocator)

Constructs a new, empty map with a default capacity and load factor. This class's default load factor is the same as the default load factor for the java.util.HashMap class.

Parameters:

valuesCollectionAllocator - object to use to allocate collections of values for a key.

MultiValueMap

public MultiValueMap(int initialCapacity,
                     float loadFactor)

Constructs a new, empty map with the specified initial capacity and the specified load factor. Note that the load factor and capacity refer to the number of keys in the table, not the number of values.

Parameters:

initialCapacity - the initial capacity of the Map

loadFactor - the load factor

Throws:

java.lang.IllegalArgumentException - if the initial capacity is negative, or if the load factor is nonpostive.

MultiValueMap

public MultiValueMap(int initialCapacity,
                     float loadFactor,
                     MultiValueMap.ValuesCollectionAllocator<V> valuesCollectionAllocator)

Constructs a new, empty map with the specified initial capacity and the specified load factor. Note that the load factor and capacity refer to the number of keys in the table, not the number of values.

Parameters:

initialCapacity - the initial capacity

loadFactor - the load factor

valuesCollectionAllocator - object to use to allocate collections of values for a key.

Throws:

java.lang.IllegalArgumentException - if the initial capacity is negative, or if the load factor is nonpostive.

MultiValueMap

public MultiValueMap(int initialCapacity)

Constructs a new, empty map with the specified initial capacity and the default load factor. Note that the load factor and capacity refer to the number of keys in the table, not the number of values.

Parameters:

initialCapacity - the initial capacity

Throws:

java.lang.IllegalArgumentException - if the initial capacity is negative, or if the load factor is nonpostive.

MultiValueMap

public MultiValueMap(MultiValueMap<K,V> otherMap)

Construct a new map from the contents of an existing map. The new map is a shallow copy of the existing map.

Parameters:

otherMap - the map to clone

Method Detail

clear

public void clear()

Removes all mappings from this map.

Specified by:

clear in interface java.util.Map<K,V>

Overrides:

clear in class java.util.AbstractMap<K,V>

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Returns a shallow copy of this MultivalueMap instance. The keys and values themselves are not cloned.

Overrides:

clone in class java.util.AbstractMap<K,V>

Throws:

java.lang.CloneNotSupportedException - never, but it's part of the signature

containsKey

public boolean containsKey(java.lang.Object key)

Returns true if this map contains at least one value for the specified key.

Specified by:

containsKey in interface java.util.Map<K,V>

Overrides:

containsKey in class java.util.AbstractMap<K,V>

Parameters:

key - key whose presence in this map is to be tested

Returns:

true if this map contains at least one value for the key, false otherwise.

Throws:

java.lang.ClassCastException - if the key is of an inappropriate type for this map.

java.lang.NullPointerException - if the key is null and this map does not not permit null keys.

See Also:

totalValuesForKey(K)

containsValue

public boolean containsValue(java.lang.Object value)

Returns true if this map maps one or more keys to the specified value. The values are compared via their compareTo() and/or equals() methods, so this method is only useful if the map contains values of the same type.

Specified by:

containsValue in interface java.util.Map<K,V>

Overrides:

containsValue in class java.util.AbstractMap<K,V>

Parameters:

value - value whose presence in this map is to be tested.

Returns:

true if this map maps one or more keys to the specified value, false otherwise.

containsKeyValue

public boolean containsKeyValue(K key,
                                V value)

Returns true if this map contains the specified value for the specified key. The values are compared via their compareTo() and/or equals() methods.

Parameters:

key - the key

value - the value

Returns:

true if the set of values for the specified key contains the specified value

entrySet

public java.util.Set<java.util.Map.Entry<K,V>> entrySet()

Returns an unmodifiable Set view of the mappings contained in this map. Each element in the returned collection is a Map.Entry; each Map.Entry contains a key and a value. Even though the return value is a Set, it will still contain all key/value pairs for a given key. The returned Set is backed by this map, so any changes to the map are automatically reflected in the set.

Specified by:

entrySet in interface java.util.Map<K,V>

Specified by:

entrySet in class java.util.AbstractMap<K,V>

Returns:

a Set view of the mappings contained in this map

See Also:

keySet(), values()

equals

public boolean equals(java.lang.Object o)

Compares the specified object with this map for equality. Returns true if the given object is also a MultivalueMap and the two maps represent the same mappings. 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.

Warning:: Because this method must compare the actual values stored in the map, and the values in a file, this method can be quite slow.

Specified by:

equals in interface java.util.Map<K,V>

Overrides:

equals in class java.util.AbstractMap<K,V>

Parameters:

o - object to be compared for equality with this map.

Returns:

true if the specified object is equal to this map.

getCollection

public java.util.Collection<V> getCollection(K key)

Returns an unmodifiable Collection containing all values associated with the the specified key. Returns null if the map contains no mapping for this key.

Parameters:

key - key whose associated collection of values is to be returned.

Returns:

an unmodifiable Collection containing all values associated with the the specified key, or * null if the map contains no values for this key.

Throws:

java.lang.ClassCastException - if the key is of an inappropriate type for this map.

java.lang.NullPointerException - if the key is null and this map does not not permit null keys.

See Also:

containsKey(java.lang.Object), getFirstValueForKey(K)

get

public V get(java.lang.Object key)

Synonym for getFirstValueForKey(K), required by the Map interface.

Specified by:

get in interface java.util.Map<K,V>

Overrides:

get in class java.util.AbstractMap<K,V>

Parameters:

key - the key

Returns:

the first value for the key, or null if not found

getFirstValueForKey

public V getFirstValueForKey(K key)

Returns the first value in the set of values associated with a key. This method is especially useful when you know that there is only a single value associated with the key. Note that "first" does not mean "first value ever associated with the key." Instead, it means "first value in the sorted list of values for the key."

Parameters:

key - key whose associated value is to be returned.

Returns:

the first value for the key, where first is defined as above, or null, if the key has no values

Throws:

java.lang.NullPointerException - if the key is null and this map does not not permit null keys.

See Also:

containsKey(java.lang.Object), get(java.lang.Object), totalValuesForKey(K)

hashCode

public int hashCode()

Returns the hash code value for this map. The hash code of a map is defined to be the sum of the hash codes 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.

Specified by:

hashCode in interface java.util.Map<K,V>

Overrides:

hashCode in class java.util.AbstractMap<K,V>

Returns:

the hash code value for this map.

See Also:

equals(Object)

isEmpty

public boolean isEmpty()

Determine whether the map is empty.

Specified by:

isEmpty in interface java.util.Map<K,V>

Overrides:

isEmpty in class java.util.AbstractMap<K,V>

Returns:

true if this map contains no key-value mappings.

keySet

public java.util.Set<K> keySet()

Returns a Set containing all the keys in this map.

The set is backed by the map, so changes to the map are reflected in the set. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined. Neither the set nor its associated iterator supports any of the set-modification methods (e.g., add(), remove(), etc). If you attempt to call any of those methods, the called method will throw an UnsupportedOperationException.

Specified by:

keySet in interface java.util.Map<K,V>

Overrides:

keySet in class java.util.AbstractMap<K,V>

Returns:

a set view of the keys contained in this map.

See Also:

getValuesForKey(K), values()

put

public V put(K key,
             V value)

Associates the specified value with the specified key in this map. If the map previously contained a mapping for this key, this value is added to the list of values associated with the key. This map class does not permit a null value to be stored.

Specified by:

put in interface java.util.Map<K,V>

Overrides:

put in class java.util.AbstractMap<K,V>

Parameters:

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

null, always

Throws:

java.lang.ClassCastException - if the class of the specified key or value prevents it from being stored in this map.

java.lang.IllegalArgumentException - if some aspect of this key or value prevents it from being stored in this map.

java.lang.NullPointerException - the specified key or value is null.

putAll

public void putAll(java.util.Map<? extends K,? extends V> fromMap)

Copies all of the mappings from the specified Map to this map. These mappings will be added to any mappings that this map had for any of the keys currently in the specified map.

Specified by:

putAll in interface java.util.Map<K,V>

Overrides:

putAll in class java.util.AbstractMap<K,V>

Parameters:

fromMap - Mappings to be stored in this map.

Throws:

java.lang.ClassCastException - if the class of a key or value in the specified map prevents it from being stored in this map.

java.lang.IllegalArgumentException - some aspect of a key or value in the specified map prevents it from being stored in this map.

java.lang.NullPointerException - the specified key or value is null.

putAll

public void putAll(MultiValueMap<K,V> fromMap)

Copies all of the mappings from the specified MultivalueMap to this map. These mappings will be added to any mappings that this map had for any of the keys currently in the specified map.

Parameters:

fromMap - Mappings to be stored in this map.

Throws:

java.lang.ClassCastException - if the class of a key or value in the specified map prevents it from being stored in this map.

java.lang.IllegalArgumentException - some aspect of a key or value in the specified map prevents it from being stored in this map.

java.lang.NullPointerException - the specified key or value is null.

putAll

public void putAll(K key,
                   java.util.Collection<V> values)

Assocates all the objects in a Collection with a key. This method is equivalent to the following code fragment:

 for (Iterator it = values.iterator(); it.hasNext(); )
    map.put (key, it.next());
 

Parameters:

key - the key

values - the collection of values to associate with the key

remove

public java.util.Collection<V> remove(K key)

Removes all mappings for a key from this map, if present.

Parameters:

key - key whose mappings are to be removed from the map.

Returns:

Collection of values associated with specified key, or null if there was no mapping for key.

remove

public boolean remove(K key,
                      V value)

Removes a single value from the set of values associated with a key.

Parameters:

key - the key

value - the value to find and remove

Returns:

true if the value was found and removed. false if the value isn't associated with the key.

size

public int size()

Returns the number of key-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:

size in interface java.util.Map<K,V>

Overrides:

size in class java.util.AbstractMap<K,V>

Returns:

the number of key-value mappings in this map.

totalValuesForKey

public int totalValuesForKey(K key)

Gets the total number of values mapped to a specific key.

Parameters:

key - the key to test

Returns:

the number of values mapped to the key, or 0 if the key isn't present in the map.

Throws:

java.lang.NullPointerException - if the key is null and this map does not not permit null keys.

See Also:

getValuesForKey(K)

values

public java.util.Collection<V> values()

Returns a collection view of the values contained in this map. The returned collection is a "thin" view of the values contained in this map. If a value is associated with more than one key (as determined by the value's equals() method), it will only appear once in the returned Collection. The values are sorted (via their compareTo() methods) in the returned Collection.

Warning: Unlike the SDK's Map class, the returned Collection is not backed by this map; instead, it represents a snapshot of the values in the map. Subsequent changes to this map object are not reflected in the returned Collection.

Specified by:

values in interface java.util.Map<K,V>

Overrides:

values in class java.util.AbstractMap<K,V>

Returns:

a collection view of the values contained in this map.

See Also:

keySet(), getValuesForKey(K)

getValuesForKey

public java.util.Collection<V> getValuesForKey(K key)

Return an unmodifiable Collection of all the values for a specific key.

Parameters:

key - The key

Returns:

an unmodifiable Collection of all the values associated with the key, or null if there are no values associated with the key

Throws:

java.lang.NullPointerException - if the key is null and this map does not not permit null keys.

See Also:

keySet(), totalValuesForKey(K), values()

getValuesForKey

public int getValuesForKey(K key,
                           java.util.Collection<V> values)

Copy all the values for a specific key into a caller-supplied Collection.

Parameters:

key - The key

values - The Collection to receive the values

Returns:

the number of values copied to the collection

Throws:

java.lang.NullPointerException - if the key is null and this map does not not permit null keys.

See Also:

keySet(), totalValuesForKey(K), values()