Multimap (Goldman Sachs Collections API

Type Parameters:
K - the type of keys used
V - the type of mapped values

All Known Subinterfaces:

BagMultimap<K,V>, ImmutableBagMultimap<K,V>, ImmutableListMultimap<K,V>, ImmutableMultimap<K,V>, ImmutableSetMultimap<K,V>, ImmutableSortedBagMultimap<K,V>, ImmutableSortedSetMultimap<K,V>, ListMultimap<K,V>, MutableBagMultimap<K,V>, MutableListMultimap<K,V>, MutableMultimap<K,V>, MutableSetMultimap<K,V>, MutableSortedBagMultimap<K,V>, MutableSortedSetMultimap<K,V>, ReversibleIterableMultimap<K,V>, SetMultimap<K,V>, SortedBagMultimap<K,V>, SortedIterableMultimap<K,V>, SortedSetMultimap<K,V>, UnsortedBagMultimap<K,V>, UnsortedSetMultimap<K,V>
```
public interface Multimap<K,V>
```
This collection is a type of Map that can associate multiple values for keys.

Unlike Map however, this interface is read-only so the results of access methods such as get(Object) return a view onto the values associated with that key. The MutableMultimap subinterface provides methods to mutate the collection.

The advantages to using this container over a Map<K, Collection<V>> is that all of the handling of the value collection can be done automatically. It also allows implementations to further specialize in how duplicate values will be handled. Value collections with list semantics would allow duplicate values for a key, while those implementing set semantics would not.

Internal iteration methods for keys and values (singly - forEachKey(Procedure), forEachValue(Procedure), and together - forEachKeyValue(Procedure2)) are provided to allow flexible browsing of the collection's contents. Similarly, views also are provided for keys (keysView()), values (valuesView()) and the combination thereof (keyValuePairsView(), keyMultiValuePairsView()).

Since:

1.0

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`containsKey(java.lang.Object key)` Returns `true` if any values are mapped to the specified key.
`boolean`	`containsKeyAndValue(java.lang.Object key, java.lang.Object value)` Returns `true` if the specified key-value pair is mapped.
`boolean`	`containsValue(java.lang.Object value)` Returns `true` if any key is mapped to the specified value.
`boolean`	`equals(java.lang.Object obj)` Compares the specified object with this Multimap for equality.
`void`	`forEachKey(Procedure<? super K> procedure)` Calls the `procedure` with each key.
`void`	`forEachKeyValue(Procedure2<K,V> procedure)` Calls the `procedure` with each key-value pair.
`void`	`forEachValue(Procedure<? super V> procedure)` Calls the procedure with each value.
`RichIterable<V>`	`get(K key)` Returns a view of all values associated with the given key.
`int`	`hashCode()` Returns the hash code for this Multimap.
`boolean`	`isEmpty()` Returns `true` if there are no entries.
`Bag<K>`	`keyBag()` Returns a `Bag` of keys with the count corresponding to the number of mapped values.
`RichIterable<Pair<K,RichIterable<V>>>`	`keyMultiValuePairsView()` Returns a lazy view of the pair of a key and and a lazy view of the values mapped to that key.
`RichIterable<K>`	`keysView()` Returns a lazy view of the unique keys.
`RichIterable<Pair<K,V>>`	`keyValuePairsView()` Returns a lazy view of all of the key/value pairs.
`RichIterable<RichIterable<V>>`	`multiValuesView()` Returns an unmodifiable view of all of the values mapped to each key.
`Multimap<K,V>`	`newEmpty()` Creates a new instance of the same implementation type, using the default capacity and growth parameters.
`boolean`	`notEmpty()` Returns `true` if there is at least one entry.
`int`	`size()` Returns the number of key-value entry pairs.
`int`	`sizeDistinct()` Returns the number of distinct keys.
`ImmutableMultimap<K,V>`	`toImmutable()` Returns an immutable copy of this Multimap if it is not already immutable.
`MutableMap<K,RichIterable<V>>`	`toMap()` Returns a new `MutableMap` of keys from this Multimap to the mapped values as a `RichIterable`.
`<R extends java.util.Collection<V>> MutableMap<K,R>`	`toMap(Function0<R> collectionFactory)` Returns a new `MutableMap` of keys from this Multimap to the mapped values as a `RichIterable`.
`MutableMultimap<K,V>`	`toMutable()` Returns a mutable copy of this Multimap.
`RichIterable<V>`	`valuesView()` Returns a lazy flattened view of all the values.

- Method Detail
  - newEmpty
```
Multimap<K,V> newEmpty()
```
    Creates a new instance of the same implementation type, using the default capacity and growth parameters.
  - isEmpty
```
boolean isEmpty()
```
    Returns true if there are no entries.
  - notEmpty
```
boolean notEmpty()
```
    Returns true if there is at least one entry.
  - forEachValue
```
void forEachValue(Procedure<? super V> procedure)
```
    Calls the procedure with each value.
    Given a Multimap with the contents:
    { "key1" : ["val1", "val2", "val2"], "key2" : ["val3"] }
    The given procedure would be invoked with the parameters:
    [ "val1", "val2", "val2", "val3" ]
  - forEachKey
```
void forEachKey(Procedure<? super K> procedure)
```
    Calls the procedure with each key.
    Given a Multimap with the contents:
    { "key1" : ["val1", "val2", "val2"], "key2" : ["val3"] }
    The given procedure would be invoked with the parameters:
    [ "key1", "key2" ]
  - forEachKeyValue
```
void forEachKeyValue(Procedure2<K,V> procedure)
```
    Calls the procedure with each key-value pair.
    Given a Multimap with the contents:
    { "key1" : ["val1", "val2", "val2"], "key2" : ["val3"] }
    The given procedure would be invoked with the parameters:
    [ ["key1", "val1"], ["key1", "val2"], ["key1", "val2"], ["key2", "val3"] ]
  - size
```
int size()
```
    Returns the number of key-value entry pairs.
    This method is implemented with O(1) (constant-time) performance.
  - sizeDistinct
```
int sizeDistinct()
```
    Returns the number of distinct keys.
  - containsKey
```
boolean containsKey(java.lang.Object key)
```
    Returns true if any values are mapped to the specified key.
    
    Parameters:
    key - the key to search for
  - containsValue
```
boolean containsValue(java.lang.Object value)
```
    Returns true if any key is mapped to the specified value.
    
    Parameters:
    value - the value to search for
  - containsKeyAndValue
```
boolean containsKeyAndValue(java.lang.Object key,
                          java.lang.Object value)
```
    Returns true if the specified key-value pair is mapped.
    
    Parameters:
    key - the key to search for
    value - the value to search for
  - get
```
RichIterable<V> get(K key)
```
    Returns a view of all values associated with the given key.
    If the given key does not exist, an empty RichIterable is returned.
    
    Parameters:
    key - the key to search for
  - keysView
```
RichIterable<K> keysView()
```
    Returns a lazy view of the unique keys.
  - keyBag
```
Bag<K> keyBag()
```
    Returns a Bag of keys with the count corresponding to the number of mapped values.
  - multiValuesView
```
RichIterable<RichIterable<V>> multiValuesView()
```
    Returns an unmodifiable view of all of the values mapped to each key.
  - valuesView
```
RichIterable<V> valuesView()
```
    Returns a lazy flattened view of all the values.
  - keyMultiValuePairsView
```
RichIterable<Pair<K,RichIterable<V>>> keyMultiValuePairsView()
```
    Returns a lazy view of the pair of a key and and a lazy view of the values mapped to that key.
  - keyValuePairsView
```
RichIterable<Pair<K,V>> keyValuePairsView()
```
    Returns a lazy view of all of the key/value pairs.
  - toMap
```
MutableMap<K,RichIterable<V>> toMap()
```
    Returns a new MutableMap of keys from this Multimap to the mapped values as a RichIterable.
  - toMap
```
<R extends java.util.Collection<V>> MutableMap<K,R> toMap(Function0<R> collectionFactory)
```
    Returns a new MutableMap of keys from this Multimap to the mapped values as a RichIterable.
    
    Parameters:
    collectionFactory - used to create the collections that hold the values and affects the return type
  - equals
```
boolean equals(java.lang.Object obj)
```
    Compares the specified object with this Multimap for equality.
    Two Multimaps are equal when their map views (as returned by toMap()) are also equal.
    
    In general, two Multimaps with identical key-value mappings may or may not be equal, depending on the type of the collections holding the values. If the backing collections are Sets, then two instances with the same key-value mappings are equal, but if the backing collections are Lists, equality depends on the ordering of the values for each key.
    Any two empty Multimaps are equal, because they both have empty toMap() views.
    
    Overrides:
    
    equals in class java.lang.Object
  - hashCode
```
int hashCode()
```
    Returns the hash code for this Multimap.
    
    The hash code of a Multimap is defined as the hash code of the map view, as returned by toMap().
    
    Overrides:
    
    hashCode in class java.lang.Object
  - toMutable
```
MutableMultimap<K,V> toMutable()
```
    Returns a mutable copy of this Multimap.
  - toImmutable
```
ImmutableMultimap<K,V> toImmutable()
```
    Returns an immutable copy of this Multimap if it is not already immutable. If the Multimap is immutable, it will return itself.
    The returned Multimap will be Serializable if this Multimap is Serializable.

Interface Multimap<K,V>

Method Summary

Method Detail

newEmpty

isEmpty

notEmpty

forEachValue

forEachKey

forEachKeyValue

size

sizeDistinct

containsKey

containsValue

containsKeyAndValue

get

keysView

keyBag

multiValuesView

valuesView

keyMultiValuePairsView

keyValuePairsView

toMap

toMap

equals

hashCode

toMutable

toImmutable