com.google.common.collect
Class Multimaps

java.lang.Object
  com.google.common.collect.Multimaps

public final class Multimaps
extends java.lang.Object

Provides static methods acting on or generating a Multimap.

Author:

Jared Levy, Robert Konigsberg, Mike Bostock

Method Summary

static <K,V> SetMultimap<K,V>	forMap(java.util.Map<K,V> map) Returns a multimap view of the specified map.
static <K,V> ListMultimap<K,V>	index(java.lang.Iterable<? extends V> values, Function<? super V,? extends K> keyFunction) Creates an index ListMultimap that contains the results of applying a specified function to each item in an Iterable of values.
static <K,V> void	index(java.lang.Iterable<? extends V> values, Function<? super V,? extends K> keyFunction, Multimap<K,V> multimap) Indexes the specified values into a Multimap by applying a specified function to each item in an Iterable of values.
static <K,V> ArrayListMultimap<V,K>	inverseArrayListMultimap(Multimap<K,V> multimap) Creates an ArrayListMultimap that's the inverse of the provided multimap.
static <K,V> HashMultimap<V,K>	inverseHashMultimap(Multimap<K,V> multimap) Creates a HashMultimap that's the inverse of the provided multimap.
static <K extends java.lang.Comparable,V extends java.lang.Comparable> TreeMultimap<V,K>	inverseTreeMultimap(Multimap<K,V> multimap) Creates a TreeMultimap that's the inverse of the provided multimap.
static <K,V> ArrayListMultimap<K,V>	newArrayListMultimap() Creates an empty ArrayListMultimap instance.
static <K,V> ArrayListMultimap<K,V>	newArrayListMultimap(Multimap<? extends K,? extends V> multimap) Creates an ArrayListMultimap instance initialized with all elements from the supplied Multimap.
static <K,V> HashMultimap<K,V>	newHashMultimap() Creates an empty HashMultimap instance.
static <K,V> HashMultimap<K,V>	newHashMultimap(Multimap<? extends K,? extends V> multimap) Creates a HashMultimap instance initialized with all elements from the supplied Multimap.
static <K,V> LinkedHashMultimap<K,V>	newLinkedHashMultimap() Creates an empty LinkedHashMultimap instance.
static <K,V> LinkedHashMultimap<K,V>	newLinkedHashMultimap(Multimap<? extends K,? extends V> multimap) Creates a LinkedHashMultimap instance initialized with all elements from the supplied Multimap.
static <K,V> ListMultimap<K,V>	newListMultimap(java.util.Map<K,java.util.Collection<V>> map, Supplier<? extends java.util.List<V>> factory) Creates a new ListMultimap that uses the provided map and factory.
static <K,V> Multimap<K,V>	newMultimap(java.util.Map<K,java.util.Collection<V>> map, Supplier<? extends java.util.Collection<V>> factory) Creates a new Multimap that uses the provided map and factory.
static <K,V> SetMultimap<K,V>	newSetMultimap(java.util.Map<K,java.util.Collection<V>> map, Supplier<? extends java.util.Set<V>> factory) Creates a new SetMultimap that uses the provided map and factory.
static <K,V> SortedSetMultimap<K,V>	newSortedSetMultimap(java.util.Map<K,java.util.Collection<V>> map, Supplier<? extends java.util.SortedSet<V>> factory) Creates a new SortedSetMultimap that uses the provided map and factory.
static <K extends java.lang.Comparable,V extends java.lang.Comparable> TreeMultimap<K,V>	newTreeMultimap() Creates an empty TreeMultimap instance using the natural ordering of keys and values.
static <K,V> TreeMultimap<K,V>	newTreeMultimap(java.util.Comparator<? super K> keyComparator, java.util.Comparator<? super V> valueComparator) Creates an empty TreeMultimap instance using explicit comparators.
static <K,V> TreeMultimap<K,V>	newTreeMultimap(java.util.Comparator<? super K> keyComparator, java.util.Comparator<? super V> valueComparator, Multimap<? extends K,? extends V> multimap) Creates a TreeMultimap instance using explicit comparators, initialized with all elements from the supplied Multimap.
static <K,V> TreeMultimap<K,V>	newTreeMultimap(Multimap<? extends K,? extends V> multimap) Constructs a TreeMultimap with the same mappings as the specified Multimap.
static <K,V> ListMultimap<K,V>	synchronizedListMultimap(ListMultimap<K,V> multimap) Returns a synchronized (thread-safe) ListMultimap backed by the specified multimap.
static <K,V> Multimap<K,V>	synchronizedMultimap(Multimap<K,V> multimap) Returns a synchronized (thread-safe) multimap backed by the specified multimap.
static <K,V> SetMultimap<K,V>	synchronizedSetMultimap(SetMultimap<K,V> multimap) Returns a synchronized (thread-safe) SetMultimap backed by the specified multimap.
static <K,V> SortedSetMultimap<K,V>	synchronizedSortedSetMultimap(SortedSetMultimap<K,V> multimap) Returns a synchronized (thread-safe) SortedSetMultimap backed by the specified multimap.
static <K,V> ListMultimap<K,V>	unmodifiableListMultimap(ListMultimap<K,V> delegate) Returns an unmodifiable view of the specified ListMultimap.
static <K,V> Multimap<K,V>	unmodifiableMultimap(Multimap<K,V> delegate) Returns an unmodifiable view of the specified multimap.
static <K,V> SetMultimap<K,V>	unmodifiableSetMultimap(SetMultimap<K,V> delegate) Returns an unmodifiable view of the specified SetMultimap.
static <K,V> SortedSetMultimap<K,V>	unmodifiableSortedSetMultimap(SortedSetMultimap<K,V> delegate) Returns an unmodifiable view of the specified SortedSetMultimap.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newHashMultimap

public static <K,V> HashMultimap<K,V> newHashMultimap()

Creates an empty HashMultimap instance.

Returns:

a newly-created, initially-empty HashMultimap

newHashMultimap

public static <K,V> HashMultimap<K,V> newHashMultimap(Multimap<? extends K,? extends V> multimap)

Creates a HashMultimap instance initialized with all elements from the supplied Multimap. If the supplied multimap contains duplicate key-value pairs, those duplicate pairs will only be stored once in the new multimap.

Parameters:

multimap - the multimap whose contents are copied to this multimap.

Returns:

a newly-created and initialized HashMultimap

newArrayListMultimap

public static <K,V> ArrayListMultimap<K,V> newArrayListMultimap()

Creates an empty ArrayListMultimap instance.

Returns:

a newly-created, initially-empty ArrayListMultimap

newArrayListMultimap

public static <K,V> ArrayListMultimap<K,V> newArrayListMultimap(Multimap<? extends K,? extends V> multimap)

Creates an ArrayListMultimap instance initialized with all elements from the supplied Multimap.

Parameters:

multimap - the multimap whose contents are copied to this multimap.

Returns:

a newly-created and initialized ArrayListMultimap

newLinkedHashMultimap

public static <K,V> LinkedHashMultimap<K,V> newLinkedHashMultimap()

Creates an empty LinkedHashMultimap instance.

Returns:

a newly-created, initially-empty LinkedHashMultimap

newLinkedHashMultimap

public static <K,V> LinkedHashMultimap<K,V> newLinkedHashMultimap(Multimap<? extends K,? extends V> multimap)

Creates a LinkedHashMultimap instance initialized with all elements from the supplied Multimap. If the supplied multimap contains duplicate key-value pairs, those duplicate pairs will only be stored once in the new multimap. The new multimap has the same Multimap.entries() iteration order as the input multimap, except for excluding duplicate mappings.

Parameters:

multimap - the multimap whose contents are copied to this multimap.

Returns:

a newly-created and initialized LinkedHashMultimap

newTreeMultimap

public static <K extends java.lang.Comparable,V extends java.lang.Comparable> TreeMultimap<K,V> newTreeMultimap()

Creates an empty TreeMultimap instance using the natural ordering of keys and values. If the supplied multimap contains duplicate key-value pairs, those duplicate pairs will only be stored once in the new multimap.

Returns:

a newly-created, initially-empty TreeMultimap

newTreeMultimap

public static <K,V> TreeMultimap<K,V> newTreeMultimap(Multimap<? extends K,? extends V> multimap)

Constructs a TreeMultimap with the same mappings as the specified Multimap.

If the supplied multimap is an instance of TreeMultimap, the supplied multimap's comparators are copied to the new instance.

If the supplied multimap is not an instance of TreeMultimap, the new multimap is ordered using the natural ordering of the key and value classes. The key and value classes must satisfy the Comparable interface.

Parameters:

multimap - the multimap whose contents are copied to this multimap.

Returns:

a newly-created and initialized TreeMultimap

newTreeMultimap

public static <K,V> TreeMultimap<K,V> newTreeMultimap(@Nullable
                                                      java.util.Comparator<? super K> keyComparator,
                                                      @Nullable
                                                      java.util.Comparator<? super V> valueComparator)

Creates an empty TreeMultimap instance using explicit comparators.

Parameters:

keyComparator - the comparator that determines the key ordering. If it's null, the natural ordering of the keys is used.

valueComparator - the comparator that determines the value ordering. If it's null, the natural ordering of the values is used.

Returns:

a newly-created, initially-empty TreeMultimap

newTreeMultimap

public static <K,V> TreeMultimap<K,V> newTreeMultimap(@Nullable
                                                      java.util.Comparator<? super K> keyComparator,
                                                      @Nullable
                                                      java.util.Comparator<? super V> valueComparator,
                                                      Multimap<? extends K,? extends V> multimap)

Creates a TreeMultimap instance using explicit comparators, initialized with all elements from the supplied Multimap.

Parameters:

multimap - the multimap whose contents are copied to this multimap.

Returns:

a newly-created and initialized TreeMultimap

newMultimap

public static <K,V> Multimap<K,V> newMultimap(java.util.Map<K,java.util.Collection<V>> map,
                                              Supplier<? extends java.util.Collection<V>> factory)

Creates a new Multimap that uses the provided map and factory. It can generate a multimap based on arbitrary Map and Collection classes.

The factory-generated and map classes determine the multimap iteration order. They also specify the behavior of the equals, hashCode, and toString methods for the multimap and its returned views. However, the multimaps's get method returns instances of a different class than factory.get() does.

The multimap is serializable if map, factory, the collections generated by factory, and the multimap contents are all serializable.

The multimap is not threadsafe when any concurrent operations update the multimap, even if map and the instances generated by factory are. Concurrent read operations will work correctly. To allow concurrent update operations, wrap the multimap with a call to synchronizedMultimap(com.google.common.collect.Multimap).

Call this method only when the simpler methods newArrayListMultimap(), newHashMultimap(), newLinkedHashMultimap() and newTreeMultimap() won't suffice.

Parameters:

map - place to store the mapping from each key to its corresponding values

factory - supplier of new empty collections that will each hold all values for a given key

Throws:

java.lang.IllegalArgumentException - if map is not empty

newListMultimap

public static <K,V> ListMultimap<K,V> newListMultimap(java.util.Map<K,java.util.Collection<V>> map,
                                                      Supplier<? extends java.util.List<V>> factory)

Creates a new ListMultimap that uses the provided map and factory. It can generate a multimap based on arbitrary Map and List classes.

The factory-generated and map classes determine the multimap iteration order. They also specify the behavior of the equals, hashCode, and toString methods for the multimap and its returned views. However, the multimaps's get method returns instances of a different class than factory.get() does.

The multimap is serializable if map, factory, the lists generated by factory, and the multimap contents are all serializable.

The multimap is not threadsafe when any concurrent operations update the multimap, even if map and the instances generated by factory are. Concurrent read operations will work correctly. To allow concurrent update operations, wrap the multimap with a call to synchronizedListMultimap(com.google.common.collect.ListMultimap).

Call this method only when the simpler method newArrayListMultimap() won't suffice.

Parameters:

map - place to store the mapping from each key to its corresponding values

factory - supplier of new empty lists that will each hold all values for a given key

Throws:

java.lang.IllegalArgumentException - if map is not empty

newSetMultimap

public static <K,V> SetMultimap<K,V> newSetMultimap(java.util.Map<K,java.util.Collection<V>> map,
                                                    Supplier<? extends java.util.Set<V>> factory)

Creates a new SetMultimap that uses the provided map and factory. It can generate a multimap based on arbitrary Map and Set classes.

The factory-generated and map classes determine the multimap iteration order. They also specify the behavior of the equals, hashCode, and toString methods for the multimap and its returned views. However, the multimaps's get method returns instances of a different class than factory.get() does.

The multimap is serializable if map, factory, the sets generated by factory, and the multimap contents are all serializable.

The multimap is not threadsafe when any concurrent operations update the multimap, even if map and the instances generated by factory are. Concurrent read operations will work correctly. To allow concurrent update operations, wrap the multimap with a call to synchronizedSetMultimap(com.google.common.collect.SetMultimap).

Call this method only when the simpler methods newHashMultimap(), newLinkedHashMultimap(), and newTreeMultimap() won't suffice.

Parameters:

map - place to store the mapping from each key to its corresponding values

factory - supplier of new empty sets that will each hold all values for a given key

Throws:

java.lang.IllegalArgumentException - if map is not empty

newSortedSetMultimap

public static <K,V> SortedSetMultimap<K,V> newSortedSetMultimap(java.util.Map<K,java.util.Collection<V>> map,
                                                                Supplier<? extends java.util.SortedSet<V>> factory)

Creates a new SortedSetMultimap that uses the provided map and factory. It can generate a multimap based on arbitrary Map and SortedSet classes.

The factory-generated and map classes determine the multimap iteration order. They also specify the behavior of the equals, hashCode, and toString methods for the multimap and its returned views. However, the multimaps's get method returns instances of a different class than factory.get() does.

The multimap is serializable if map, factory, the sets generated by factory, and the multimap contents are all serializable.

The multimap is not threadsafe when any concurrent operations update the multimap, even if map and the instances generated by factory are. Concurrent read operations will work correctly. To allow concurrent update operations, wrap the multimap with a call to synchronizedSortedSetMultimap(com.google.common.collect.SortedSetMultimap).

Call this method only when the simpler method newTreeMultimap() won't suffice.

Parameters:

map - place to store the mapping from each key to its corresponding values

factory - supplier of new empty sorted sets that will each hold all values for a given key

Throws:

java.lang.IllegalArgumentException - if map is not empty

inverseHashMultimap

public static <K,V> HashMultimap<V,K> inverseHashMultimap(Multimap<K,V> multimap)

Creates a HashMultimap that's the inverse of the provided multimap. If the input multimap includes the mapping from a key to a value, the returned multimap contains a mapping from the value to the key.

If the input multimap has duplicate key-value mappings, the returned multimap includes the inverse mapping once.

The returned multimap is modifiable. Updating it will not affect the input multimap, and vice versa.

Parameters:

multimap - the multimap to invert

Returns:

the inverse of the input multimap

inverseArrayListMultimap

public static <K,V> ArrayListMultimap<V,K> inverseArrayListMultimap(Multimap<K,V> multimap)

Creates an ArrayListMultimap that's the inverse of the provided multimap. If the input multimap includes the mapping from a key to a value, the returned multimap contains a mapping from the value to the key.

The returned multimap is modifiable. Updating it will not affect the input multimap, and vice versa.

Parameters:

multimap - the multimap to invert

Returns:

the inverse of the input multimap

inverseTreeMultimap

public static <K extends java.lang.Comparable,V extends java.lang.Comparable> TreeMultimap<V,K> inverseTreeMultimap(Multimap<K,V> multimap)

Creates a TreeMultimap that's the inverse of the provided multimap. If the input multimap includes the mapping from a key to a value, the returned multimap contains a mapping from the value to the key. The returned multimap follows the natural ordering of its keys and values.

If the input multimap has duplicate key-value mappings, the returned multimap includes the inverse mapping once.

The returned multimap is modifiable. Updating it will not affect the input map, and vice versa. The returned multimap orders the keys and values according to their natural ordering.

Parameters:

multimap - the multimap to invert

Returns:

the inverse of the input multimap

synchronizedMultimap

public static <K,V> Multimap<K,V> synchronizedMultimap(Multimap<K,V> multimap)

Returns a synchronized (thread-safe) multimap backed by the specified multimap. In order to guarantee serial access, it is critical that all access to the backing multimap is accomplished through the returned multimap.

It is imperative that the user manually synchronize on the returned map when accessing any of its collection views:

  Multimap<K,V> m = Multimaps.synchronizedMultimap(
      new HashMultimap<K,V>());
   ...
  Set<K> s = m.keySet();  // Needn't be in synchronized block
   ...
  synchronized (m) {  // Synchronizing on m, not s!
    Iterator<K> i = s.iterator(); // Must be in synchronized block
    while (i.hasNext()) {
      foo(i.next());
    }
  }

Failure to follow this advice may result in non-deterministic behavior.

Note that the generated multimap's Multimap.removeAll(java.lang.Object) and Multimap.replaceValues(K, java.lang.Iterable) methods return collections that aren't synchronized.

Parameters:

multimap - the multimap to be wrapped in a synchronized view

Returns:

a synchronized view of the specified multimap

unmodifiableMultimap

public static <K,V> Multimap<K,V> unmodifiableMultimap(Multimap<K,V> delegate)

Returns an unmodifiable view of the specified multimap. Query operations on the returned multimap "read through" to the specified multimap, and attempts to modify the returned multimap, either directly or through the multimap's views, result in an UnsupportedOperationException.

Note that the generated multimap's Multimap.removeAll(java.lang.Object) and Multimap.replaceValues(K, java.lang.Iterable) methods return collections that are modifiable.

Parameters:

delegate - the multimap for which an unmodifiable view is to be returned

Returns:

an unmodifiable view of the specified multimap

synchronizedSetMultimap

public static <K,V> SetMultimap<K,V> synchronizedSetMultimap(SetMultimap<K,V> multimap)

Returns a synchronized (thread-safe) SetMultimap backed by the specified multimap.

You must follow the warnings described in synchronizedMultimap(com.google.common.collect.Multimap).

Parameters:

multimap - the multimap to be wrapped

Returns:

a synchronized view of the specified multimap

unmodifiableSetMultimap

public static <K,V> SetMultimap<K,V> unmodifiableSetMultimap(SetMultimap<K,V> delegate)

Returns an unmodifiable view of the specified SetMultimap. Query operations on the returned multimap "read through" to the specified multimap, and attempts to modify the returned multimap, either directly or through the multimap's views, result in an UnsupportedOperationException.

Note that the generated multimap's Multimap.removeAll(java.lang.Object) and Multimap.replaceValues(K, java.lang.Iterable) methods return collections that are modifiable.

Parameters:

delegate - the multimap for which an unmodifiable view is to be returned

Returns:

an unmodifiable view of the specified multimap

synchronizedSortedSetMultimap

public static <K,V> SortedSetMultimap<K,V> synchronizedSortedSetMultimap(SortedSetMultimap<K,V> multimap)

Returns a synchronized (thread-safe) SortedSetMultimap backed by the specified multimap.

You must follow the warnings described in synchronizedMultimap(com.google.common.collect.Multimap).

Parameters:

multimap - the multimap to be wrapped

Returns:

a synchronized view of the specified multimap

unmodifiableSortedSetMultimap

public static <K,V> SortedSetMultimap<K,V> unmodifiableSortedSetMultimap(SortedSetMultimap<K,V> delegate)

Returns an unmodifiable view of the specified SortedSetMultimap. Query operations on the returned multimap "read through" to the specified multimap, and attempts to modify the returned multimap, either directly or through the multimap's views, result in an UnsupportedOperationException.

Note that the generated multimap's Multimap.removeAll(java.lang.Object) and Multimap.replaceValues(K, java.lang.Iterable) methods return collections that are modifiable.

Parameters:

delegate - the multimap for which an unmodifiable view is to be returned

Returns:

an unmodifiable view of the specified multimap

synchronizedListMultimap

public static <K,V> ListMultimap<K,V> synchronizedListMultimap(ListMultimap<K,V> multimap)

Returns a synchronized (thread-safe) ListMultimap backed by the specified multimap.

You must follow the warnings described in synchronizedMultimap(com.google.common.collect.Multimap).

Parameters:

multimap - the multimap to be wrapped

Returns:

a synchronized view of the specified multimap

unmodifiableListMultimap

public static <K,V> ListMultimap<K,V> unmodifiableListMultimap(ListMultimap<K,V> delegate)

Returns an unmodifiable view of the specified ListMultimap. Query operations on the returned multimap "read through" to the specified multimap, and attempts to modify the returned multimap, either directly or through the multimap's views, result in an UnsupportedOperationException.

Note that the generated multimap's Multimap.removeAll(java.lang.Object) and Multimap.replaceValues(K, java.lang.Iterable) methods return collections that are modifiable.

Parameters:

delegate - the multimap for which an unmodifiable view is to be returned

Returns:

an unmodifiable view of the specified multimap

forMap

public static <K,V> SetMultimap<K,V> forMap(java.util.Map<K,V> map)

Returns a multimap view of the specified map. The multimap is backed by the map, so changes to the map are reflected in the multimap, and vice versa. If the map is modified while an iteration over one of the multimap's collection views 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 multimap supports mapping removal, which removes the corresponding mapping from the map. It does not support any operations which might add mappings, such as put, putAll or replaceValues.

The returned multimap will be serializable if the specified map is serializable.

Parameters:

map - the backing map for the returned multimap view

index

public static <K,V> ListMultimap<K,V> index(java.lang.Iterable<? extends V> values,
                                            Function<? super V,? extends K> keyFunction)

Creates an index ListMultimap that contains the results of applying a specified function to each item in an Iterable of values. Each value will be stored as a value in the resulting multimap, yielding a multimap with the same size as the input iterable. The key used to store that value in the multimap will be the result of calling the function on that value. The resulting multimap is created as an unmodifiable snapshot, it does not reflect subsequent changes on the input iterable.

For example,

 List<String> badGuys =
   Arrays.asList("Inky", "Blinky", "Pinky", "Pinky", "Clyde");
 Function<String, Integer> stringLengthFunction = ...;
 Multimap<Integer, String> index
   = Multimaps.index(badGuys, stringLengthFunction);
 System.out.println(index); 

prints

 {4=[Inky], 5=[Pinky, Pinky, Clyde], 6=[Blinky]} 

Parameters:

values - the values to use when constructing the ListMultimap

keyFunction - the function used to produce the key for each value

Returns:

ListMultimap mapping the result of evaluating the function keyFunction on each value in the input collection to that value

index

public static <K,V> void index(java.lang.Iterable<? extends V> values,
                               Function<? super V,? extends K> keyFunction,
                               Multimap<K,V> multimap)

Indexes the specified values into a Multimap by applying a specified function to each item in an Iterable of values. Each value will be stored as a value in the specified multimap. The key used to store that value in the multimap will be the result of calling the function on that value. Depending on the multimap implementation, duplicate entries (equal keys and equal values) may be collapsed.

For example,

 List<String> badGuys =
   Arrays.asList("Inky", "Blinky", "Pinky", "Pinky", "Clyde");
 Function<String, Integer> stringLengthFunction = ...;
 Multimap<Integer, String> index = Multimaps.newHashMultimap();
 Multimaps.index(badGuys, stringLengthFunction, index);
 System.out.println(index); 

prints

 {4=[Inky], 5=[Pinky, Clyde], 6=[Blinky]} 

The HashMultimap collapses the duplicate occurrence of (5, "Pinky").

Parameters:

values - the values to add to the multimap

keyFunction - the function used to produce the key for each value

multimap - the multimap to store the key value pairs