001/* 002 * Copyright (C) 2007 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.google.common.collect; 018 019import static com.google.common.base.Preconditions.checkNotNull; 020import static com.google.common.collect.CollectPreconditions.checkNonnegative; 021import static com.google.common.collect.CollectPreconditions.checkRemove; 022import static com.google.common.collect.NullnessCasts.uncheckedCastNullableTToT; 023import static java.util.Objects.requireNonNull; 024 025import com.google.common.annotations.Beta; 026import com.google.common.annotations.GwtCompatible; 027import com.google.common.annotations.GwtIncompatible; 028import com.google.common.base.Function; 029import com.google.common.base.Predicate; 030import com.google.common.base.Predicates; 031import com.google.common.base.Supplier; 032import com.google.common.collect.Maps.EntryTransformer; 033import com.google.errorprone.annotations.CanIgnoreReturnValue; 034import com.google.errorprone.annotations.concurrent.LazyInit; 035import com.google.j2objc.annotations.Weak; 036import com.google.j2objc.annotations.WeakOuter; 037import java.io.IOException; 038import java.io.ObjectInputStream; 039import java.io.ObjectOutputStream; 040import java.io.Serializable; 041import java.util.AbstractCollection; 042import java.util.Collection; 043import java.util.Collections; 044import java.util.Comparator; 045import java.util.HashSet; 046import java.util.Iterator; 047import java.util.List; 048import java.util.Map; 049import java.util.Map.Entry; 050import java.util.NavigableSet; 051import java.util.NoSuchElementException; 052import java.util.Set; 053import java.util.SortedSet; 054import javax.annotation.CheckForNull; 055import org.checkerframework.checker.nullness.qual.Nullable; 056 057/** 058 * Provides static methods acting on or generating a {@code Multimap}. 059 * 060 * <p>See the Guava User Guide article on <a href= 061 * "https://github.com/google/guava/wiki/CollectionUtilitiesExplained#multimaps"> {@code 062 * Multimaps}</a>. 063 * 064 * @author Jared Levy 065 * @author Robert Konigsberg 066 * @author Mike Bostock 067 * @author Louis Wasserman 068 * @since 2.0 069 */ 070@GwtCompatible(emulated = true) 071@ElementTypesAreNonnullByDefault 072public final class Multimaps { 073 private Multimaps() {} 074 075 /** 076 * Creates a new {@code Multimap} backed by {@code map}, whose internal value collections are 077 * generated by {@code factory}. 078 * 079 * <p><b>Warning: do not use</b> this method when the collections returned by {@code factory} 080 * implement either {@link List} or {@code Set}! Use the more specific method {@link 081 * #newListMultimap}, {@link #newSetMultimap} or {@link #newSortedSetMultimap} instead, to avoid 082 * very surprising behavior from {@link Multimap#equals}. 083 * 084 * <p>The {@code factory}-generated and {@code map} classes determine the multimap iteration 085 * order. They also specify the behavior of the {@code equals}, {@code hashCode}, and {@code 086 * toString} methods for the multimap and its returned views. However, the multimap's {@code get} 087 * method returns instances of a different class than {@code factory.get()} does. 088 * 089 * <p>The multimap is serializable if {@code map}, {@code factory}, the collections generated by 090 * {@code factory}, and the multimap contents are all serializable. 091 * 092 * <p>The multimap is not threadsafe when any concurrent operations update the multimap, even if 093 * {@code map} and the instances generated by {@code factory} are. Concurrent read operations will 094 * work correctly. To allow concurrent update operations, wrap the multimap with a call to {@link 095 * #synchronizedMultimap}. 096 * 097 * <p>Call this method only when the simpler methods {@link ArrayListMultimap#create()}, {@link 098 * HashMultimap#create()}, {@link LinkedHashMultimap#create()}, {@link 099 * LinkedListMultimap#create()}, {@link TreeMultimap#create()}, and {@link 100 * TreeMultimap#create(Comparator, Comparator)} won't suffice. 101 * 102 * <p>Note: the multimap assumes complete ownership over of {@code map} and the collections 103 * returned by {@code factory}. Those objects should not be manually updated and they should not 104 * use soft, weak, or phantom references. 105 * 106 * @param map place to store the mapping from each key to its corresponding values 107 * @param factory supplier of new, empty collections that will each hold all values for a given 108 * key 109 * @throws IllegalArgumentException if {@code map} is not empty 110 */ 111 public static <K extends @Nullable Object, V extends @Nullable Object> Multimap<K, V> newMultimap( 112 Map<K, Collection<V>> map, final Supplier<? extends Collection<V>> factory) { 113 return new CustomMultimap<>(map, factory); 114 } 115 116 private static class CustomMultimap<K extends @Nullable Object, V extends @Nullable Object> 117 extends AbstractMapBasedMultimap<K, V> { 118 transient Supplier<? extends Collection<V>> factory; 119 120 CustomMultimap(Map<K, Collection<V>> map, Supplier<? extends Collection<V>> factory) { 121 super(map); 122 this.factory = checkNotNull(factory); 123 } 124 125 @Override 126 Set<K> createKeySet() { 127 return createMaybeNavigableKeySet(); 128 } 129 130 @Override 131 Map<K, Collection<V>> createAsMap() { 132 return createMaybeNavigableAsMap(); 133 } 134 135 @Override 136 protected Collection<V> createCollection() { 137 return factory.get(); 138 } 139 140 @Override 141 <E extends @Nullable Object> Collection<E> unmodifiableCollectionSubclass( 142 Collection<E> collection) { 143 if (collection instanceof NavigableSet) { 144 return Sets.unmodifiableNavigableSet((NavigableSet<E>) collection); 145 } else if (collection instanceof SortedSet) { 146 return Collections.unmodifiableSortedSet((SortedSet<E>) collection); 147 } else if (collection instanceof Set) { 148 return Collections.unmodifiableSet((Set<E>) collection); 149 } else if (collection instanceof List) { 150 return Collections.unmodifiableList((List<E>) collection); 151 } else { 152 return Collections.unmodifiableCollection(collection); 153 } 154 } 155 156 @Override 157 Collection<V> wrapCollection(@ParametricNullness K key, Collection<V> collection) { 158 if (collection instanceof List) { 159 return wrapList(key, (List<V>) collection, null); 160 } else if (collection instanceof NavigableSet) { 161 return new WrappedNavigableSet(key, (NavigableSet<V>) collection, null); 162 } else if (collection instanceof SortedSet) { 163 return new WrappedSortedSet(key, (SortedSet<V>) collection, null); 164 } else if (collection instanceof Set) { 165 return new WrappedSet(key, (Set<V>) collection); 166 } else { 167 return new WrappedCollection(key, collection, null); 168 } 169 } 170 171 // can't use Serialization writeMultimap and populateMultimap methods since 172 // there's no way to generate the empty backing map. 173 174 /** @serialData the factory and the backing map */ 175 @GwtIncompatible // java.io.ObjectOutputStream 176 private void writeObject(ObjectOutputStream stream) throws IOException { 177 stream.defaultWriteObject(); 178 stream.writeObject(factory); 179 stream.writeObject(backingMap()); 180 } 181 182 @GwtIncompatible // java.io.ObjectInputStream 183 @SuppressWarnings("unchecked") // reading data stored by writeObject 184 private void readObject(ObjectInputStream stream) throws IOException, ClassNotFoundException { 185 stream.defaultReadObject(); 186 factory = (Supplier<? extends Collection<V>>) stream.readObject(); 187 Map<K, Collection<V>> map = (Map<K, Collection<V>>) stream.readObject(); 188 setMap(map); 189 } 190 191 @GwtIncompatible // java serialization not supported 192 private static final long serialVersionUID = 0; 193 } 194 195 /** 196 * Creates a new {@code ListMultimap} that uses the provided map and factory. It can generate a 197 * multimap based on arbitrary {@link Map} and {@link List} classes. 198 * 199 * <p>The {@code factory}-generated and {@code map} classes determine the multimap iteration 200 * order. They also specify the behavior of the {@code equals}, {@code hashCode}, and {@code 201 * toString} methods for the multimap and its returned views. The multimap's {@code get}, {@code 202 * removeAll}, and {@code replaceValues} methods return {@code RandomAccess} lists if the factory 203 * does. However, the multimap's {@code get} method returns instances of a different class than 204 * does {@code factory.get()}. 205 * 206 * <p>The multimap is serializable if {@code map}, {@code factory}, the lists generated by {@code 207 * factory}, and the multimap contents are all serializable. 208 * 209 * <p>The multimap is not threadsafe when any concurrent operations update the multimap, even if 210 * {@code map} and the instances generated by {@code factory} are. Concurrent read operations will 211 * work correctly. To allow concurrent update operations, wrap the multimap with a call to {@link 212 * #synchronizedListMultimap}. 213 * 214 * <p>Call this method only when the simpler methods {@link ArrayListMultimap#create()} and {@link 215 * LinkedListMultimap#create()} won't suffice. 216 * 217 * <p>Note: the multimap assumes complete ownership over of {@code map} and the lists returned by 218 * {@code factory}. Those objects should not be manually updated, they should be empty when 219 * provided, and they should not use soft, weak, or phantom references. 220 * 221 * @param map place to store the mapping from each key to its corresponding values 222 * @param factory supplier of new, empty lists that will each hold all values for a given key 223 * @throws IllegalArgumentException if {@code map} is not empty 224 */ 225 public static <K extends @Nullable Object, V extends @Nullable Object> 226 ListMultimap<K, V> newListMultimap( 227 Map<K, Collection<V>> map, final Supplier<? extends List<V>> factory) { 228 return new CustomListMultimap<>(map, factory); 229 } 230 231 private static class CustomListMultimap<K extends @Nullable Object, V extends @Nullable Object> 232 extends AbstractListMultimap<K, V> { 233 transient Supplier<? extends List<V>> factory; 234 235 CustomListMultimap(Map<K, Collection<V>> map, Supplier<? extends List<V>> factory) { 236 super(map); 237 this.factory = checkNotNull(factory); 238 } 239 240 @Override 241 Set<K> createKeySet() { 242 return createMaybeNavigableKeySet(); 243 } 244 245 @Override 246 Map<K, Collection<V>> createAsMap() { 247 return createMaybeNavigableAsMap(); 248 } 249 250 @Override 251 protected List<V> createCollection() { 252 return factory.get(); 253 } 254 255 /** @serialData the factory and the backing map */ 256 @GwtIncompatible // java.io.ObjectOutputStream 257 private void writeObject(ObjectOutputStream stream) throws IOException { 258 stream.defaultWriteObject(); 259 stream.writeObject(factory); 260 stream.writeObject(backingMap()); 261 } 262 263 @GwtIncompatible // java.io.ObjectInputStream 264 @SuppressWarnings("unchecked") // reading data stored by writeObject 265 private void readObject(ObjectInputStream stream) throws IOException, ClassNotFoundException { 266 stream.defaultReadObject(); 267 factory = (Supplier<? extends List<V>>) stream.readObject(); 268 Map<K, Collection<V>> map = (Map<K, Collection<V>>) stream.readObject(); 269 setMap(map); 270 } 271 272 @GwtIncompatible // java serialization not supported 273 private static final long serialVersionUID = 0; 274 } 275 276 /** 277 * Creates a new {@code SetMultimap} that uses the provided map and factory. It can generate a 278 * multimap based on arbitrary {@link Map} and {@link Set} classes. 279 * 280 * <p>The {@code factory}-generated and {@code map} classes determine the multimap iteration 281 * order. They also specify the behavior of the {@code equals}, {@code hashCode}, and {@code 282 * toString} methods for the multimap and its returned views. However, the multimap's {@code get} 283 * method returns instances of a different class than {@code factory.get()} does. 284 * 285 * <p>The multimap is serializable if {@code map}, {@code factory}, the sets generated by {@code 286 * factory}, and the multimap contents are all serializable. 287 * 288 * <p>The multimap is not threadsafe when any concurrent operations update the multimap, even if 289 * {@code map} and the instances generated by {@code factory} are. Concurrent read operations will 290 * work correctly. To allow concurrent update operations, wrap the multimap with a call to {@link 291 * #synchronizedSetMultimap}. 292 * 293 * <p>Call this method only when the simpler methods {@link HashMultimap#create()}, {@link 294 * LinkedHashMultimap#create()}, {@link TreeMultimap#create()}, and {@link 295 * TreeMultimap#create(Comparator, Comparator)} won't suffice. 296 * 297 * <p>Note: the multimap assumes complete ownership over of {@code map} and the sets returned by 298 * {@code factory}. Those objects should not be manually updated and they should not use soft, 299 * weak, or phantom references. 300 * 301 * @param map place to store the mapping from each key to its corresponding values 302 * @param factory supplier of new, empty sets that will each hold all values for a given key 303 * @throws IllegalArgumentException if {@code map} is not empty 304 */ 305 public static <K extends @Nullable Object, V extends @Nullable Object> 306 SetMultimap<K, V> newSetMultimap( 307 Map<K, Collection<V>> map, final Supplier<? extends Set<V>> factory) { 308 return new CustomSetMultimap<>(map, factory); 309 } 310 311 private static class CustomSetMultimap<K extends @Nullable Object, V extends @Nullable Object> 312 extends AbstractSetMultimap<K, V> { 313 transient Supplier<? extends Set<V>> factory; 314 315 CustomSetMultimap(Map<K, Collection<V>> map, Supplier<? extends Set<V>> factory) { 316 super(map); 317 this.factory = checkNotNull(factory); 318 } 319 320 @Override 321 Set<K> createKeySet() { 322 return createMaybeNavigableKeySet(); 323 } 324 325 @Override 326 Map<K, Collection<V>> createAsMap() { 327 return createMaybeNavigableAsMap(); 328 } 329 330 @Override 331 protected Set<V> createCollection() { 332 return factory.get(); 333 } 334 335 @Override 336 <E extends @Nullable Object> Collection<E> unmodifiableCollectionSubclass( 337 Collection<E> collection) { 338 if (collection instanceof NavigableSet) { 339 return Sets.unmodifiableNavigableSet((NavigableSet<E>) collection); 340 } else if (collection instanceof SortedSet) { 341 return Collections.unmodifiableSortedSet((SortedSet<E>) collection); 342 } else { 343 return Collections.unmodifiableSet((Set<E>) collection); 344 } 345 } 346 347 @Override 348 Collection<V> wrapCollection(@ParametricNullness K key, Collection<V> collection) { 349 if (collection instanceof NavigableSet) { 350 return new WrappedNavigableSet(key, (NavigableSet<V>) collection, null); 351 } else if (collection instanceof SortedSet) { 352 return new WrappedSortedSet(key, (SortedSet<V>) collection, null); 353 } else { 354 return new WrappedSet(key, (Set<V>) collection); 355 } 356 } 357 358 /** @serialData the factory and the backing map */ 359 @GwtIncompatible // java.io.ObjectOutputStream 360 private void writeObject(ObjectOutputStream stream) throws IOException { 361 stream.defaultWriteObject(); 362 stream.writeObject(factory); 363 stream.writeObject(backingMap()); 364 } 365 366 @GwtIncompatible // java.io.ObjectInputStream 367 @SuppressWarnings("unchecked") // reading data stored by writeObject 368 private void readObject(ObjectInputStream stream) throws IOException, ClassNotFoundException { 369 stream.defaultReadObject(); 370 factory = (Supplier<? extends Set<V>>) stream.readObject(); 371 Map<K, Collection<V>> map = (Map<K, Collection<V>>) stream.readObject(); 372 setMap(map); 373 } 374 375 @GwtIncompatible // not needed in emulated source 376 private static final long serialVersionUID = 0; 377 } 378 379 /** 380 * Creates a new {@code SortedSetMultimap} that uses the provided map and factory. It can generate 381 * a multimap based on arbitrary {@link Map} and {@link SortedSet} classes. 382 * 383 * <p>The {@code factory}-generated and {@code map} classes determine the multimap iteration 384 * order. They also specify the behavior of the {@code equals}, {@code hashCode}, and {@code 385 * toString} methods for the multimap and its returned views. However, the multimap's {@code get} 386 * method returns instances of a different class than {@code factory.get()} does. 387 * 388 * <p>The multimap is serializable if {@code map}, {@code factory}, the sets generated by {@code 389 * factory}, and the multimap contents are all serializable. 390 * 391 * <p>The multimap is not threadsafe when any concurrent operations update the multimap, even if 392 * {@code map} and the instances generated by {@code factory} are. Concurrent read operations will 393 * work correctly. To allow concurrent update operations, wrap the multimap with a call to {@link 394 * #synchronizedSortedSetMultimap}. 395 * 396 * <p>Call this method only when the simpler methods {@link TreeMultimap#create()} and {@link 397 * TreeMultimap#create(Comparator, Comparator)} won't suffice. 398 * 399 * <p>Note: the multimap assumes complete ownership over of {@code map} and the sets returned by 400 * {@code factory}. Those objects should not be manually updated and they should not use soft, 401 * weak, or phantom references. 402 * 403 * @param map place to store the mapping from each key to its corresponding values 404 * @param factory supplier of new, empty sorted sets that will each hold all values for a given 405 * key 406 * @throws IllegalArgumentException if {@code map} is not empty 407 */ 408 public static <K extends @Nullable Object, V extends @Nullable Object> 409 SortedSetMultimap<K, V> newSortedSetMultimap( 410 Map<K, Collection<V>> map, final Supplier<? extends SortedSet<V>> factory) { 411 return new CustomSortedSetMultimap<>(map, factory); 412 } 413 414 private static class CustomSortedSetMultimap< 415 K extends @Nullable Object, V extends @Nullable Object> 416 extends AbstractSortedSetMultimap<K, V> { 417 transient Supplier<? extends SortedSet<V>> factory; 418 @CheckForNull transient Comparator<? super V> valueComparator; 419 420 CustomSortedSetMultimap(Map<K, Collection<V>> map, Supplier<? extends SortedSet<V>> factory) { 421 super(map); 422 this.factory = checkNotNull(factory); 423 valueComparator = factory.get().comparator(); 424 } 425 426 @Override 427 Set<K> createKeySet() { 428 return createMaybeNavigableKeySet(); 429 } 430 431 @Override 432 Map<K, Collection<V>> createAsMap() { 433 return createMaybeNavigableAsMap(); 434 } 435 436 @Override 437 protected SortedSet<V> createCollection() { 438 return factory.get(); 439 } 440 441 @Override 442 @CheckForNull 443 public Comparator<? super V> valueComparator() { 444 return valueComparator; 445 } 446 447 /** @serialData the factory and the backing map */ 448 @GwtIncompatible // java.io.ObjectOutputStream 449 private void writeObject(ObjectOutputStream stream) throws IOException { 450 stream.defaultWriteObject(); 451 stream.writeObject(factory); 452 stream.writeObject(backingMap()); 453 } 454 455 @GwtIncompatible // java.io.ObjectInputStream 456 @SuppressWarnings("unchecked") // reading data stored by writeObject 457 private void readObject(ObjectInputStream stream) throws IOException, ClassNotFoundException { 458 stream.defaultReadObject(); 459 factory = (Supplier<? extends SortedSet<V>>) stream.readObject(); 460 valueComparator = factory.get().comparator(); 461 Map<K, Collection<V>> map = (Map<K, Collection<V>>) stream.readObject(); 462 setMap(map); 463 } 464 465 @GwtIncompatible // not needed in emulated source 466 private static final long serialVersionUID = 0; 467 } 468 469 /** 470 * Copies each key-value mapping in {@code source} into {@code dest}, with its key and value 471 * reversed. 472 * 473 * <p>If {@code source} is an {@link ImmutableMultimap}, consider using {@link 474 * ImmutableMultimap#inverse} instead. 475 * 476 * @param source any multimap 477 * @param dest the multimap to copy into; usually empty 478 * @return {@code dest} 479 */ 480 @CanIgnoreReturnValue 481 public static <K extends @Nullable Object, V extends @Nullable Object, M extends Multimap<K, V>> 482 M invertFrom(Multimap<? extends V, ? extends K> source, M dest) { 483 checkNotNull(dest); 484 for (Map.Entry<? extends V, ? extends K> entry : source.entries()) { 485 dest.put(entry.getValue(), entry.getKey()); 486 } 487 return dest; 488 } 489 490 /** 491 * Returns a synchronized (thread-safe) multimap backed by the specified multimap. In order to 492 * guarantee serial access, it is critical that <b>all</b> access to the backing multimap is 493 * accomplished through the returned multimap. 494 * 495 * <p>It is imperative that the user manually synchronize on the returned multimap when accessing 496 * any of its collection views: 497 * 498 * <pre>{@code 499 * Multimap<K, V> multimap = Multimaps.synchronizedMultimap( 500 * HashMultimap.<K, V>create()); 501 * ... 502 * Collection<V> values = multimap.get(key); // Needn't be in synchronized block 503 * ... 504 * synchronized (multimap) { // Synchronizing on multimap, not values! 505 * Iterator<V> i = values.iterator(); // Must be in synchronized block 506 * while (i.hasNext()) { 507 * foo(i.next()); 508 * } 509 * } 510 * }</pre> 511 * 512 * <p>Failure to follow this advice may result in non-deterministic behavior. 513 * 514 * <p>Note that the generated multimap's {@link Multimap#removeAll} and {@link 515 * Multimap#replaceValues} methods return collections that aren't synchronized. 516 * 517 * <p>The returned multimap will be serializable if the specified multimap is serializable. 518 * 519 * @param multimap the multimap to be wrapped in a synchronized view 520 * @return a synchronized view of the specified multimap 521 */ 522 public static <K extends @Nullable Object, V extends @Nullable Object> 523 Multimap<K, V> synchronizedMultimap(Multimap<K, V> multimap) { 524 return Synchronized.multimap(multimap, null); 525 } 526 527 /** 528 * Returns an unmodifiable view of the specified multimap. Query operations on the returned 529 * multimap "read through" to the specified multimap, and attempts to modify the returned 530 * multimap, either directly or through the multimap's views, result in an {@code 531 * UnsupportedOperationException}. 532 * 533 * <p>The returned multimap will be serializable if the specified multimap is serializable. 534 * 535 * @param delegate the multimap for which an unmodifiable view is to be returned 536 * @return an unmodifiable view of the specified multimap 537 */ 538 public static <K extends @Nullable Object, V extends @Nullable Object> 539 Multimap<K, V> unmodifiableMultimap(Multimap<K, V> delegate) { 540 if (delegate instanceof UnmodifiableMultimap || delegate instanceof ImmutableMultimap) { 541 return delegate; 542 } 543 return new UnmodifiableMultimap<>(delegate); 544 } 545 546 /** 547 * Simply returns its argument. 548 * 549 * @deprecated no need to use this 550 * @since 10.0 551 */ 552 @Deprecated 553 public static <K, V> Multimap<K, V> unmodifiableMultimap(ImmutableMultimap<K, V> delegate) { 554 return checkNotNull(delegate); 555 } 556 557 private static class UnmodifiableMultimap<K extends @Nullable Object, V extends @Nullable Object> 558 extends ForwardingMultimap<K, V> implements Serializable { 559 final Multimap<K, V> delegate; 560 @LazyInit @CheckForNull transient Collection<Entry<K, V>> entries; 561 @LazyInit @CheckForNull transient Multiset<K> keys; 562 @LazyInit @CheckForNull transient Set<K> keySet; 563 @LazyInit @CheckForNull transient Collection<V> values; 564 @LazyInit @CheckForNull transient Map<K, Collection<V>> map; 565 566 UnmodifiableMultimap(final Multimap<K, V> delegate) { 567 this.delegate = checkNotNull(delegate); 568 } 569 570 @Override 571 protected Multimap<K, V> delegate() { 572 return delegate; 573 } 574 575 @Override 576 public void clear() { 577 throw new UnsupportedOperationException(); 578 } 579 580 @Override 581 public Map<K, Collection<V>> asMap() { 582 Map<K, Collection<V>> result = map; 583 if (result == null) { 584 result = 585 map = 586 Collections.unmodifiableMap( 587 Maps.transformValues( 588 delegate.asMap(), 589 new Function<Collection<V>, Collection<V>>() { 590 @Override 591 public Collection<V> apply(Collection<V> collection) { 592 return unmodifiableValueCollection(collection); 593 } 594 })); 595 } 596 return result; 597 } 598 599 @Override 600 public Collection<Entry<K, V>> entries() { 601 Collection<Entry<K, V>> result = entries; 602 if (result == null) { 603 entries = result = unmodifiableEntries(delegate.entries()); 604 } 605 return result; 606 } 607 608 @Override 609 public Collection<V> get(@ParametricNullness K key) { 610 return unmodifiableValueCollection(delegate.get(key)); 611 } 612 613 @Override 614 public Multiset<K> keys() { 615 Multiset<K> result = keys; 616 if (result == null) { 617 keys = result = Multisets.unmodifiableMultiset(delegate.keys()); 618 } 619 return result; 620 } 621 622 @Override 623 public Set<K> keySet() { 624 Set<K> result = keySet; 625 if (result == null) { 626 keySet = result = Collections.unmodifiableSet(delegate.keySet()); 627 } 628 return result; 629 } 630 631 @Override 632 public boolean put(@ParametricNullness K key, @ParametricNullness V value) { 633 throw new UnsupportedOperationException(); 634 } 635 636 @Override 637 public boolean putAll(@ParametricNullness K key, Iterable<? extends V> values) { 638 throw new UnsupportedOperationException(); 639 } 640 641 @Override 642 public boolean putAll(Multimap<? extends K, ? extends V> multimap) { 643 throw new UnsupportedOperationException(); 644 } 645 646 @Override 647 public boolean remove(@CheckForNull Object key, @CheckForNull Object value) { 648 throw new UnsupportedOperationException(); 649 } 650 651 @Override 652 public Collection<V> removeAll(@CheckForNull Object key) { 653 throw new UnsupportedOperationException(); 654 } 655 656 @Override 657 public Collection<V> replaceValues(@ParametricNullness K key, Iterable<? extends V> values) { 658 throw new UnsupportedOperationException(); 659 } 660 661 @Override 662 public Collection<V> values() { 663 Collection<V> result = values; 664 if (result == null) { 665 values = result = Collections.unmodifiableCollection(delegate.values()); 666 } 667 return result; 668 } 669 670 private static final long serialVersionUID = 0; 671 } 672 673 private static class UnmodifiableListMultimap< 674 K extends @Nullable Object, V extends @Nullable Object> 675 extends UnmodifiableMultimap<K, V> implements ListMultimap<K, V> { 676 UnmodifiableListMultimap(ListMultimap<K, V> delegate) { 677 super(delegate); 678 } 679 680 @Override 681 public ListMultimap<K, V> delegate() { 682 return (ListMultimap<K, V>) super.delegate(); 683 } 684 685 @Override 686 public List<V> get(@ParametricNullness K key) { 687 return Collections.unmodifiableList(delegate().get(key)); 688 } 689 690 @Override 691 public List<V> removeAll(@CheckForNull Object key) { 692 throw new UnsupportedOperationException(); 693 } 694 695 @Override 696 public List<V> replaceValues(@ParametricNullness K key, Iterable<? extends V> values) { 697 throw new UnsupportedOperationException(); 698 } 699 700 private static final long serialVersionUID = 0; 701 } 702 703 private static class UnmodifiableSetMultimap< 704 K extends @Nullable Object, V extends @Nullable Object> 705 extends UnmodifiableMultimap<K, V> implements SetMultimap<K, V> { 706 UnmodifiableSetMultimap(SetMultimap<K, V> delegate) { 707 super(delegate); 708 } 709 710 @Override 711 public SetMultimap<K, V> delegate() { 712 return (SetMultimap<K, V>) super.delegate(); 713 } 714 715 @Override 716 public Set<V> get(@ParametricNullness K key) { 717 /* 718 * Note that this doesn't return a SortedSet when delegate is a 719 * SortedSetMultiset, unlike (SortedSet<V>) super.get(). 720 */ 721 return Collections.unmodifiableSet(delegate().get(key)); 722 } 723 724 @Override 725 public Set<Map.Entry<K, V>> entries() { 726 return Maps.unmodifiableEntrySet(delegate().entries()); 727 } 728 729 @Override 730 public Set<V> removeAll(@CheckForNull Object key) { 731 throw new UnsupportedOperationException(); 732 } 733 734 @Override 735 public Set<V> replaceValues(@ParametricNullness K key, Iterable<? extends V> values) { 736 throw new UnsupportedOperationException(); 737 } 738 739 private static final long serialVersionUID = 0; 740 } 741 742 private static class UnmodifiableSortedSetMultimap< 743 K extends @Nullable Object, V extends @Nullable Object> 744 extends UnmodifiableSetMultimap<K, V> implements SortedSetMultimap<K, V> { 745 UnmodifiableSortedSetMultimap(SortedSetMultimap<K, V> delegate) { 746 super(delegate); 747 } 748 749 @Override 750 public SortedSetMultimap<K, V> delegate() { 751 return (SortedSetMultimap<K, V>) super.delegate(); 752 } 753 754 @Override 755 public SortedSet<V> get(@ParametricNullness K key) { 756 return Collections.unmodifiableSortedSet(delegate().get(key)); 757 } 758 759 @Override 760 public SortedSet<V> removeAll(@CheckForNull Object key) { 761 throw new UnsupportedOperationException(); 762 } 763 764 @Override 765 public SortedSet<V> replaceValues(@ParametricNullness K key, Iterable<? extends V> values) { 766 throw new UnsupportedOperationException(); 767 } 768 769 @Override 770 @CheckForNull 771 public Comparator<? super V> valueComparator() { 772 return delegate().valueComparator(); 773 } 774 775 private static final long serialVersionUID = 0; 776 } 777 778 /** 779 * Returns a synchronized (thread-safe) {@code SetMultimap} backed by the specified multimap. 780 * 781 * <p>You must follow the warnings described in {@link #synchronizedMultimap}. 782 * 783 * <p>The returned multimap will be serializable if the specified multimap is serializable. 784 * 785 * @param multimap the multimap to be wrapped 786 * @return a synchronized view of the specified multimap 787 */ 788 public static <K extends @Nullable Object, V extends @Nullable Object> 789 SetMultimap<K, V> synchronizedSetMultimap(SetMultimap<K, V> multimap) { 790 return Synchronized.setMultimap(multimap, null); 791 } 792 793 /** 794 * Returns an unmodifiable view of the specified {@code SetMultimap}. Query operations on the 795 * returned multimap "read through" to the specified multimap, and attempts to modify the returned 796 * multimap, either directly or through the multimap's views, result in an {@code 797 * UnsupportedOperationException}. 798 * 799 * <p>The returned multimap will be serializable if the specified multimap is serializable. 800 * 801 * @param delegate the multimap for which an unmodifiable view is to be returned 802 * @return an unmodifiable view of the specified multimap 803 */ 804 public static <K extends @Nullable Object, V extends @Nullable Object> 805 SetMultimap<K, V> unmodifiableSetMultimap(SetMultimap<K, V> delegate) { 806 if (delegate instanceof UnmodifiableSetMultimap || delegate instanceof ImmutableSetMultimap) { 807 return delegate; 808 } 809 return new UnmodifiableSetMultimap<>(delegate); 810 } 811 812 /** 813 * Simply returns its argument. 814 * 815 * @deprecated no need to use this 816 * @since 10.0 817 */ 818 @Deprecated 819 public static <K, V> SetMultimap<K, V> unmodifiableSetMultimap( 820 ImmutableSetMultimap<K, V> delegate) { 821 return checkNotNull(delegate); 822 } 823 824 /** 825 * Returns a synchronized (thread-safe) {@code SortedSetMultimap} backed by the specified 826 * multimap. 827 * 828 * <p>You must follow the warnings described in {@link #synchronizedMultimap}. 829 * 830 * <p>The returned multimap will be serializable if the specified multimap is serializable. 831 * 832 * @param multimap the multimap to be wrapped 833 * @return a synchronized view of the specified multimap 834 */ 835 public static <K extends @Nullable Object, V extends @Nullable Object> 836 SortedSetMultimap<K, V> synchronizedSortedSetMultimap(SortedSetMultimap<K, V> multimap) { 837 return Synchronized.sortedSetMultimap(multimap, null); 838 } 839 840 /** 841 * Returns an unmodifiable view of the specified {@code SortedSetMultimap}. Query operations on 842 * the returned multimap "read through" to the specified multimap, and attempts to modify the 843 * returned multimap, either directly or through the multimap's views, result in an {@code 844 * UnsupportedOperationException}. 845 * 846 * <p>The returned multimap will be serializable if the specified multimap is serializable. 847 * 848 * @param delegate the multimap for which an unmodifiable view is to be returned 849 * @return an unmodifiable view of the specified multimap 850 */ 851 public static <K extends @Nullable Object, V extends @Nullable Object> 852 SortedSetMultimap<K, V> unmodifiableSortedSetMultimap(SortedSetMultimap<K, V> delegate) { 853 if (delegate instanceof UnmodifiableSortedSetMultimap) { 854 return delegate; 855 } 856 return new UnmodifiableSortedSetMultimap<>(delegate); 857 } 858 859 /** 860 * Returns a synchronized (thread-safe) {@code ListMultimap} backed by the specified multimap. 861 * 862 * <p>You must follow the warnings described in {@link #synchronizedMultimap}. 863 * 864 * @param multimap the multimap to be wrapped 865 * @return a synchronized view of the specified multimap 866 */ 867 public static <K extends @Nullable Object, V extends @Nullable Object> 868 ListMultimap<K, V> synchronizedListMultimap(ListMultimap<K, V> multimap) { 869 return Synchronized.listMultimap(multimap, null); 870 } 871 872 /** 873 * Returns an unmodifiable view of the specified {@code ListMultimap}. Query operations on the 874 * returned multimap "read through" to the specified multimap, and attempts to modify the returned 875 * multimap, either directly or through the multimap's views, result in an {@code 876 * UnsupportedOperationException}. 877 * 878 * <p>The returned multimap will be serializable if the specified multimap is serializable. 879 * 880 * @param delegate the multimap for which an unmodifiable view is to be returned 881 * @return an unmodifiable view of the specified multimap 882 */ 883 public static <K extends @Nullable Object, V extends @Nullable Object> 884 ListMultimap<K, V> unmodifiableListMultimap(ListMultimap<K, V> delegate) { 885 if (delegate instanceof UnmodifiableListMultimap || delegate instanceof ImmutableListMultimap) { 886 return delegate; 887 } 888 return new UnmodifiableListMultimap<>(delegate); 889 } 890 891 /** 892 * Simply returns its argument. 893 * 894 * @deprecated no need to use this 895 * @since 10.0 896 */ 897 @Deprecated 898 public static <K, V> ListMultimap<K, V> unmodifiableListMultimap( 899 ImmutableListMultimap<K, V> delegate) { 900 return checkNotNull(delegate); 901 } 902 903 /** 904 * Returns an unmodifiable view of the specified collection, preserving the interface for 905 * instances of {@code SortedSet}, {@code Set}, {@code List} and {@code Collection}, in that order 906 * of preference. 907 * 908 * @param collection the collection for which to return an unmodifiable view 909 * @return an unmodifiable view of the collection 910 */ 911 private static <V extends @Nullable Object> Collection<V> unmodifiableValueCollection( 912 Collection<V> collection) { 913 if (collection instanceof SortedSet) { 914 return Collections.unmodifiableSortedSet((SortedSet<V>) collection); 915 } else if (collection instanceof Set) { 916 return Collections.unmodifiableSet((Set<V>) collection); 917 } else if (collection instanceof List) { 918 return Collections.unmodifiableList((List<V>) collection); 919 } 920 return Collections.unmodifiableCollection(collection); 921 } 922 923 /** 924 * Returns an unmodifiable view of the specified collection of entries. The {@link Entry#setValue} 925 * operation throws an {@link UnsupportedOperationException}. If the specified collection is a 926 * {@code Set}, the returned collection is also a {@code Set}. 927 * 928 * @param entries the entries for which to return an unmodifiable view 929 * @return an unmodifiable view of the entries 930 */ 931 private static <K extends @Nullable Object, V extends @Nullable Object> 932 Collection<Entry<K, V>> unmodifiableEntries(Collection<Entry<K, V>> entries) { 933 if (entries instanceof Set) { 934 return Maps.unmodifiableEntrySet((Set<Entry<K, V>>) entries); 935 } 936 return new Maps.UnmodifiableEntries<>(Collections.unmodifiableCollection(entries)); 937 } 938 939 /** 940 * Returns {@link ListMultimap#asMap multimap.asMap()}, with its type corrected from {@code Map<K, 941 * Collection<V>>} to {@code Map<K, List<V>>}. 942 * 943 * @since 15.0 944 */ 945 @Beta 946 @SuppressWarnings("unchecked") 947 // safe by specification of ListMultimap.asMap() 948 public static <K extends @Nullable Object, V extends @Nullable Object> Map<K, List<V>> asMap( 949 ListMultimap<K, V> multimap) { 950 return (Map<K, List<V>>) (Map<K, ?>) multimap.asMap(); 951 } 952 953 /** 954 * Returns {@link SetMultimap#asMap multimap.asMap()}, with its type corrected from {@code Map<K, 955 * Collection<V>>} to {@code Map<K, Set<V>>}. 956 * 957 * @since 15.0 958 */ 959 @Beta 960 @SuppressWarnings("unchecked") 961 // safe by specification of SetMultimap.asMap() 962 public static <K extends @Nullable Object, V extends @Nullable Object> Map<K, Set<V>> asMap( 963 SetMultimap<K, V> multimap) { 964 return (Map<K, Set<V>>) (Map<K, ?>) multimap.asMap(); 965 } 966 967 /** 968 * Returns {@link SortedSetMultimap#asMap multimap.asMap()}, with its type corrected from {@code 969 * Map<K, Collection<V>>} to {@code Map<K, SortedSet<V>>}. 970 * 971 * @since 15.0 972 */ 973 @Beta 974 @SuppressWarnings("unchecked") 975 // safe by specification of SortedSetMultimap.asMap() 976 public static <K extends @Nullable Object, V extends @Nullable Object> Map<K, SortedSet<V>> asMap( 977 SortedSetMultimap<K, V> multimap) { 978 return (Map<K, SortedSet<V>>) (Map<K, ?>) multimap.asMap(); 979 } 980 981 /** 982 * Returns {@link Multimap#asMap multimap.asMap()}. This is provided for parity with the other 983 * more strongly-typed {@code asMap()} implementations. 984 * 985 * @since 15.0 986 */ 987 @Beta 988 public static <K extends @Nullable Object, V extends @Nullable Object> 989 Map<K, Collection<V>> asMap(Multimap<K, V> multimap) { 990 return multimap.asMap(); 991 } 992 993 /** 994 * Returns a multimap view of the specified map. The multimap is backed by the map, so changes to 995 * the map are reflected in the multimap, and vice versa. If the map is modified while an 996 * iteration over one of the multimap's collection views is in progress (except through the 997 * iterator's own {@code remove} operation, or through the {@code setValue} operation on a map 998 * entry returned by the iterator), the results of the iteration are undefined. 999 * 1000 * <p>The multimap supports mapping removal, which removes the corresponding mapping from the map. 1001 * It does not support any operations which might add mappings, such as {@code put}, {@code 1002 * putAll} or {@code replaceValues}. 1003 * 1004 * <p>The returned multimap will be serializable if the specified map is serializable. 1005 * 1006 * @param map the backing map for the returned multimap view 1007 */ 1008 public static <K extends @Nullable Object, V extends @Nullable Object> SetMultimap<K, V> forMap( 1009 Map<K, V> map) { 1010 return new MapMultimap<>(map); 1011 } 1012 1013 /** @see Multimaps#forMap */ 1014 private static class MapMultimap<K extends @Nullable Object, V extends @Nullable Object> 1015 extends AbstractMultimap<K, V> implements SetMultimap<K, V>, Serializable { 1016 final Map<K, V> map; 1017 1018 MapMultimap(Map<K, V> map) { 1019 this.map = checkNotNull(map); 1020 } 1021 1022 @Override 1023 public int size() { 1024 return map.size(); 1025 } 1026 1027 @Override 1028 public boolean containsKey(@CheckForNull Object key) { 1029 return map.containsKey(key); 1030 } 1031 1032 @Override 1033 public boolean containsValue(@CheckForNull Object value) { 1034 return map.containsValue(value); 1035 } 1036 1037 @Override 1038 public boolean containsEntry(@CheckForNull Object key, @CheckForNull Object value) { 1039 return map.entrySet().contains(Maps.immutableEntry(key, value)); 1040 } 1041 1042 @Override 1043 public Set<V> get(@ParametricNullness final K key) { 1044 return new Sets.ImprovedAbstractSet<V>() { 1045 @Override 1046 public Iterator<V> iterator() { 1047 return new Iterator<V>() { 1048 int i; 1049 1050 @Override 1051 public boolean hasNext() { 1052 return (i == 0) && map.containsKey(key); 1053 } 1054 1055 @Override 1056 @ParametricNullness 1057 public V next() { 1058 if (!hasNext()) { 1059 throw new NoSuchElementException(); 1060 } 1061 i++; 1062 /* 1063 * The cast is safe because of the containsKey check in hasNext(). (That means it's 1064 * unsafe under concurrent modification, but all bets are off then, anyway.) 1065 */ 1066 return uncheckedCastNullableTToT(map.get(key)); 1067 } 1068 1069 @Override 1070 public void remove() { 1071 checkRemove(i == 1); 1072 i = -1; 1073 map.remove(key); 1074 } 1075 }; 1076 } 1077 1078 @Override 1079 public int size() { 1080 return map.containsKey(key) ? 1 : 0; 1081 } 1082 }; 1083 } 1084 1085 @Override 1086 public boolean put(@ParametricNullness K key, @ParametricNullness V value) { 1087 throw new UnsupportedOperationException(); 1088 } 1089 1090 @Override 1091 public boolean putAll(@ParametricNullness K key, Iterable<? extends V> values) { 1092 throw new UnsupportedOperationException(); 1093 } 1094 1095 @Override 1096 public boolean putAll(Multimap<? extends K, ? extends V> multimap) { 1097 throw new UnsupportedOperationException(); 1098 } 1099 1100 @Override 1101 public Set<V> replaceValues(@ParametricNullness K key, Iterable<? extends V> values) { 1102 throw new UnsupportedOperationException(); 1103 } 1104 1105 @Override 1106 public boolean remove(@CheckForNull Object key, @CheckForNull Object value) { 1107 return map.entrySet().remove(Maps.immutableEntry(key, value)); 1108 } 1109 1110 @Override 1111 public Set<V> removeAll(@CheckForNull Object key) { 1112 Set<V> values = new HashSet<V>(2); 1113 if (!map.containsKey(key)) { 1114 return values; 1115 } 1116 values.add(map.remove(key)); 1117 return values; 1118 } 1119 1120 @Override 1121 public void clear() { 1122 map.clear(); 1123 } 1124 1125 @Override 1126 Set<K> createKeySet() { 1127 return map.keySet(); 1128 } 1129 1130 @Override 1131 Collection<V> createValues() { 1132 return map.values(); 1133 } 1134 1135 @Override 1136 public Set<Entry<K, V>> entries() { 1137 return map.entrySet(); 1138 } 1139 1140 @Override 1141 Collection<Entry<K, V>> createEntries() { 1142 throw new AssertionError("unreachable"); 1143 } 1144 1145 @Override 1146 Multiset<K> createKeys() { 1147 return new Multimaps.Keys<K, V>(this); 1148 } 1149 1150 @Override 1151 Iterator<Entry<K, V>> entryIterator() { 1152 return map.entrySet().iterator(); 1153 } 1154 1155 @Override 1156 Map<K, Collection<V>> createAsMap() { 1157 return new AsMap<>(this); 1158 } 1159 1160 @Override 1161 public int hashCode() { 1162 return map.hashCode(); 1163 } 1164 1165 private static final long serialVersionUID = 7845222491160860175L; 1166 } 1167 1168 /** 1169 * Returns a view of a multimap where each value is transformed by a function. All other 1170 * properties of the multimap, such as iteration order, are left intact. For example, the code: 1171 * 1172 * <pre>{@code 1173 * Multimap<String, Integer> multimap = 1174 * ImmutableSetMultimap.of("a", 2, "b", -3, "b", -3, "a", 4, "c", 6); 1175 * Function<Integer, String> square = new Function<Integer, String>() { 1176 * public String apply(Integer in) { 1177 * return Integer.toString(in * in); 1178 * } 1179 * }; 1180 * Multimap<String, String> transformed = 1181 * Multimaps.transformValues(multimap, square); 1182 * System.out.println(transformed); 1183 * }</pre> 1184 * 1185 * ... prints {@code {a=[4, 16], b=[9, 9], c=[36]}}. 1186 * 1187 * <p>Changes in the underlying multimap are reflected in this view. Conversely, this view 1188 * supports removal operations, and these are reflected in the underlying multimap. 1189 * 1190 * <p>It's acceptable for the underlying multimap to contain null keys, and even null values 1191 * provided that the function is capable of accepting null input. The transformed multimap might 1192 * contain null values, if the function sometimes gives a null result. 1193 * 1194 * <p>The returned multimap is not thread-safe or serializable, even if the underlying multimap 1195 * is. The {@code equals} and {@code hashCode} methods of the returned multimap are meaningless, 1196 * since there is not a definition of {@code equals} or {@code hashCode} for general collections, 1197 * and {@code get()} will return a general {@code Collection} as opposed to a {@code List} or a 1198 * {@code Set}. 1199 * 1200 * <p>The function is applied lazily, invoked when needed. This is necessary for the returned 1201 * multimap to be a view, but it means that the function will be applied many times for bulk 1202 * operations like {@link Multimap#containsValue} and {@code Multimap.toString()}. For this to 1203 * perform well, {@code function} should be fast. To avoid lazy evaluation when the returned 1204 * multimap doesn't need to be a view, copy the returned multimap into a new multimap of your 1205 * choosing. 1206 * 1207 * @since 7.0 1208 */ 1209 public static < 1210 K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> 1211 Multimap<K, V2> transformValues( 1212 Multimap<K, V1> fromMultimap, final Function<? super V1, V2> function) { 1213 checkNotNull(function); 1214 EntryTransformer<K, V1, V2> transformer = Maps.asEntryTransformer(function); 1215 return transformEntries(fromMultimap, transformer); 1216 } 1217 1218 /** 1219 * Returns a view of a {@code ListMultimap} where each value is transformed by a function. All 1220 * other properties of the multimap, such as iteration order, are left intact. For example, the 1221 * code: 1222 * 1223 * <pre>{@code 1224 * ListMultimap<String, Integer> multimap 1225 * = ImmutableListMultimap.of("a", 4, "a", 16, "b", 9); 1226 * Function<Integer, Double> sqrt = 1227 * new Function<Integer, Double>() { 1228 * public Double apply(Integer in) { 1229 * return Math.sqrt((int) in); 1230 * } 1231 * }; 1232 * ListMultimap<String, Double> transformed = Multimaps.transformValues(map, 1233 * sqrt); 1234 * System.out.println(transformed); 1235 * }</pre> 1236 * 1237 * ... prints {@code {a=[2.0, 4.0], b=[3.0]}}. 1238 * 1239 * <p>Changes in the underlying multimap are reflected in this view. Conversely, this view 1240 * supports removal operations, and these are reflected in the underlying multimap. 1241 * 1242 * <p>It's acceptable for the underlying multimap to contain null keys, and even null values 1243 * provided that the function is capable of accepting null input. The transformed multimap might 1244 * contain null values, if the function sometimes gives a null result. 1245 * 1246 * <p>The returned multimap is not thread-safe or serializable, even if the underlying multimap 1247 * is. 1248 * 1249 * <p>The function is applied lazily, invoked when needed. This is necessary for the returned 1250 * multimap to be a view, but it means that the function will be applied many times for bulk 1251 * operations like {@link Multimap#containsValue} and {@code Multimap.toString()}. For this to 1252 * perform well, {@code function} should be fast. To avoid lazy evaluation when the returned 1253 * multimap doesn't need to be a view, copy the returned multimap into a new multimap of your 1254 * choosing. 1255 * 1256 * @since 7.0 1257 */ 1258 public static < 1259 K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> 1260 ListMultimap<K, V2> transformValues( 1261 ListMultimap<K, V1> fromMultimap, final Function<? super V1, V2> function) { 1262 checkNotNull(function); 1263 EntryTransformer<K, V1, V2> transformer = Maps.asEntryTransformer(function); 1264 return transformEntries(fromMultimap, transformer); 1265 } 1266 1267 /** 1268 * Returns a view of a multimap whose values are derived from the original multimap's entries. In 1269 * contrast to {@link #transformValues}, this method's entry-transformation logic may depend on 1270 * the key as well as the value. 1271 * 1272 * <p>All other properties of the transformed multimap, such as iteration order, are left intact. 1273 * For example, the code: 1274 * 1275 * <pre>{@code 1276 * SetMultimap<String, Integer> multimap = 1277 * ImmutableSetMultimap.of("a", 1, "a", 4, "b", -6); 1278 * EntryTransformer<String, Integer, String> transformer = 1279 * new EntryTransformer<String, Integer, String>() { 1280 * public String transformEntry(String key, Integer value) { 1281 * return (value >= 0) ? key : "no" + key; 1282 * } 1283 * }; 1284 * Multimap<String, String> transformed = 1285 * Multimaps.transformEntries(multimap, transformer); 1286 * System.out.println(transformed); 1287 * }</pre> 1288 * 1289 * ... prints {@code {a=[a, a], b=[nob]}}. 1290 * 1291 * <p>Changes in the underlying multimap are reflected in this view. Conversely, this view 1292 * supports removal operations, and these are reflected in the underlying multimap. 1293 * 1294 * <p>It's acceptable for the underlying multimap to contain null keys and null values provided 1295 * that the transformer is capable of accepting null inputs. The transformed multimap might 1296 * contain null values if the transformer sometimes gives a null result. 1297 * 1298 * <p>The returned multimap is not thread-safe or serializable, even if the underlying multimap 1299 * is. The {@code equals} and {@code hashCode} methods of the returned multimap are meaningless, 1300 * since there is not a definition of {@code equals} or {@code hashCode} for general collections, 1301 * and {@code get()} will return a general {@code Collection} as opposed to a {@code List} or a 1302 * {@code Set}. 1303 * 1304 * <p>The transformer is applied lazily, invoked when needed. This is necessary for the returned 1305 * multimap to be a view, but it means that the transformer will be applied many times for bulk 1306 * operations like {@link Multimap#containsValue} and {@link Object#toString}. For this to perform 1307 * well, {@code transformer} should be fast. To avoid lazy evaluation when the returned multimap 1308 * doesn't need to be a view, copy the returned multimap into a new multimap of your choosing. 1309 * 1310 * <p><b>Warning:</b> This method assumes that for any instance {@code k} of {@code 1311 * EntryTransformer} key type {@code K}, {@code k.equals(k2)} implies that {@code k2} is also of 1312 * type {@code K}. Using an {@code EntryTransformer} key type for which this may not hold, such as 1313 * {@code ArrayList}, may risk a {@code ClassCastException} when calling methods on the 1314 * transformed multimap. 1315 * 1316 * @since 7.0 1317 */ 1318 public static < 1319 K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> 1320 Multimap<K, V2> transformEntries( 1321 Multimap<K, V1> fromMap, EntryTransformer<? super K, ? super V1, V2> transformer) { 1322 return new TransformedEntriesMultimap<>(fromMap, transformer); 1323 } 1324 1325 /** 1326 * Returns a view of a {@code ListMultimap} whose values are derived from the original multimap's 1327 * entries. In contrast to {@link #transformValues(ListMultimap, Function)}, this method's 1328 * entry-transformation logic may depend on the key as well as the value. 1329 * 1330 * <p>All other properties of the transformed multimap, such as iteration order, are left intact. 1331 * For example, the code: 1332 * 1333 * <pre>{@code 1334 * Multimap<String, Integer> multimap = 1335 * ImmutableMultimap.of("a", 1, "a", 4, "b", 6); 1336 * EntryTransformer<String, Integer, String> transformer = 1337 * new EntryTransformer<String, Integer, String>() { 1338 * public String transformEntry(String key, Integer value) { 1339 * return key + value; 1340 * } 1341 * }; 1342 * Multimap<String, String> transformed = 1343 * Multimaps.transformEntries(multimap, transformer); 1344 * System.out.println(transformed); 1345 * }</pre> 1346 * 1347 * ... prints {@code {"a"=["a1", "a4"], "b"=["b6"]}}. 1348 * 1349 * <p>Changes in the underlying multimap are reflected in this view. Conversely, this view 1350 * supports removal operations, and these are reflected in the underlying multimap. 1351 * 1352 * <p>It's acceptable for the underlying multimap to contain null keys and null values provided 1353 * that the transformer is capable of accepting null inputs. The transformed multimap might 1354 * contain null values if the transformer sometimes gives a null result. 1355 * 1356 * <p>The returned multimap is not thread-safe or serializable, even if the underlying multimap 1357 * is. 1358 * 1359 * <p>The transformer is applied lazily, invoked when needed. This is necessary for the returned 1360 * multimap to be a view, but it means that the transformer will be applied many times for bulk 1361 * operations like {@link Multimap#containsValue} and {@link Object#toString}. For this to perform 1362 * well, {@code transformer} should be fast. To avoid lazy evaluation when the returned multimap 1363 * doesn't need to be a view, copy the returned multimap into a new multimap of your choosing. 1364 * 1365 * <p><b>Warning:</b> This method assumes that for any instance {@code k} of {@code 1366 * EntryTransformer} key type {@code K}, {@code k.equals(k2)} implies that {@code k2} is also of 1367 * type {@code K}. Using an {@code EntryTransformer} key type for which this may not hold, such as 1368 * {@code ArrayList}, may risk a {@code ClassCastException} when calling methods on the 1369 * transformed multimap. 1370 * 1371 * @since 7.0 1372 */ 1373 public static < 1374 K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> 1375 ListMultimap<K, V2> transformEntries( 1376 ListMultimap<K, V1> fromMap, EntryTransformer<? super K, ? super V1, V2> transformer) { 1377 return new TransformedEntriesListMultimap<>(fromMap, transformer); 1378 } 1379 1380 private static class TransformedEntriesMultimap< 1381 K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> 1382 extends AbstractMultimap<K, V2> { 1383 final Multimap<K, V1> fromMultimap; 1384 final EntryTransformer<? super K, ? super V1, V2> transformer; 1385 1386 TransformedEntriesMultimap( 1387 Multimap<K, V1> fromMultimap, 1388 final EntryTransformer<? super K, ? super V1, V2> transformer) { 1389 this.fromMultimap = checkNotNull(fromMultimap); 1390 this.transformer = checkNotNull(transformer); 1391 } 1392 1393 Collection<V2> transform(@ParametricNullness K key, Collection<V1> values) { 1394 Function<? super V1, V2> function = Maps.asValueToValueFunction(transformer, key); 1395 if (values instanceof List) { 1396 return Lists.transform((List<V1>) values, function); 1397 } else { 1398 return Collections2.transform(values, function); 1399 } 1400 } 1401 1402 @Override 1403 Map<K, Collection<V2>> createAsMap() { 1404 return Maps.transformEntries( 1405 fromMultimap.asMap(), 1406 new EntryTransformer<K, Collection<V1>, Collection<V2>>() { 1407 @Override 1408 public Collection<V2> transformEntry(@ParametricNullness K key, Collection<V1> value) { 1409 return transform(key, value); 1410 } 1411 }); 1412 } 1413 1414 @Override 1415 public void clear() { 1416 fromMultimap.clear(); 1417 } 1418 1419 @Override 1420 public boolean containsKey(@CheckForNull Object key) { 1421 return fromMultimap.containsKey(key); 1422 } 1423 1424 @Override 1425 Collection<Entry<K, V2>> createEntries() { 1426 return new Entries(); 1427 } 1428 1429 @Override 1430 Iterator<Entry<K, V2>> entryIterator() { 1431 return Iterators.transform( 1432 fromMultimap.entries().iterator(), Maps.<K, V1, V2>asEntryToEntryFunction(transformer)); 1433 } 1434 1435 @Override 1436 public Collection<V2> get(@ParametricNullness final K key) { 1437 return transform(key, fromMultimap.get(key)); 1438 } 1439 1440 @Override 1441 public boolean isEmpty() { 1442 return fromMultimap.isEmpty(); 1443 } 1444 1445 @Override 1446 Set<K> createKeySet() { 1447 return fromMultimap.keySet(); 1448 } 1449 1450 @Override 1451 Multiset<K> createKeys() { 1452 return fromMultimap.keys(); 1453 } 1454 1455 @Override 1456 public boolean put(@ParametricNullness K key, @ParametricNullness V2 value) { 1457 throw new UnsupportedOperationException(); 1458 } 1459 1460 @Override 1461 public boolean putAll(@ParametricNullness K key, Iterable<? extends V2> values) { 1462 throw new UnsupportedOperationException(); 1463 } 1464 1465 @Override 1466 public boolean putAll(Multimap<? extends K, ? extends V2> multimap) { 1467 throw new UnsupportedOperationException(); 1468 } 1469 1470 @SuppressWarnings("unchecked") 1471 @Override 1472 public boolean remove(@CheckForNull Object key, @CheckForNull Object value) { 1473 return get((K) key).remove(value); 1474 } 1475 1476 @SuppressWarnings("unchecked") 1477 @Override 1478 public Collection<V2> removeAll(@CheckForNull Object key) { 1479 return transform((K) key, fromMultimap.removeAll(key)); 1480 } 1481 1482 @Override 1483 public Collection<V2> replaceValues(@ParametricNullness K key, Iterable<? extends V2> values) { 1484 throw new UnsupportedOperationException(); 1485 } 1486 1487 @Override 1488 public int size() { 1489 return fromMultimap.size(); 1490 } 1491 1492 @Override 1493 Collection<V2> createValues() { 1494 return Collections2.transform( 1495 fromMultimap.entries(), Maps.<K, V1, V2>asEntryToValueFunction(transformer)); 1496 } 1497 } 1498 1499 private static final class TransformedEntriesListMultimap< 1500 K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> 1501 extends TransformedEntriesMultimap<K, V1, V2> implements ListMultimap<K, V2> { 1502 1503 TransformedEntriesListMultimap( 1504 ListMultimap<K, V1> fromMultimap, EntryTransformer<? super K, ? super V1, V2> transformer) { 1505 super(fromMultimap, transformer); 1506 } 1507 1508 @Override 1509 List<V2> transform(@ParametricNullness K key, Collection<V1> values) { 1510 return Lists.transform((List<V1>) values, Maps.asValueToValueFunction(transformer, key)); 1511 } 1512 1513 @Override 1514 public List<V2> get(@ParametricNullness K key) { 1515 return transform(key, fromMultimap.get(key)); 1516 } 1517 1518 @SuppressWarnings("unchecked") 1519 @Override 1520 public List<V2> removeAll(@CheckForNull Object key) { 1521 return transform((K) key, fromMultimap.removeAll(key)); 1522 } 1523 1524 @Override 1525 public List<V2> replaceValues(@ParametricNullness K key, Iterable<? extends V2> values) { 1526 throw new UnsupportedOperationException(); 1527 } 1528 } 1529 1530 /** 1531 * Creates an index {@code ImmutableListMultimap} that contains the results of applying a 1532 * specified function to each item in an {@code Iterable} of values. Each value will be stored as 1533 * a value in the resulting multimap, yielding a multimap with the same size as the input 1534 * iterable. The key used to store that value in the multimap will be the result of calling the 1535 * function on that value. The resulting multimap is created as an immutable snapshot. In the 1536 * returned multimap, keys appear in the order they are first encountered, and the values 1537 * corresponding to each key appear in the same order as they are encountered. 1538 * 1539 * <p>For example, 1540 * 1541 * <pre>{@code 1542 * List<String> badGuys = 1543 * Arrays.asList("Inky", "Blinky", "Pinky", "Pinky", "Clyde"); 1544 * Function<String, Integer> stringLengthFunction = ...; 1545 * Multimap<Integer, String> index = 1546 * Multimaps.index(badGuys, stringLengthFunction); 1547 * System.out.println(index); 1548 * }</pre> 1549 * 1550 * <p>prints 1551 * 1552 * <pre>{@code 1553 * {4=[Inky], 6=[Blinky], 5=[Pinky, Pinky, Clyde]} 1554 * }</pre> 1555 * 1556 * <p>The returned multimap is serializable if its keys and values are all serializable. 1557 * 1558 * @param values the values to use when constructing the {@code ImmutableListMultimap} 1559 * @param keyFunction the function used to produce the key for each value 1560 * @return {@code ImmutableListMultimap} mapping the result of evaluating the function {@code 1561 * keyFunction} on each value in the input collection to that value 1562 * @throws NullPointerException if any element of {@code values} is {@code null}, or if {@code 1563 * keyFunction} produces {@code null} for any key 1564 */ 1565 public static <K, V> ImmutableListMultimap<K, V> index( 1566 Iterable<V> values, Function<? super V, K> keyFunction) { 1567 return index(values.iterator(), keyFunction); 1568 } 1569 1570 /** 1571 * Creates an index {@code ImmutableListMultimap} that contains the results of applying a 1572 * specified function to each item in an {@code Iterator} of values. Each value will be stored as 1573 * a value in the resulting multimap, yielding a multimap with the same size as the input 1574 * iterator. The key used to store that value in the multimap will be the result of calling the 1575 * function on that value. The resulting multimap is created as an immutable snapshot. In the 1576 * returned multimap, keys appear in the order they are first encountered, and the values 1577 * corresponding to each key appear in the same order as they are encountered. 1578 * 1579 * <p>For example, 1580 * 1581 * <pre>{@code 1582 * List<String> badGuys = 1583 * Arrays.asList("Inky", "Blinky", "Pinky", "Pinky", "Clyde"); 1584 * Function<String, Integer> stringLengthFunction = ...; 1585 * Multimap<Integer, String> index = 1586 * Multimaps.index(badGuys.iterator(), stringLengthFunction); 1587 * System.out.println(index); 1588 * }</pre> 1589 * 1590 * <p>prints 1591 * 1592 * <pre>{@code 1593 * {4=[Inky], 6=[Blinky], 5=[Pinky, Pinky, Clyde]} 1594 * }</pre> 1595 * 1596 * <p>The returned multimap is serializable if its keys and values are all serializable. 1597 * 1598 * @param values the values to use when constructing the {@code ImmutableListMultimap} 1599 * @param keyFunction the function used to produce the key for each value 1600 * @return {@code ImmutableListMultimap} mapping the result of evaluating the function {@code 1601 * keyFunction} on each value in the input collection to that value 1602 * @throws NullPointerException if any element of {@code values} is {@code null}, or if {@code 1603 * keyFunction} produces {@code null} for any key 1604 * @since 10.0 1605 */ 1606 public static <K, V> ImmutableListMultimap<K, V> index( 1607 Iterator<V> values, Function<? super V, K> keyFunction) { 1608 checkNotNull(keyFunction); 1609 ImmutableListMultimap.Builder<K, V> builder = ImmutableListMultimap.builder(); 1610 while (values.hasNext()) { 1611 V value = values.next(); 1612 checkNotNull(value, values); 1613 builder.put(keyFunction.apply(value), value); 1614 } 1615 return builder.build(); 1616 } 1617 1618 static class Keys<K extends @Nullable Object, V extends @Nullable Object> 1619 extends AbstractMultiset<K> { 1620 @Weak final Multimap<K, V> multimap; 1621 1622 Keys(Multimap<K, V> multimap) { 1623 this.multimap = multimap; 1624 } 1625 1626 @Override 1627 Iterator<Multiset.Entry<K>> entryIterator() { 1628 return new TransformedIterator<Map.Entry<K, Collection<V>>, Multiset.Entry<K>>( 1629 multimap.asMap().entrySet().iterator()) { 1630 @Override 1631 Multiset.Entry<K> transform(final Map.Entry<K, Collection<V>> backingEntry) { 1632 return new Multisets.AbstractEntry<K>() { 1633 @Override 1634 @ParametricNullness 1635 public K getElement() { 1636 return backingEntry.getKey(); 1637 } 1638 1639 @Override 1640 public int getCount() { 1641 return backingEntry.getValue().size(); 1642 } 1643 }; 1644 } 1645 }; 1646 } 1647 1648 @Override 1649 int distinctElements() { 1650 return multimap.asMap().size(); 1651 } 1652 1653 @Override 1654 public int size() { 1655 return multimap.size(); 1656 } 1657 1658 @Override 1659 public boolean contains(@CheckForNull Object element) { 1660 return multimap.containsKey(element); 1661 } 1662 1663 @Override 1664 public Iterator<K> iterator() { 1665 return Maps.keyIterator(multimap.entries().iterator()); 1666 } 1667 1668 @Override 1669 public int count(@CheckForNull Object element) { 1670 Collection<V> values = Maps.safeGet(multimap.asMap(), element); 1671 return (values == null) ? 0 : values.size(); 1672 } 1673 1674 @Override 1675 public int remove(@CheckForNull Object element, int occurrences) { 1676 checkNonnegative(occurrences, "occurrences"); 1677 if (occurrences == 0) { 1678 return count(element); 1679 } 1680 1681 Collection<V> values = Maps.safeGet(multimap.asMap(), element); 1682 1683 if (values == null) { 1684 return 0; 1685 } 1686 1687 int oldCount = values.size(); 1688 if (occurrences >= oldCount) { 1689 values.clear(); 1690 } else { 1691 Iterator<V> iterator = values.iterator(); 1692 for (int i = 0; i < occurrences; i++) { 1693 iterator.next(); 1694 iterator.remove(); 1695 } 1696 } 1697 return oldCount; 1698 } 1699 1700 @Override 1701 public void clear() { 1702 multimap.clear(); 1703 } 1704 1705 @Override 1706 public Set<K> elementSet() { 1707 return multimap.keySet(); 1708 } 1709 1710 @Override 1711 Iterator<K> elementIterator() { 1712 throw new AssertionError("should never be called"); 1713 } 1714 } 1715 1716 /** A skeleton implementation of {@link Multimap#entries()}. */ 1717 abstract static class Entries<K extends @Nullable Object, V extends @Nullable Object> 1718 extends AbstractCollection<Map.Entry<K, V>> { 1719 abstract Multimap<K, V> multimap(); 1720 1721 @Override 1722 public int size() { 1723 return multimap().size(); 1724 } 1725 1726 @Override 1727 public boolean contains(@CheckForNull Object o) { 1728 if (o instanceof Map.Entry) { 1729 Map.Entry<?, ?> entry = (Map.Entry<?, ?>) o; 1730 return multimap().containsEntry(entry.getKey(), entry.getValue()); 1731 } 1732 return false; 1733 } 1734 1735 @Override 1736 public boolean remove(@CheckForNull Object o) { 1737 if (o instanceof Map.Entry) { 1738 Map.Entry<?, ?> entry = (Map.Entry<?, ?>) o; 1739 return multimap().remove(entry.getKey(), entry.getValue()); 1740 } 1741 return false; 1742 } 1743 1744 @Override 1745 public void clear() { 1746 multimap().clear(); 1747 } 1748 } 1749 1750 /** A skeleton implementation of {@link Multimap#asMap()}. */ 1751 static final class AsMap<K extends @Nullable Object, V extends @Nullable Object> 1752 extends Maps.ViewCachingAbstractMap<K, Collection<V>> { 1753 @Weak private final Multimap<K, V> multimap; 1754 1755 AsMap(Multimap<K, V> multimap) { 1756 this.multimap = checkNotNull(multimap); 1757 } 1758 1759 @Override 1760 public int size() { 1761 return multimap.keySet().size(); 1762 } 1763 1764 @Override 1765 protected Set<Entry<K, Collection<V>>> createEntrySet() { 1766 return new EntrySet(); 1767 } 1768 1769 void removeValuesForKey(@CheckForNull Object key) { 1770 multimap.keySet().remove(key); 1771 } 1772 1773 @WeakOuter 1774 class EntrySet extends Maps.EntrySet<K, Collection<V>> { 1775 @Override 1776 Map<K, Collection<V>> map() { 1777 return AsMap.this; 1778 } 1779 1780 @Override 1781 public Iterator<Entry<K, Collection<V>>> iterator() { 1782 return Maps.asMapEntryIterator( 1783 multimap.keySet(), 1784 new Function<K, Collection<V>>() { 1785 @Override 1786 public Collection<V> apply(@ParametricNullness K key) { 1787 return multimap.get(key); 1788 } 1789 }); 1790 } 1791 1792 @Override 1793 public boolean remove(@CheckForNull Object o) { 1794 if (!contains(o)) { 1795 return false; 1796 } 1797 // requireNonNull is safe because of the contains check. 1798 Map.Entry<?, ?> entry = requireNonNull((Map.Entry<?, ?>) o); 1799 removeValuesForKey(entry.getKey()); 1800 return true; 1801 } 1802 } 1803 1804 @SuppressWarnings("unchecked") 1805 @Override 1806 @CheckForNull 1807 public Collection<V> get(@CheckForNull Object key) { 1808 return containsKey(key) ? multimap.get((K) key) : null; 1809 } 1810 1811 @Override 1812 @CheckForNull 1813 public Collection<V> remove(@CheckForNull Object key) { 1814 return containsKey(key) ? multimap.removeAll(key) : null; 1815 } 1816 1817 @Override 1818 public Set<K> keySet() { 1819 return multimap.keySet(); 1820 } 1821 1822 @Override 1823 public boolean isEmpty() { 1824 return multimap.isEmpty(); 1825 } 1826 1827 @Override 1828 public boolean containsKey(@CheckForNull Object key) { 1829 return multimap.containsKey(key); 1830 } 1831 1832 @Override 1833 public void clear() { 1834 multimap.clear(); 1835 } 1836 } 1837 1838 /** 1839 * Returns a multimap containing the mappings in {@code unfiltered} whose keys satisfy a 1840 * predicate. The returned multimap is a live view of {@code unfiltered}; changes to one affect 1841 * the other. 1842 * 1843 * <p>The resulting multimap's views have iterators that don't support {@code remove()}, but all 1844 * other methods are supported by the multimap and its views. When adding a key that doesn't 1845 * satisfy the predicate, the multimap's {@code put()}, {@code putAll()}, and {@code 1846 * replaceValues()} methods throw an {@link IllegalArgumentException}. 1847 * 1848 * <p>When methods such as {@code removeAll()} and {@code clear()} are called on the filtered 1849 * multimap or its views, only mappings whose keys satisfy the filter will be removed from the 1850 * underlying multimap. 1851 * 1852 * <p>The returned multimap isn't threadsafe or serializable, even if {@code unfiltered} is. 1853 * 1854 * <p>Many of the filtered multimap's methods, such as {@code size()}, iterate across every 1855 * key/value mapping in the underlying multimap and determine which satisfy the filter. When a 1856 * live view is <i>not</i> needed, it may be faster to copy the filtered multimap and use the 1857 * copy. 1858 * 1859 * <p><b>Warning:</b> {@code keyPredicate} must be <i>consistent with equals</i>, as documented at 1860 * {@link Predicate#apply}. Do not provide a predicate such as {@code 1861 * Predicates.instanceOf(ArrayList.class)}, which is inconsistent with equals. 1862 * 1863 * @since 11.0 1864 */ 1865 public static <K extends @Nullable Object, V extends @Nullable Object> Multimap<K, V> filterKeys( 1866 Multimap<K, V> unfiltered, final Predicate<? super K> keyPredicate) { 1867 if (unfiltered instanceof SetMultimap) { 1868 return filterKeys((SetMultimap<K, V>) unfiltered, keyPredicate); 1869 } else if (unfiltered instanceof ListMultimap) { 1870 return filterKeys((ListMultimap<K, V>) unfiltered, keyPredicate); 1871 } else if (unfiltered instanceof FilteredKeyMultimap) { 1872 FilteredKeyMultimap<K, V> prev = (FilteredKeyMultimap<K, V>) unfiltered; 1873 return new FilteredKeyMultimap<>( 1874 prev.unfiltered, Predicates.<K>and(prev.keyPredicate, keyPredicate)); 1875 } else if (unfiltered instanceof FilteredMultimap) { 1876 FilteredMultimap<K, V> prev = (FilteredMultimap<K, V>) unfiltered; 1877 return filterFiltered(prev, Maps.<K>keyPredicateOnEntries(keyPredicate)); 1878 } else { 1879 return new FilteredKeyMultimap<>(unfiltered, keyPredicate); 1880 } 1881 } 1882 1883 /** 1884 * Returns a multimap containing the mappings in {@code unfiltered} whose keys satisfy a 1885 * predicate. The returned multimap is a live view of {@code unfiltered}; changes to one affect 1886 * the other. 1887 * 1888 * <p>The resulting multimap's views have iterators that don't support {@code remove()}, but all 1889 * other methods are supported by the multimap and its views. When adding a key that doesn't 1890 * satisfy the predicate, the multimap's {@code put()}, {@code putAll()}, and {@code 1891 * replaceValues()} methods throw an {@link IllegalArgumentException}. 1892 * 1893 * <p>When methods such as {@code removeAll()} and {@code clear()} are called on the filtered 1894 * multimap or its views, only mappings whose keys satisfy the filter will be removed from the 1895 * underlying multimap. 1896 * 1897 * <p>The returned multimap isn't threadsafe or serializable, even if {@code unfiltered} is. 1898 * 1899 * <p>Many of the filtered multimap's methods, such as {@code size()}, iterate across every 1900 * key/value mapping in the underlying multimap and determine which satisfy the filter. When a 1901 * live view is <i>not</i> needed, it may be faster to copy the filtered multimap and use the 1902 * copy. 1903 * 1904 * <p><b>Warning:</b> {@code keyPredicate} must be <i>consistent with equals</i>, as documented at 1905 * {@link Predicate#apply}. Do not provide a predicate such as {@code 1906 * Predicates.instanceOf(ArrayList.class)}, which is inconsistent with equals. 1907 * 1908 * @since 14.0 1909 */ 1910 public static <K extends @Nullable Object, V extends @Nullable Object> 1911 SetMultimap<K, V> filterKeys( 1912 SetMultimap<K, V> unfiltered, final Predicate<? super K> keyPredicate) { 1913 if (unfiltered instanceof FilteredKeySetMultimap) { 1914 FilteredKeySetMultimap<K, V> prev = (FilteredKeySetMultimap<K, V>) unfiltered; 1915 return new FilteredKeySetMultimap<>( 1916 prev.unfiltered(), Predicates.<K>and(prev.keyPredicate, keyPredicate)); 1917 } else if (unfiltered instanceof FilteredSetMultimap) { 1918 FilteredSetMultimap<K, V> prev = (FilteredSetMultimap<K, V>) unfiltered; 1919 return filterFiltered(prev, Maps.<K>keyPredicateOnEntries(keyPredicate)); 1920 } else { 1921 return new FilteredKeySetMultimap<>(unfiltered, keyPredicate); 1922 } 1923 } 1924 1925 /** 1926 * Returns a multimap containing the mappings in {@code unfiltered} whose keys satisfy a 1927 * predicate. The returned multimap is a live view of {@code unfiltered}; changes to one affect 1928 * the other. 1929 * 1930 * <p>The resulting multimap's views have iterators that don't support {@code remove()}, but all 1931 * other methods are supported by the multimap and its views. When adding a key that doesn't 1932 * satisfy the predicate, the multimap's {@code put()}, {@code putAll()}, and {@code 1933 * replaceValues()} methods throw an {@link IllegalArgumentException}. 1934 * 1935 * <p>When methods such as {@code removeAll()} and {@code clear()} are called on the filtered 1936 * multimap or its views, only mappings whose keys satisfy the filter will be removed from the 1937 * underlying multimap. 1938 * 1939 * <p>The returned multimap isn't threadsafe or serializable, even if {@code unfiltered} is. 1940 * 1941 * <p>Many of the filtered multimap's methods, such as {@code size()}, iterate across every 1942 * key/value mapping in the underlying multimap and determine which satisfy the filter. When a 1943 * live view is <i>not</i> needed, it may be faster to copy the filtered multimap and use the 1944 * copy. 1945 * 1946 * <p><b>Warning:</b> {@code keyPredicate} must be <i>consistent with equals</i>, as documented at 1947 * {@link Predicate#apply}. Do not provide a predicate such as {@code 1948 * Predicates.instanceOf(ArrayList.class)}, which is inconsistent with equals. 1949 * 1950 * @since 14.0 1951 */ 1952 public static <K extends @Nullable Object, V extends @Nullable Object> 1953 ListMultimap<K, V> filterKeys( 1954 ListMultimap<K, V> unfiltered, final Predicate<? super K> keyPredicate) { 1955 if (unfiltered instanceof FilteredKeyListMultimap) { 1956 FilteredKeyListMultimap<K, V> prev = (FilteredKeyListMultimap<K, V>) unfiltered; 1957 return new FilteredKeyListMultimap<>( 1958 prev.unfiltered(), Predicates.<K>and(prev.keyPredicate, keyPredicate)); 1959 } else { 1960 return new FilteredKeyListMultimap<>(unfiltered, keyPredicate); 1961 } 1962 } 1963 1964 /** 1965 * Returns a multimap containing the mappings in {@code unfiltered} whose values satisfy a 1966 * predicate. The returned multimap is a live view of {@code unfiltered}; changes to one affect 1967 * the other. 1968 * 1969 * <p>The resulting multimap's views have iterators that don't support {@code remove()}, but all 1970 * other methods are supported by the multimap and its views. When adding a value that doesn't 1971 * satisfy the predicate, the multimap's {@code put()}, {@code putAll()}, and {@code 1972 * replaceValues()} methods throw an {@link IllegalArgumentException}. 1973 * 1974 * <p>When methods such as {@code removeAll()} and {@code clear()} are called on the filtered 1975 * multimap or its views, only mappings whose value satisfy the filter will be removed from the 1976 * underlying multimap. 1977 * 1978 * <p>The returned multimap isn't threadsafe or serializable, even if {@code unfiltered} is. 1979 * 1980 * <p>Many of the filtered multimap's methods, such as {@code size()}, iterate across every 1981 * key/value mapping in the underlying multimap and determine which satisfy the filter. When a 1982 * live view is <i>not</i> needed, it may be faster to copy the filtered multimap and use the 1983 * copy. 1984 * 1985 * <p><b>Warning:</b> {@code valuePredicate} must be <i>consistent with equals</i>, as documented 1986 * at {@link Predicate#apply}. Do not provide a predicate such as {@code 1987 * Predicates.instanceOf(ArrayList.class)}, which is inconsistent with equals. 1988 * 1989 * @since 11.0 1990 */ 1991 public static <K extends @Nullable Object, V extends @Nullable Object> 1992 Multimap<K, V> filterValues( 1993 Multimap<K, V> unfiltered, final Predicate<? super V> valuePredicate) { 1994 return filterEntries(unfiltered, Maps.<V>valuePredicateOnEntries(valuePredicate)); 1995 } 1996 1997 /** 1998 * Returns a multimap containing the mappings in {@code unfiltered} whose values satisfy a 1999 * predicate. The returned multimap is a live view of {@code unfiltered}; changes to one affect 2000 * the other. 2001 * 2002 * <p>The resulting multimap's views have iterators that don't support {@code remove()}, but all 2003 * other methods are supported by the multimap and its views. When adding a value that doesn't 2004 * satisfy the predicate, the multimap's {@code put()}, {@code putAll()}, and {@code 2005 * replaceValues()} methods throw an {@link IllegalArgumentException}. 2006 * 2007 * <p>When methods such as {@code removeAll()} and {@code clear()} are called on the filtered 2008 * multimap or its views, only mappings whose value satisfy the filter will be removed from the 2009 * underlying multimap. 2010 * 2011 * <p>The returned multimap isn't threadsafe or serializable, even if {@code unfiltered} is. 2012 * 2013 * <p>Many of the filtered multimap's methods, such as {@code size()}, iterate across every 2014 * key/value mapping in the underlying multimap and determine which satisfy the filter. When a 2015 * live view is <i>not</i> needed, it may be faster to copy the filtered multimap and use the 2016 * copy. 2017 * 2018 * <p><b>Warning:</b> {@code valuePredicate} must be <i>consistent with equals</i>, as documented 2019 * at {@link Predicate#apply}. Do not provide a predicate such as {@code 2020 * Predicates.instanceOf(ArrayList.class)}, which is inconsistent with equals. 2021 * 2022 * @since 14.0 2023 */ 2024 public static <K extends @Nullable Object, V extends @Nullable Object> 2025 SetMultimap<K, V> filterValues( 2026 SetMultimap<K, V> unfiltered, final Predicate<? super V> valuePredicate) { 2027 return filterEntries(unfiltered, Maps.<V>valuePredicateOnEntries(valuePredicate)); 2028 } 2029 2030 /** 2031 * Returns a multimap containing the mappings in {@code unfiltered} that satisfy a predicate. The 2032 * returned multimap is a live view of {@code unfiltered}; changes to one affect the other. 2033 * 2034 * <p>The resulting multimap's views have iterators that don't support {@code remove()}, but all 2035 * other methods are supported by the multimap and its views. When adding a key/value pair that 2036 * doesn't satisfy the predicate, multimap's {@code put()}, {@code putAll()}, and {@code 2037 * replaceValues()} methods throw an {@link IllegalArgumentException}. 2038 * 2039 * <p>When methods such as {@code removeAll()} and {@code clear()} are called on the filtered 2040 * multimap or its views, only mappings whose keys satisfy the filter will be removed from the 2041 * underlying multimap. 2042 * 2043 * <p>The returned multimap isn't threadsafe or serializable, even if {@code unfiltered} is. 2044 * 2045 * <p>Many of the filtered multimap's methods, such as {@code size()}, iterate across every 2046 * key/value mapping in the underlying multimap and determine which satisfy the filter. When a 2047 * live view is <i>not</i> needed, it may be faster to copy the filtered multimap and use the 2048 * copy. 2049 * 2050 * <p><b>Warning:</b> {@code entryPredicate} must be <i>consistent with equals</i>, as documented 2051 * at {@link Predicate#apply}. 2052 * 2053 * @since 11.0 2054 */ 2055 public static <K extends @Nullable Object, V extends @Nullable Object> 2056 Multimap<K, V> filterEntries( 2057 Multimap<K, V> unfiltered, Predicate<? super Entry<K, V>> entryPredicate) { 2058 checkNotNull(entryPredicate); 2059 if (unfiltered instanceof SetMultimap) { 2060 return filterEntries((SetMultimap<K, V>) unfiltered, entryPredicate); 2061 } 2062 return (unfiltered instanceof FilteredMultimap) 2063 ? filterFiltered((FilteredMultimap<K, V>) unfiltered, entryPredicate) 2064 : new FilteredEntryMultimap<K, V>(checkNotNull(unfiltered), entryPredicate); 2065 } 2066 2067 /** 2068 * Returns a multimap containing the mappings in {@code unfiltered} that satisfy a predicate. The 2069 * returned multimap is a live view of {@code unfiltered}; changes to one affect the other. 2070 * 2071 * <p>The resulting multimap's views have iterators that don't support {@code remove()}, but all 2072 * other methods are supported by the multimap and its views. When adding a key/value pair that 2073 * doesn't satisfy the predicate, multimap's {@code put()}, {@code putAll()}, and {@code 2074 * replaceValues()} methods throw an {@link IllegalArgumentException}. 2075 * 2076 * <p>When methods such as {@code removeAll()} and {@code clear()} are called on the filtered 2077 * multimap or its views, only mappings whose keys satisfy the filter will be removed from the 2078 * underlying multimap. 2079 * 2080 * <p>The returned multimap isn't threadsafe or serializable, even if {@code unfiltered} is. 2081 * 2082 * <p>Many of the filtered multimap's methods, such as {@code size()}, iterate across every 2083 * key/value mapping in the underlying multimap and determine which satisfy the filter. When a 2084 * live view is <i>not</i> needed, it may be faster to copy the filtered multimap and use the 2085 * copy. 2086 * 2087 * <p><b>Warning:</b> {@code entryPredicate} must be <i>consistent with equals</i>, as documented 2088 * at {@link Predicate#apply}. 2089 * 2090 * @since 14.0 2091 */ 2092 public static <K extends @Nullable Object, V extends @Nullable Object> 2093 SetMultimap<K, V> filterEntries( 2094 SetMultimap<K, V> unfiltered, Predicate<? super Entry<K, V>> entryPredicate) { 2095 checkNotNull(entryPredicate); 2096 return (unfiltered instanceof FilteredSetMultimap) 2097 ? filterFiltered((FilteredSetMultimap<K, V>) unfiltered, entryPredicate) 2098 : new FilteredEntrySetMultimap<K, V>(checkNotNull(unfiltered), entryPredicate); 2099 } 2100 2101 /** 2102 * Support removal operations when filtering a filtered multimap. Since a filtered multimap has 2103 * iterators that don't support remove, passing one to the FilteredEntryMultimap constructor would 2104 * lead to a multimap whose removal operations would fail. This method combines the predicates to 2105 * avoid that problem. 2106 */ 2107 private static <K extends @Nullable Object, V extends @Nullable Object> 2108 Multimap<K, V> filterFiltered( 2109 FilteredMultimap<K, V> multimap, Predicate<? super Entry<K, V>> entryPredicate) { 2110 Predicate<Entry<K, V>> predicate = 2111 Predicates.<Entry<K, V>>and(multimap.entryPredicate(), entryPredicate); 2112 return new FilteredEntryMultimap<>(multimap.unfiltered(), predicate); 2113 } 2114 2115 /** 2116 * Support removal operations when filtering a filtered multimap. Since a filtered multimap has 2117 * iterators that don't support remove, passing one to the FilteredEntryMultimap constructor would 2118 * lead to a multimap whose removal operations would fail. This method combines the predicates to 2119 * avoid that problem. 2120 */ 2121 private static <K extends @Nullable Object, V extends @Nullable Object> 2122 SetMultimap<K, V> filterFiltered( 2123 FilteredSetMultimap<K, V> multimap, Predicate<? super Entry<K, V>> entryPredicate) { 2124 Predicate<Entry<K, V>> predicate = 2125 Predicates.<Entry<K, V>>and(multimap.entryPredicate(), entryPredicate); 2126 return new FilteredEntrySetMultimap<>(multimap.unfiltered(), predicate); 2127 } 2128 2129 static boolean equalsImpl(Multimap<?, ?> multimap, @CheckForNull Object object) { 2130 if (object == multimap) { 2131 return true; 2132 } 2133 if (object instanceof Multimap) { 2134 Multimap<?, ?> that = (Multimap<?, ?>) object; 2135 return multimap.asMap().equals(that.asMap()); 2136 } 2137 return false; 2138 } 2139 2140 // TODO(jlevy): Create methods that filter a SortedSetMultimap. 2141}