An implementation of {@code ListMultimap} that supports deterministiciteration order for both keys and values. The iteration order is preserved across non-distinct key values. For example, for the following multimap definition:
{@code Multimap multimap = LinkedListMultimap.create(); multimap.put(key1, foo); multimap.put(key2, bar); multimap.put(key1, baz);}
... the iteration order for {@link #keys()} is {@code [key1, key2, key1]}, and similarly for {@link #entries()}. Unlike {@link LinkedHashMultimap}, the iteration order is kept consistent between keys, entries and values. For example, calling:
{@code map.remove(key1, foo);}
changes the entries iteration order to {@code [key2=bar, key1=baz]} and thekey iteration order to {@code [key2, key1]}. The {@link #entries()} iteratorreturns mutable map entries, and {@link #replaceValues} attempts to preserveiteration order as much as possible.
The collections returned by {@link #keySet()} and {@link #asMap} iteratethrough the keys in the order they were first added to the multimap. Similarly, {@link #get}, {@link #removeAll}, and {@link #replaceValues}return collections that iterate through the values in the order they were added. The collections generated by {@link #entries()}, {@link #keys()}, and {@link #values} iterate across the key-value mappings in the order they wereadded to the multimap.
The {@link #values()} and {@link #entries()} methods both return a{@code List}, instead of the {@code Collection} specified by the {@link ListMultimap} interface.
The methods {@link #get}, {@link #keySet()}, {@link #keys()}, {@link #values}, {@link #entries()}, and {@link #asMap} return collectionsthat 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 {@link Multimaps#synchronizedListMultimap}.
@author Mike Bostock
@since Guava release 02 (imported from Google Collections Library)