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.google.common.collect
Class Multimaps

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

    public final class Multimaps

extends 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(Map<K,V> map)` Returns a multimap view of the specified map.
`static
`<K,V> ImmutableListMultimap<K,V>`
` | `index(Iterable<V> values, Function<? super V,K> keyFunction)` Creates an index `ImmutableMultimap` that contains the results of applying a specified function to each item in an `Iterable` of values.
`static
`<K,V,M extends Multimap<K,V>> M`
` | `invertFrom(Multimap<? extends V,? extends K> source, M dest)` Copies each key-value mapping in `source` into `dest`, with its key and value reversed.
`static
`<K,V> ListMultimap<K,V>`
` | `newListMultimap(Map<K,Collection<V>> map, Supplier<? extends List<V>> factory)` Creates a new `ListMultimap` that uses the provided map and factory.
`static
`<K,V> Multimap<K,V>`
` | `newMultimap(Map<K,Collection<V>> map, Supplier<? extends Collection<V>> factory)` Creates a new `Multimap` that uses the provided map and factory.
`static
`<K,V> SetMultimap<K,V>`
` | `newSetMultimap(Map<K,Collection<V>> map, Supplier<? extends Set<V>> factory)` Creates a new `SetMultimap` that uses the provided map and factory.
`static
`<K,V> SortedSetMultimap<K,V>`
` | `newSortedSetMultimap(Map<K,Collection<V>> map, Supplier<? extends SortedSet<V>> factory)` Creates a new `SortedSetMultimap` that uses the provided map and factory.
`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

### newMultimap

    public static <K,V> Multimap<K,V> newMultimap(Map<K,Collection<V>> map,
                                                  Supplier<? extends 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 multimap'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 `ArrayListMultimap.create()`, `HashMultimap.create()`, `LinkedHashMultimap.create()`, `LinkedListMultimap.create()`, `TreeMultimap.create()`, and `TreeMultimap.create(Comparator, Comparator)` won't suffice.

  Note: the multimap assumes complete ownership over of `map` and the collections returned by `factory`. Those objects should not be manually updated and they should not use soft, weak, or phantom references.

  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:
    `IllegalArgumentException` - if `map` is not empty

### newListMultimap

    public static <K,V> ListMultimap<K,V> newListMultimap(Map<K,Collection<V>> map,
                                                          Supplier<? extends 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. The multimap's `get`, `removeAll`, and `replaceValues` methods return `RandomAccess` lists if the factory does. However, the multimap's `get` method returns instances of a different class than does `factory.get()`.

  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 methods `ArrayListMultimap.create()` and `LinkedListMultimap.create()` won't suffice.

  Note: the multimap assumes complete ownership over of `map` and the lists returned by `factory`. Those objects should not be manually updated and they should not use soft, weak, or phantom references.

  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:
    `IllegalArgumentException` - if `map` is not empty

### newSetMultimap

    public static <K,V> SetMultimap<K,V> newSetMultimap(Map<K,Collection<V>> map,
                                                        Supplier<? extends 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 multimap'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 `HashMultimap.create()`, `LinkedHashMultimap.create()`, `TreeMultimap.create()`, and `TreeMultimap.create(Comparator, Comparator)` won't suffice.

  Note: the multimap assumes complete ownership over of `map` and the sets returned by `factory`. Those objects should not be manually updated and they should not use soft, weak, or phantom references.

  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:
    `IllegalArgumentException` - if `map` is not empty

### newSortedSetMultimap

    public static <K,V> SortedSetMultimap<K,V> newSortedSetMultimap(Map<K,Collection<V>> map,
                                                                    Supplier<? extends 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 multimap'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 methods `TreeMultimap.create()` and `TreeMultimap.create(Comparator, Comparator)` won't suffice.

  Note: the multimap assumes complete ownership over of `map` and the sets returned by `factory`. Those objects should not be manually updated and they should not use soft, weak, or phantom references.

  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:
    `IllegalArgumentException` - if `map` is not empty

### invertFrom

    public static <K,V,M extends Multimap<K,V>> M invertFrom(Multimap<? extends V,? extends K> source,
                                                             M dest)

  Copies each key-value mapping in `source` into `dest`, with its key and value reversed.

  Parameters:
    `source` - any multimap
    `dest` - the multimap to copy into; usually empty
  Returns:
    `dest`

### 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 multimap when accessing any of its collection views:

        Multimap<K, V> m = Multimaps.synchronizedMultimap(
            HashMultimap.<K, V>create());
        ...
        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.

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

  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.

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

  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)`.

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

  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.

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

  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)`.

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

  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.

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

  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.

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

  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(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> ImmutableListMultimap<K,V> index(Iterable<V> values,
                                                         Function<? super V,K> keyFunction)

  Creates an index `ImmutableMultimap` 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 immutable 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]}

  The returned multimap is serializable if its keys and values are all serializable.

  Parameters:
    `values` - the values to use when constructing the `ImmutableMultimap`
    `keyFunction` - the function used to produce the key for each value
  Returns:
    `ImmutableMultimap` mapping the result of evaluating the function `keyFunction` on each value in the input collection to that value
  Throws:
    `NullPointerException` - if any of the following cases is true:
    - `values` is null
    - `keyFunction` is null
    - An element in `values` is null
    - `keyFunction` returns null for any element of `values`

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