Basic implementation of the Multimap interface. This class represents a multimap as a map that associates each key with a collection of values. All methods of Multimap are supported, including those specified as optional in the interface.

To implement a multimap, a subclass must define the method createCollection(), which creates an empty collection of values for a key.

The multimap constructor takes a map that has a single entry for each distinct key. When you insert a key-value pair with a key that isn't already in the multimap, AbstractMapBasedMultimap calls createCollection() to create the collection of values for that key. The subclass should not call createCollection() directly, and a new instance should be created every time the method is called.

For example, the subclass could pass a java.util.TreeMap during construction, and createCollection() could return a java.util.TreeSet, in which case the multimap's iterators would propagate through the keys and values in sorted order.

Keys and values may be null, as long as the underlying collection classes support null elements.

The collections created by createCollection() may or may not allow duplicates. If the collection, such as a Set, does not support duplicates, an added key-value pair will replace an existing pair with the same key and value, if such a pair is present. With collections like List that allow duplicates, the collection will keep the existing key-value pairs while adding a new pair.

This class is not threadsafe when any concurrent operations update the multimap, even if the underlying map and createCollection() method return threadsafe classes. Concurrent read operations will work correctly. To allow concurrent update operations, wrap your multimap with a call to Multimaps#synchronizedMultimap.

For serialization to work, the subclass must specify explicit readObject and writeObject methods.