A collection similar to a {@code Map}, but which may associate multiple values with a single key. If you call {@link #put} twice, with the same keybut different values, the multimap contains mappings from the key to both values.
The methods {@link #get}, {@link #keySet}, {@link #keys}, {@link #values}, {@link #entries}, and {@link #asMap} return collections that are views of themultimap. If the multimap is modifiable, updating it can change the contents of those collections, and updating the collections will change the multimap. In contrast, {@link #replaceValues} and {@link #removeAll} return collectionsthat are independent of subsequent multimap changes.
Depending on the implementation, a multimap may or may not allow duplicate key-value pairs. In other words, the multimap contents after adding the same key and value twice varies between implementations. In multimaps allowing duplicates, the multimap will contain two mappings, and {@code get} willreturn a collection that includes the value twice. In multimaps not supporting duplicates, the multimap will contain a single mapping from the key to the value, and {@code get} will return a collection that includes thevalue once.
All methods that alter the multimap are optional, and the views returned by the multimap may or may not be modifiable. When modification isn't supported, those methods will throw an {@link UnsupportedOperationException}.
@author Jared Levy
@param < K> the type of keys maintained by this multimap
@param < V> the type of mapped values
@since Guava release 02 (imported from Google Collections Library)