com.google.common.collect
Class ImmutableMultimapBuilder<K,V>

java.lang.Object
  extended by com.google.common.collect.ImmutableMultimapBuilder<K,V>

public class ImmutableMultimapBuilder<K,V>
extends Object

A convenient way to populate immutable Multimap instances, especially static-final "constant Multimaps". Code such as

   static final Multimap<String,Integer> STRING_TO_INTEGER_MULTIMAP
       = createNumbersMap();

   static Multimap<String,Integer> createNumbersMap() {
     Multimap<String,Integer> multimap = Multimaps.newHashMultimap();
     multimap.put("one", 1);
     multimap.putAll("several", Arrays.asList(1, 2, 3));
     multimap.putAll("many", Arrays.asList(1, 2, 3, 4, 5));
     return Multimaps.unmodifiableMultimap(multimap);
   }
 
... can be rewritten far more simply as ...
   static final Multimap<String,Integer> STRING_TO_INTEGER_MULTIMAP
     = new ImmutableMultimapBuilder<String,Integer>()
       .put("one", 1)
       .putAll("several", 1, 2, 3)
       .putAll("many", 1, 2, 3, 4, 5)
       .getMultimap();
 

The generated multimap is a ListMultimap, which allows duplicate key-value pairs and maintains the value ordering for each key.

Author:
Laura Werner, Kevin Bourrillion

Constructor Summary
ImmutableMultimapBuilder()
          Creates a new ImmutableMultimapBuilder
 
Method Summary
 ListMultimap<K,V> getMultimap()
          Returns a newly-created, immutable Multimap instance containing the keys and values that were specified using put and putAll.
 ImmutableMultimapBuilder<K,V> put(K key, V value)
          Adds a key-value mapping to the multimap that will be returned by getMultimap.
 ImmutableMultimapBuilder<K,V> putAll(K key, Iterable<? extends V> values)
          Stores a collection of values with the same key into the multimap that will be returned by getMultimap.
 ImmutableMultimapBuilder<K,V> putAll(K key, V... values)
          Stores an array of values with the same key into the multimap that will be returned by getMultimap.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ImmutableMultimapBuilder

public ImmutableMultimapBuilder()
Creates a new ImmutableMultimapBuilder

Method Detail

put

public ImmutableMultimapBuilder<K,V> put(@Nullable
                                         K key,
                                         @Nullable
                                         V value)
Adds a key-value mapping to the multimap that will be returned by getMultimap.

Parameters:
key - key with which the specified value is to be associated
value - value to be associated with the specified key
Returns:
this multimap builder (to enable call chaining)
Throws:
IllegalStateException - if getMultimap has already been called

putAll

public ImmutableMultimapBuilder<K,V> putAll(@Nullable
                                            K key,
                                            Iterable<? extends V> values)
Stores a collection of values with the same key into the multimap that will be returned by getMultimap.

Parameters:
key - key to store in the multimap.
values - values to store in the multimap.
Returns:
this multimap builder (to enable call chaining)
Throws:
IllegalStateException - if getMultimap has already been called

putAll

public ImmutableMultimapBuilder<K,V> putAll(@Nullable
                                            K key,
                                            V... values)
Stores an array of values with the same key into the multimap that will be returned by getMultimap.

Parameters:
key - key to store in the multimap.
values - values to store in the multimap.
Returns:
this multimap builder (to enable call chaining)
Throws:
IllegalStateException - if getMultimap has already been called

getMultimap

public ListMultimap<K,V> getMultimap()
Returns a newly-created, immutable Multimap instance containing the keys and values that were specified using put and putAll.

Returns:
a new, immutable ListMultimap instance
Throws:
IllegalStateException - if getMultimap has already been called