javadoc.com.google.common.collect.Multimaps.html Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of guava-osgi

Repackaging of Google Guava libraries as OSGi bundle

The newest version!








Multimaps (Guava: Google Core Libraries for Java 11.0.1 API)























  
      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



@GwtCompatible(emulated=true)
public final class Multimapsextends Object




Provides static methods acting on or generating a Multimap.




Since:
  2.0 (imported from Google Collections Library)
Author:
  Jared Levy, Robert Konigsberg, Mike Bostock, Louis Wasserman











Method Summary



static



<K,V> Multimap<K,V>



filterEntries(Multimap<K,V> unfiltered,
                           Predicate<? super Map.Entry<K,V>> entryPredicate)



          Returns a multimap containing the mappings in unfiltered that
 satisfy a predicate.



static



<K,V> Multimap<K,V>



filterKeys(Multimap<K,V> unfiltered,
                     Predicate<? super K> keyPredicate)



          Returns a multimap containing the mappings in unfiltered whose keys
 satisfy a predicate.



static



<K,V> Multimap<K,V>



filterValues(Multimap<K,V> unfiltered,
                         Predicate<? super V> valuePredicate)



          Returns a multimap containing the mappings in unfiltered whose values
 satisfy a predicate.



static



<K,V> SetMultimap<K,V>



forMap(Map<K,V> map)



          Returns a multimap view of the specified map.



static



<K,V,I extends Object & Iterable<V> & Iterator<V>> 


ImmutableListMultimap<K,V>



index(I values,
           Function<? super V,K> keyFunction)



          Deprecated. use index(Iterator, Function) by casting values to Iterator<V>, or better yet, by implementing only
     Iterator and not Iterable. This method is scheduled
     for deletion in March 2012.



static



<K,V> ImmutableListMultimap<K,V>



index(Iterable<V> values,
           Function<? super V,K> keyFunction)



          Creates an index ImmutableListMultimap that contains the results of
 applying a specified function to each item in an Iterable of
 values.



static



<K,V> ImmutableListMultimap<K,V>



index(Iterator<V> values,
           Function<? super V,K> keyFunction)



          Creates an index ImmutableListMultimap that contains the results of
 applying a specified function to each item in an Iterator 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,V1,V2> ListMultimap<K,V2>



transformEntries(ListMultimap<K,V1> fromMap,
                                 Maps.EntryTransformer<? super K,? super V1,V2> transformer)



          Returns a view of a ListMultimap whose values are derived from the
 original multimap's entries.



static



<K,V1,V2> Multimap<K,V2>



transformEntries(Multimap<K,V1> fromMap,
                                 Maps.EntryTransformer<? super K,? super V1,V2> transformer)



          Returns a view of a multimap whose values are derived from the original
 multimap's entries.



static



<K,V1,V2> ListMultimap<K,V2>



transformValues(ListMultimap<K,V1> fromMultimap,
                               Function<? super V1,V2> function)



          Returns a view of a ListMultimap where each value is transformed by
 a function.



static



<K,V1,V2> Multimap<K,V2>



transformValues(Multimap<K,V1> fromMultimap,
                               Function<? super V1,V2> function)



          Returns a view of a multimap where each value is transformed by a function.



static



<K,V> ListMultimap<K,V>



unmodifiableListMultimap(ImmutableListMultimap<K,V> delegate)



          Deprecated. no need to use this



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(ImmutableMultimap<K,V> delegate)



          Deprecated. no need to use this



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(ImmutableSetMultimap<K,V> delegate)



          Deprecated. no need to use this



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, they should be empty when provided, 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.

 If source is an ImmutableMultimap, consider using
 ImmutableMultimap.inverse() instead.


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





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

Deprecated. no need to use this

Simply returns its argument.


Since:
  10.0






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





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

Deprecated. no need to use this

Simply returns its argument.


Since:
  10.0






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





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

Deprecated. no need to use this

Simply returns its argument.


Since:
  10.0






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





transformValues
@Beta
public static <K,V1,V2> Multimap<K,V2> transformValues(Multimap<K,V1> fromMultimap,
                                                            Function<? super V1,V2> function)

Returns a view of a multimap where each value is transformed by a function.
 All other properties of the multimap, such as iteration order, are left
 intact. For example, the code:    Multimap<String, Integer> multimap =
     ImmutableSetMultimap.of("a", 2, "b", -3, "b", -3, "a", 4, "c", 6);
 Function<Integer, String> square = new Function<Integer, String>() {
     public String apply(Integer in) {
       return Integer.toString(in * in);
     }
 };
 Multimap<String, String> transformed =
     Multimaps.transformValues(multimap, square);
   System.out.println(transformed);

 ... prints {a=[4, 16], b=[9, 9], c=[6]}.

 Changes in the underlying multimap are reflected in this view.
 Conversely, this view supports removal operations, and these are reflected
 in the underlying multimap.

 
It's acceptable for the underlying multimap to contain null keys, and
 even null values provided that the function is capable of accepting null
 input.  The transformed multimap might contain null values, if the function
 sometimes gives a null result.

 
The returned multimap is not thread-safe or serializable, even if the
 underlying multimap is.  The equals and hashCode methods
 of the returned multimap are meaningless, since there is not a definition
 of equals or hashCode for general collections, and
 get() will return a general Collection as opposed to a
 List or a Set.

 
The function is applied lazily, invoked when needed. This is necessary
 for the returned multimap to be a view, but it means that the function will
 be applied many times for bulk operations like
 Multimap.containsValue(java.lang.Object) and Multimap.toString(). For this to
 perform well, function should be fast. To avoid lazy evaluation
 when the returned multimap doesn't need to be a view, copy the returned
 multimap into a new multimap of your choosing.


Since:
  7.0






transformEntries
@Beta
public static <K,V1,V2> Multimap<K,V2> transformEntries(Multimap<K,V1> fromMap,
                                                             Maps.EntryTransformer<? super K,? super V1,V2> transformer)

Returns a view of a multimap whose values are derived from the original
 multimap's entries. In contrast to transformValues(com.google.common.collect.Multimap, com.google.common.base.Function), this method's
 entry-transformation logic may depend on the key as well as the value.

 All other properties of the transformed multimap, such as iteration
 order, are left intact. For example, the code: 
   SetMultimap<String, Integer> multimap =
       ImmutableSetMultimap.of("a", 1, "a", 4, "b", -6);
   EntryTransformer<String, Integer, String> transformer =
       new EntryTransformer<String, Integer, String>() {
         public String transformEntry(String key, Integer value) {
            return (value >= 0) ? key : "no" + key;
         }
       };
   Multimap<String, String> transformed =
       Multimaps.transformEntries(multimap, transformer);
   System.out.println(transformed);

 ... prints {a=[a, a], b=[nob]}.

 Changes in the underlying multimap are reflected in this view.
 Conversely, this view supports removal operations, and these are reflected
 in the underlying multimap.

 
It's acceptable for the underlying multimap to contain null keys and
 null values provided that the transformer is capable of accepting null
 inputs. The transformed multimap might contain null values if the
 transformer sometimes gives a null result.

 
The returned multimap is not thread-safe or serializable, even if the
 underlying multimap is.  The equals and hashCode methods
 of the returned multimap are meaningless, since there is not a definition
 of equals or hashCode for general collections, and
 get() will return a general Collection as opposed to a
 List or a Set.

 
The transformer is applied lazily, invoked when needed. This is
 necessary for the returned multimap to be a view, but it means that the
 transformer will be applied many times for bulk operations like Multimap.containsValue(java.lang.Object) and Object.toString(). For this to perform
 well, transformer should be fast. To avoid lazy evaluation when the
 returned multimap doesn't need to be a view, copy the returned multimap
 into a new multimap of your choosing.

 
Warning: This method assumes that for any instance k of
 EntryTransformer key type K, k.equals(k2) implies
 that k2 is also of type K. Using an EntryTransformer key type for which this may not hold, such as ArrayList, may risk a ClassCastException when calling methods on
 the transformed multimap.


Since:
  7.0






transformValues
@Beta
public static <K,V1,V2> ListMultimap<K,V2> transformValues(ListMultimap<K,V1> fromMultimap,
                                                                Function<? super V1,V2> function)

Returns a view of a ListMultimap where each value is transformed by
 a function. All other properties of the multimap, such as iteration order,
 are left intact. For example, the code:    ListMultimap<String, Integer> multimap
        = ImmutableListMultimap.of("a", 4, "a", 16, "b", 9);
   Function<Integer, Double> sqrt =
       new Function<Integer, Double>() {
         public Double apply(Integer in) {
           return Math.sqrt((int) in);
         }
       };
   ListMultimap<String, Double> transformed = Multimaps.transformValues(map,
       sqrt);
   System.out.println(transformed);

 ... prints {a=[2.0, 4.0], b=[3.0]}.

 Changes in the underlying multimap are reflected in this view.
 Conversely, this view supports removal operations, and these are reflected
 in the underlying multimap.

 
It's acceptable for the underlying multimap to contain null keys, and
 even null values provided that the function is capable of accepting null
 input.  The transformed multimap might contain null values, if the function
 sometimes gives a null result.

 
The returned multimap is not thread-safe or serializable, even if the
 underlying multimap is.

 
The function is applied lazily, invoked when needed. This is necessary
 for the returned multimap to be a view, but it means that the function will
 be applied many times for bulk operations like
 Multimap.containsValue(java.lang.Object) and Multimap.toString(). For this to
 perform well, function should be fast. To avoid lazy evaluation
 when the returned multimap doesn't need to be a view, copy the returned
 multimap into a new multimap of your choosing.


Since:
  7.0






transformEntries
@Beta
public static <K,V1,V2> ListMultimap<K,V2> transformEntries(ListMultimap<K,V1> fromMap,
                                                                 Maps.EntryTransformer<? super K,? super V1,V2> transformer)

Returns a view of a ListMultimap whose values are derived from the
 original multimap's entries. In contrast to
 transformValues(ListMultimap, Function), this method's
 entry-transformation logic may depend on the key as well as the value.

 All other properties of the transformed multimap, such as iteration
 order, are left intact. For example, the code: 
   Multimap<String, Integer> multimap =
       ImmutableMultimap.of("a", 1, "a", 4, "b", 6);
   EntryTransformer<String, Integer, String> transformer =
       new EntryTransformer<String, Integer, String>() {
         public String transformEntry(String key, Integer value) {
           return key + value;
         }
       };
   Multimap<String, String> transformed =
       Multimaps.transformEntries(multimap, transformer);
   System.out.println(transformed);

 ... prints {"a"=["a1", "a4"], "b"=["b6"]}.

 Changes in the underlying multimap are reflected in this view.
 Conversely, this view supports removal operations, and these are reflected
 in the underlying multimap.

 
It's acceptable for the underlying multimap to contain null keys and
 null values provided that the transformer is capable of accepting null
 inputs. The transformed multimap might contain null values if the
 transformer sometimes gives a null result.

 
The returned multimap is not thread-safe or serializable, even if the
 underlying multimap is.

 
The transformer is applied lazily, invoked when needed. This is
 necessary for the returned multimap to be a view, but it means that the
 transformer will be applied many times for bulk operations like Multimap.containsValue(java.lang.Object) and Object.toString(). For this to perform
 well, transformer should be fast. To avoid lazy evaluation when the
 returned multimap doesn't need to be a view, copy the returned multimap
 into a new multimap of your choosing.

 
Warning: This method assumes that for any instance k of
 EntryTransformer key type K, k.equals(k2) implies
 that k2 is also of type K. Using an EntryTransformer key type for which this may not hold, such as ArrayList, may risk a ClassCastException when calling methods on
 the transformed multimap.


Since:
  7.0






index
public static <K,V> ImmutableListMultimap<K,V> index(Iterable<V> values,
                                                     Function<? super V,K> keyFunction)

Creates an index ImmutableListMultimap 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. In the returned multimap, keys appear in the order they are first
 encountered, and the values corresponding to each key appear in the same
 order as they are encountered.

 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], 6=[Blinky], 5=[Pinky, Pinky, Clyde]}

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


Parameters:
values - the values to use when constructing the ImmutableListMultimap
keyFunction - the function used to produce the key for each value
Returns:
ImmutableListMultimap 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
     





index
@Beta
@Deprecated
public static <K,V,I extends Object & Iterable<V> & Iterator<V>> ImmutableListMultimap<K,V> index(I values,
                                                                                                                Function<? super V,K> keyFunction)

Deprecated. use index(Iterator, Function) by casting values to Iterator<V>, or better yet, by implementing only
     Iterator and not Iterable. This method is scheduled
     for deletion in March 2012.

Deprecated.


Since:
  10.0






index
public static <K,V> ImmutableListMultimap<K,V> index(Iterator<V> values,
                                                     Function<? super V,K> keyFunction)

Creates an index ImmutableListMultimap that contains the results of
 applying a specified function to each item in an Iterator of
 values. Each value will be stored as a value in the resulting multimap,
 yielding a multimap with the same size as the input iterator. 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. In the returned multimap, keys appear in the order they are first
 encountered, and the values corresponding to each key appear in the same
 order as they are encountered.

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

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

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


Parameters:
values - the values to use when constructing the ImmutableListMultimap
keyFunction - the function used to produce the key for each value
Returns:
ImmutableListMultimap 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
     
Since:
  10.0






filterKeys
@Beta
@GwtIncompatible(value="untested")
public static <K,V> Multimap<K,V> filterKeys(Multimap<K,V> unfiltered,
                                                                       Predicate<? super K> keyPredicate)

Returns a multimap containing the mappings in unfiltered whose keys
 satisfy a predicate. The returned multimap is a live view of
 unfiltered; changes to one affect the other.

 The resulting multimap's views have iterators that don't support
 remove(), but all other methods are supported by the multimap and
 its views. When adding a key that doesn't satisfy the predicate, the
 multimap's put(), putAll(), and  methods
 throw an IllegalArgumentException.

 
When methods such as removeAll() and clear() are called on
 the filtered multimap or its views, only mappings whose keys satisfy the
 filter will be removed from the underlying multimap.

 
The returned multimap isn't threadsafe or serializable, even if
 unfiltered is.

 
Many of the filtered multimap's methods, such as size(), iterate
 across every key/value mapping in the underlying multimap and determine
 which satisfy the filter. When a live view is not needed, it may be
 faster to copy the filtered multimap and use the copy.

 
Warning: keyPredicate must be consistent with equals,
 as documented at Predicate.apply(T). Do not provide a predicate such
 as Predicates.instanceOf(ArrayList.class), which is inconsistent
 with equals.


Since:
  11.0






filterValues
@Beta
@GwtIncompatible(value="untested")
public static <K,V> Multimap<K,V> filterValues(Multimap<K,V> unfiltered,
                                                                         Predicate<? super V> valuePredicate)

Returns a multimap containing the mappings in unfiltered whose values
 satisfy a predicate. The returned multimap is a live view of
 unfiltered; changes to one affect the other.

 The resulting multimap's views have iterators that don't support
 remove(), but all other methods are supported by the multimap and
 its views. When adding a value that doesn't satisfy the predicate, the
 multimap's put(), putAll(), and  methods
 throw an IllegalArgumentException.

 
When methods such as removeAll() and clear() are called on
 the filtered multimap or its views, only mappings whose value satisfy the
 filter will be removed from the underlying multimap.

 
The returned multimap isn't threadsafe or serializable, even if
 unfiltered is.

 
Many of the filtered multimap's methods, such as size(), iterate
 across every key/value mapping in the underlying multimap and determine
 which satisfy the filter. When a live view is not needed, it may be
 faster to copy the filtered multimap and use the copy.

 
Warning: valuePredicate must be consistent with
 equals, as documented at Predicate.apply(T). Do not provide a
 predicate such as Predicates.instanceOf(ArrayList.class), which is
 inconsistent with equals.


Since:
  11.0






filterEntries
@Beta
@GwtIncompatible(value="untested")
public static <K,V> Multimap<K,V> filterEntries(Multimap<K,V> unfiltered,
                                                                          Predicate<? super Map.Entry<K,V>> entryPredicate)

Returns a multimap containing the mappings in unfiltered that
 satisfy a predicate. The returned multimap is a live view of
 unfiltered; changes to one affect the other.

 The resulting multimap's views have iterators that don't support
 remove(), but all other methods are supported by the multimap and
 its views. When adding a key/value pair that doesn't satisfy the predicate,
 multimap's put(), putAll(), and  methods
 throw an IllegalArgumentException.

 
When methods such as removeAll() and clear() are called on
 the filtered multimap or its views, only mappings whose keys satisfy the
 filter will be removed from the underlying multimap.

 
The returned multimap isn't threadsafe or serializable, even if
 unfiltered is.

 
Many of the filtered multimap's methods, such as size(), iterate
 across every key/value mapping in the underlying multimap and determine
 which satisfy the filter. When a live view is not needed, it may be
 faster to copy the filtered multimap and use the copy.

 
Warning: entryPredicate must be consistent with
 equals, as documented at Predicate.apply(T).


Since:
  11.0















  
      Overview 
      Package 
    Class 
      Use 
      Tree 
      Deprecated 
      Index 
      Help 
  









 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES   
 







  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD






Copyright © 2010-2012. All Rights Reserved.

javadoc.com.google.common.collect.Multimaps.html Maven / Gradle / Ivy

com.google.common.collect Class Multimaps

newMultimap

newListMultimap

newSetMultimap

newSortedSetMultimap

invertFrom

synchronizedMultimap

unmodifiableMultimap

unmodifiableMultimap

synchronizedSetMultimap

unmodifiableSetMultimap

unmodifiableSetMultimap

synchronizedSortedSetMultimap

unmodifiableSortedSetMultimap

synchronizedListMultimap

unmodifiableListMultimap

unmodifiableListMultimap

forMap

transformValues

transformEntries

transformValues

transformEntries

index

index

index

filterKeys

filterValues

filterEntries

com.google.common.collect
Class Multimaps