Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD