An implementation of ListMultimap that supports deterministic iteration order for both keys and values. The iteration order is preserved across non-distinct key values. For example, for the following multimap definition:

Multimap<K, V> multimap = LinkedListMultimap.create();
multimap.put(key1, foo);
multimap.put(key2, bar);
multimap.put(key1, baz);

... the iteration order for keys() is [key1, key2, key1], and similarly for entries(). Unlike LinkedHashMultimap, the iteration order is kept consistent between keys, entries and values. For example, calling:

multimap.remove(key1, foo);

changes the entries iteration order to [key2=bar, key1=baz] and the key iteration order to [key2, key1]. The entries() iterator returns mutable map entries, and replaceValues attempts to preserve iteration order as much as possible.

The collections returned by keySet() and asMap iterate through the keys in the order they were first added to the multimap. Similarly, get, removeAll, and replaceValues return collections that iterate through the values in the order they were added. The collections generated by entries(), keys(), and values iterate across the key-value mappings in the order they were added to the multimap.

The values() and entries() methods both return a List, instead of the Collection specified by the ListMultimap interface.

The methods get, keySet(), keys(), values, entries(), and asMap return collections that are views of the multimap. If the multimap is modified while an iteration over any of those collections is in progress, except through the iterator's methods, the results of the iteration are undefined.

Keys and values may be null. All optional multimap methods are supported, and all returned views are modifiable.

This class is not threadsafe when any concurrent operations update the multimap. Concurrent read operations will work correctly. To allow concurrent update operations, wrap your multimap with a call to Multimaps#synchronizedListMultimap.

See the Guava User Guide article on Multimap.