com.neoworks.util
Interface MultiMap

All Known Subinterfaces:

SortedMultiMap

All Known Implementing Classes:

AbstractMultiMap, HashMapMultiMap

public interface MultiMap

An object that maps keys to multiple values. A multimap can contain duplicate keys, this is something that Map objects cannot do.

The MultiMap interface provides three collection views, which allow a multimap's contents to be viewed as a set of keys, collection of values, or set of key-values mappings. The order of a multimap is defined as the order in which the iterators on the multimap's collection views return their elements.

Note: great care must be exercised if mutable objects are used as multimap keys. The behavior of a multimap is not specified if the value of an object is changed in a manner that affects equals comparisons while the object is a key in the multimap. A special case of this prohibition is that it is not permissible for a multimap to contain itself as a key. While it is permissible for a multimap to contain itself as a value, extreme caution is advised: the equals and hashCode methods are no longer well defined on a such a multimap.

All general-purpose multimap implementation classes should provide two "standard" constructors: a void (no arguments) constructor which creates an empty multimap, and a constructor with a single argument of type MultiMap, which creates a new multimap with the same key-values mappings as its argument. In effect, the latter constructor allows the user to copy any multimap, producing an equivalent multimap of the desired class. There is no way to enforce this recommendation (as interfaces cannot contain constructors) but all of the general-purpose multimap implementations in the com.neoworks.util package comply.

Version:

0.1

Author:

Stuart Farnan stuart@neoworks.com

Nested Class Summary

static interface

MultiMap.Entry A multimap entry (key-value pair).

Method Summary

void	clear() Removes all mappings from this multimap (optional operation).
boolean	containsKey(java.lang.Object key) Returns true if this multimap contains a mapping for the specified key.
boolean	containsValue(java.lang.Object value) Returns true if this multimap maps one or more keys to the specified value.
java.util.Set	entrySet() Returns a set view of the mappings contained in this multimap.
boolean	equals(java.lang.Object o) Compares the specified object with this multimap for equality.
java.util.Set	get(java.lang.Object key) Returns the set of values to which this multimap maps the specified key.
int	hashCode() Returns the hash code value for this multimap.
boolean	isEmpty() Returns true if this multimap contains no key-value mappings.
java.util.Collection	keys() Returns a collection view of the keys contained in this multimap.
java.util.Set	put(java.lang.Object key, java.lang.Object value) Associates the specified value with the specified key in this multimap (optional operation).
void	putAll(MultiMap multimap) Copies all of the mappings from the specified multimap to this multimap (optional operation).
java.util.Set	remove(java.lang.Object key) Removes all the mappings for this key from this multimap if present (optional operation).
java.lang.Object	remove(java.lang.Object key, java.lang.Object value) Removes the (key, value) mapping from this multimap if present (optional operation).
int	size() Returns the number of key-values mappings in this multimap.
java.util.Collection	uniqueKeys() Returns a collection of the unique keys in this multimap.
java.util.Collection	values() Returns a collection view of the values contained in this multimap.

Method Detail

size

public int size()

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

Returns:

The number of key-values mappings in this multimap

isEmpty

public boolean isEmpty()

Returns true if this multimap contains no key-value mappings.

Returns:

true if this multimap contains no key-value mappings.

containsKey

public boolean containsKey(java.lang.Object key)
                    throws java.lang.ClassCastException,
                           java.lang.NullPointerException

Returns true if this multimap contains a mapping for the specified key.

Parameters:

key - Key whose presence in this multimap is to be tested.

Returns:

true if this multimap contains a mapping for the specified key.

Throws:

java.lang.ClassCastException - If the key is of an inappropriate type for this multimap.

java.lang.NullPointerException - If the key is null and this multimap does not not permit null keys

containsValue

public boolean containsValue(java.lang.Object value)

Returns true if this multimap maps one or more keys to the specified value. More formally, returns true if and only if this multimap contains at least one mapping to a value v such that (value==null ? v==null : value.equals(v)). This operation will probably require time linear in the multimap size for most implementations of the MultiMap interface.

Parameters:

value - Value whose presence in this multimap is to be tested.

Returns:

true if this multimap maps one or more keys to the specified value.

get

public java.util.Set get(java.lang.Object key)
                  throws java.lang.ClassCastException,
                         java.lang.NullPointerException

Returns the set of values to which this multimap maps the specified key. Returns null if the multimap contains no mappings for this key. A return value of null does indicate that the multimap contains no mappings for the key; it's possible that the multimap explicitly maps the key to null, in this case the returned set will contain null possibly along with other objects. The containsKey operation may also be used to distinguish these two cases.

Parameters:

key - Key whose associated value is to be returned.

Returns:

A Set of values to which this multimap maps the specified key, or null if the multimap contains no mapping for this key.

Throws:

java.lang.ClassCastException - If the key is of an inappropriate type for this multimap.

java.lang.NullPointerException - If the key is null and this multimap does not not permit null keys

put

public java.util.Set put(java.lang.Object key,
                         java.lang.Object value)
                  throws java.lang.UnsupportedOperationException,
                         java.lang.ClassCastException,
                         java.lang.IllegalArgumentException,
                         java.lang.NullPointerException

Associates the specified value with the specified key in this multimap (optional operation). If the multimap previously contained a mapping for this key this mapping is not lost.

Parameters:

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

value - Value to be associated with the specified key.

Returns:

Set of values associated with the specified key.

Throws:

java.lang.UnsupportedOperationException - If the put operation is not supported by this multimap.

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

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

java.lang.NullPointerException - This multimap does not permit null keys or values, and the specified key or value is null.

remove

public java.util.Set remove(java.lang.Object key)
                     throws java.lang.UnsupportedOperationException

Removes all the mappings for this key from this multimap if present (optional operation).

Parameters:

key - Key whose mappings is to be removed from the multimap.

Returns:

Set of values associated with the specified key, or null if there were no mappings for key.

Throws:

java.lang.UnsupportedOperationException - If the remove operation is not supported by this multimap.

remove

public java.lang.Object remove(java.lang.Object key,
                               java.lang.Object value)
                        throws java.lang.UnsupportedOperationException

Removes the (key, value) mapping from this multimap if present (optional operation).

Parameters:

value - The value associated with the key to identify the item to remove

key - Key whose mapping to the value is to be removed from the multimap.

Returns:

Value that was unmapped from the specified key, or null if the given mapping did not exist.

Throws:

java.lang.UnsupportedOperationException - If the remove operation is not supported by this multimap.

putAll

public void putAll(MultiMap multimap)
            throws java.lang.UnsupportedOperationException,
                   java.lang.ClassCastException,
                   java.lang.IllegalArgumentException,
                   java.lang.NullPointerException

Copies all of the mappings from the specified multimap to this multimap (optional operation). These mappings will replace any mappings that this multimap had for any of the keys currently in the specified multimap.

Parameters:

multimap - Mappings to be stored in this multimap.

Throws:

java.lang.UnsupportedOperationException - If the put operation is not supported by this multimap.

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

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

java.lang.NullPointerException - This multimap does not permit null keys or values, and the specified key or value is null.

clear

public void clear()
           throws java.lang.UnsupportedOperationException

Removes all mappings from this multimap (optional operation).

Throws:

java.lang.UnsupportedOperationException - If clear is not supported by this multimap.

keys

public java.util.Collection keys()

Returns a collection view of the keys contained in this multimap. The collection is backed by the multimap, so changes to the multimap are reflected in the collection, and vice-versa. If the multimap is modified while an iteration over the collection is in progress, the results of the iteration are undefined. The collection supports element removal, which removes the corresponding mapping from the multimap, via the Iterator.remove, Collection.remove, removeAll retainAll, and clear operations. It does not support the add or addAll operations. Note: As a MultiMap may contain duplicate keys this method may also return duplicate values.

Returns:

A collection view of the keys contained in this multimap.

uniqueKeys

public java.util.Collection uniqueKeys()

Returns a collection of the unique keys in this multimap.

Returns:

A collection view of the unique keys contained in this multimap.

values

public java.util.Collection values()

Returns a collection view of the values contained in this multimap. The collection is backed by the multimap, so changes to the multimap are reflected in the collection, and vice-versa. If the multimap is modified while an iteration over the collection is in progress, the results of the iteration are undefined. The collection supports element removal, which removes the corresponding mapping from the multimap, via the Iterator.remove, Collection.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Returns:

A collection view of the values contained in this multimap.

entrySet

public java.util.Set entrySet()

Returns a set view of the mappings contained in this multimap. Each element in the returned set is a MultiMap.Entry. The set is backed by the multimap, so changes to the multimap are reflected in the set, and vice-versa. If the multimap is modified while an iteration over the set is in progress, the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the multimap, 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 multimap.

equals

public boolean equals(java.lang.Object o)

Compares the specified object with this multimap for equality. Returns true if the given object is also a multimap and the two multimaps 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 MultiMap interface.

Overrides:

equals in class java.lang.Object

Parameters:

o - Object to be compared for equality with this multimap.

Returns:

true if the specified object is equal to this multimap.

hashCode

public int hashCode()

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

Overrides:

hashCode in class java.lang.Object

Returns:

The hash code value for this multimap.