001/*
002 * Copyright (C) 2008 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.base.Preconditions.checkState;
021import static com.google.common.collect.CollectPreconditions.checkEntryNotNull;
022import static com.google.common.collect.CollectPreconditions.checkNonnegative;
023
024import com.google.common.annotations.Beta;
025import com.google.common.annotations.GwtCompatible;
026import com.google.common.annotations.VisibleForTesting;
027import com.google.errorprone.annotations.CanIgnoreReturnValue;
028import com.google.errorprone.annotations.DoNotMock;
029import com.google.errorprone.annotations.concurrent.LazyInit;
030import com.google.j2objc.annotations.RetainedWith;
031import com.google.j2objc.annotations.WeakOuter;
032import java.io.Serializable;
033import java.util.AbstractMap;
034import java.util.Arrays;
035import java.util.Collection;
036import java.util.Collections;
037import java.util.Comparator;
038import java.util.EnumMap;
039import java.util.Iterator;
040import java.util.LinkedHashMap;
041import java.util.Map;
042import java.util.SortedMap;
043import java.util.Spliterator;
044import java.util.Spliterators;
045import java.util.function.BiFunction;
046import java.util.function.BinaryOperator;
047import java.util.function.Function;
048import java.util.stream.Collector;
049import java.util.stream.Collectors;
050import org.checkerframework.checker.nullness.qual.Nullable;
051
052/**
053 * A {@link Map} whose contents will never change, with many other important properties detailed at
054 * {@link ImmutableCollection}.
055 *
056 * <p>See the Guava User Guide article on <a href=
057 * "https://github.com/google/guava/wiki/ImmutableCollectionsExplained"> immutable collections</a>.
058 *
059 * @author Jesse Wilson
060 * @author Kevin Bourrillion
061 * @since 2.0
062 */
063@DoNotMock("Use ImmutableMap.of or another implementation")
064@GwtCompatible(serializable = true, emulated = true)
065@SuppressWarnings("serial") // we're overriding default serialization
066public abstract class ImmutableMap<K, V> implements Map<K, V>, Serializable {
067
068  /**
069   * Returns a {@link Collector} that accumulates elements into an {@code ImmutableMap} whose keys
070   * and values are the result of applying the provided mapping functions to the input elements.
071   * Entries appear in the result {@code ImmutableMap} in encounter order.
072   *
073   * <p>If the mapped keys contain duplicates (according to {@link Object#equals(Object)}, an {@code
074   * IllegalArgumentException} is thrown when the collection operation is performed. (This differs
075   * from the {@code Collector} returned by {@link Collectors#toMap(Function, Function)}, which
076   * throws an {@code IllegalStateException}.)
077   *
078   * @since 21.0
079   */
080  public static <T, K, V> Collector<T, ?, ImmutableMap<K, V>> toImmutableMap(
081      Function<? super T, ? extends K> keyFunction,
082      Function<? super T, ? extends V> valueFunction) {
083    return CollectCollectors.toImmutableMap(keyFunction, valueFunction);
084  }
085
086  /**
087   * Returns a {@link Collector} that accumulates elements into an {@code ImmutableMap} whose keys
088   * and values are the result of applying the provided mapping functions to the input elements.
089   *
090   * <p>If the mapped keys contain duplicates (according to {@link Object#equals(Object)}), the
091   * values are merged using the specified merging function. Entries will appear in the encounter
092   * order of the first occurrence of the key.
093   *
094   * @since 21.0
095   */
096  public static <T, K, V> Collector<T, ?, ImmutableMap<K, V>> toImmutableMap(
097      Function<? super T, ? extends K> keyFunction,
098      Function<? super T, ? extends V> valueFunction,
099      BinaryOperator<V> mergeFunction) {
100    checkNotNull(keyFunction);
101    checkNotNull(valueFunction);
102    checkNotNull(mergeFunction);
103    return Collectors.collectingAndThen(
104        Collectors.toMap(keyFunction, valueFunction, mergeFunction, LinkedHashMap::new),
105        ImmutableMap::copyOf);
106  }
107
108  /**
109   * Returns the empty map. This map behaves and performs comparably to {@link
110   * Collections#emptyMap}, and is preferable mainly for consistency and maintainability of your
111   * code.
112   */
113  @SuppressWarnings("unchecked")
114  public static <K, V> ImmutableMap<K, V> of() {
115    return (ImmutableMap<K, V>) RegularImmutableMap.EMPTY;
116  }
117
118  /**
119   * Returns an immutable map containing a single entry. This map behaves and performs comparably to
120   * {@link Collections#singletonMap} but will not accept a null key or value. It is preferable
121   * mainly for consistency and maintainability of your code.
122   */
123  public static <K, V> ImmutableMap<K, V> of(K k1, V v1) {
124    return ImmutableBiMap.of(k1, v1);
125  }
126
127  /**
128   * Returns an immutable map containing the given entries, in order.
129   *
130   * @throws IllegalArgumentException if duplicate keys are provided
131   */
132  public static <K, V> ImmutableMap<K, V> of(K k1, V v1, K k2, V v2) {
133    return RegularImmutableMap.fromEntries(entryOf(k1, v1), entryOf(k2, v2));
134  }
135
136  /**
137   * Returns an immutable map containing the given entries, in order.
138   *
139   * @throws IllegalArgumentException if duplicate keys are provided
140   */
141  public static <K, V> ImmutableMap<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3) {
142    return RegularImmutableMap.fromEntries(entryOf(k1, v1), entryOf(k2, v2), entryOf(k3, v3));
143  }
144
145  /**
146   * Returns an immutable map containing the given entries, in order.
147   *
148   * @throws IllegalArgumentException if duplicate keys are provided
149   */
150  public static <K, V> ImmutableMap<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4) {
151    return RegularImmutableMap.fromEntries(
152        entryOf(k1, v1), entryOf(k2, v2), entryOf(k3, v3), entryOf(k4, v4));
153  }
154
155  /**
156   * Returns an immutable map containing the given entries, in order.
157   *
158   * @throws IllegalArgumentException if duplicate keys are provided
159   */
160  public static <K, V> ImmutableMap<K, V> of(
161      K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5) {
162    return RegularImmutableMap.fromEntries(
163        entryOf(k1, v1), entryOf(k2, v2), entryOf(k3, v3), entryOf(k4, v4), entryOf(k5, v5));
164  }
165
166  // looking for of() with > 5 entries? Use the builder instead.
167
168  /**
169   * Verifies that {@code key} and {@code value} are non-null, and returns a new immutable entry
170   * with those values.
171   *
172   * <p>A call to {@link Entry#setValue} on the returned entry will always throw {@link
173   * UnsupportedOperationException}.
174   */
175  static <K, V> Entry<K, V> entryOf(K key, V value) {
176    checkEntryNotNull(key, value);
177    return new AbstractMap.SimpleImmutableEntry<>(key, value);
178  }
179
180  /**
181   * Returns a new builder. The generated builder is equivalent to the builder created by the {@link
182   * Builder} constructor.
183   */
184  public static <K, V> Builder<K, V> builder() {
185    return new Builder<>();
186  }
187
188  /**
189   * Returns a new builder, expecting the specified number of entries to be added.
190   *
191   * <p>If {@code expectedSize} is exactly the number of entries added to the builder before {@link
192   * Builder#build} is called, the builder is likely to perform better than an unsized {@link
193   * #builder()} would have.
194   *
195   * <p>It is not specified if any performance benefits apply if {@code expectedSize} is close to,
196   * but not exactly, the number of entries added to the builder.
197   *
198   * @since 23.1
199   */
200  @Beta
201  public static <K, V> Builder<K, V> builderWithExpectedSize(int expectedSize) {
202    checkNonnegative(expectedSize, "expectedSize");
203    return new Builder<>(expectedSize);
204  }
205
206  static void checkNoConflict(
207      boolean safe, String conflictDescription, Entry<?, ?> entry1, Entry<?, ?> entry2) {
208    if (!safe) {
209      throw conflictException(conflictDescription, entry1, entry2);
210    }
211  }
212
213  static IllegalArgumentException conflictException(
214      String conflictDescription, Object entry1, Object entry2) {
215    return new IllegalArgumentException(
216        "Multiple entries with same " + conflictDescription + ": " + entry1 + " and " + entry2);
217  }
218
219  /**
220   * A builder for creating immutable map instances, especially {@code public static final} maps
221   * ("constant maps"). Example:
222   *
223   * <pre>{@code
224   * static final ImmutableMap<String, Integer> WORD_TO_INT =
225   *     new ImmutableMap.Builder<String, Integer>()
226   *         .put("one", 1)
227   *         .put("two", 2)
228   *         .put("three", 3)
229   *         .build();
230   * }</pre>
231   *
232   * <p>For <i>small</i> immutable maps, the {@code ImmutableMap.of()} methods are even more
233   * convenient.
234   *
235   * <p>By default, a {@code Builder} will generate maps that iterate over entries in the order they
236   * were inserted into the builder, equivalently to {@code LinkedHashMap}. For example, in the
237   * above example, {@code WORD_TO_INT.entrySet()} is guaranteed to iterate over the entries in the
238   * order {@code "one"=1, "two"=2, "three"=3}, and {@code keySet()} and {@code values()} respect
239   * the same order. If you want a different order, consider using {@link ImmutableSortedMap} to
240   * sort by keys, or call {@link #orderEntriesByValue(Comparator)}, which changes this builder to
241   * sort entries by value.
242   *
243   * <p>Builder instances can be reused - it is safe to call {@link #build} multiple times to build
244   * multiple maps in series. Each map is a superset of the maps created before it.
245   *
246   * @since 2.0
247   */
248  @DoNotMock
249  public static class Builder<K, V> {
250    @Nullable Comparator<? super V> valueComparator;
251    Entry<K, V>[] entries;
252    int size;
253    boolean entriesUsed;
254
255    /**
256     * Creates a new builder. The returned builder is equivalent to the builder generated by {@link
257     * ImmutableMap#builder}.
258     */
259    public Builder() {
260      this(ImmutableCollection.Builder.DEFAULT_INITIAL_CAPACITY);
261    }
262
263    @SuppressWarnings("unchecked")
264    Builder(int initialCapacity) {
265      this.entries = new Entry[initialCapacity];
266      this.size = 0;
267      this.entriesUsed = false;
268    }
269
270    private void ensureCapacity(int minCapacity) {
271      if (minCapacity > entries.length) {
272        entries =
273            Arrays.copyOf(
274                entries, ImmutableCollection.Builder.expandedCapacity(entries.length, minCapacity));
275        entriesUsed = false;
276      }
277    }
278
279    /**
280     * Associates {@code key} with {@code value} in the built map. Duplicate keys are not allowed,
281     * and will cause {@link #build} to fail.
282     */
283    @CanIgnoreReturnValue
284    public Builder<K, V> put(K key, V value) {
285      ensureCapacity(size + 1);
286      Entry<K, V> entry = entryOf(key, value);
287      // don't inline this: we want to fail atomically if key or value is null
288      entries[size++] = entry;
289      return this;
290    }
291
292    /**
293     * Adds the given {@code entry} to the map, making it immutable if necessary. Duplicate keys are
294     * not allowed, and will cause {@link #build} to fail.
295     *
296     * @since 11.0
297     */
298    @CanIgnoreReturnValue
299    public Builder<K, V> put(Entry<? extends K, ? extends V> entry) {
300      return put(entry.getKey(), entry.getValue());
301    }
302
303    /**
304     * Associates all of the given map's keys and values in the built map. Duplicate keys are not
305     * allowed, and will cause {@link #build} to fail.
306     *
307     * @throws NullPointerException if any key or value in {@code map} is null
308     */
309    @CanIgnoreReturnValue
310    public Builder<K, V> putAll(Map<? extends K, ? extends V> map) {
311      return putAll(map.entrySet());
312    }
313
314    /**
315     * Adds all of the given entries to the built map. Duplicate keys are not allowed, and will
316     * cause {@link #build} to fail.
317     *
318     * @throws NullPointerException if any key, value, or entry is null
319     * @since 19.0
320     */
321    @CanIgnoreReturnValue
322    @Beta
323    public Builder<K, V> putAll(Iterable<? extends Entry<? extends K, ? extends V>> entries) {
324      if (entries instanceof Collection) {
325        ensureCapacity(size + ((Collection<?>) entries).size());
326      }
327      for (Entry<? extends K, ? extends V> entry : entries) {
328        put(entry);
329      }
330      return this;
331    }
332
333    /**
334     * Configures this {@code Builder} to order entries by value according to the specified
335     * comparator.
336     *
337     * <p>The sort order is stable, that is, if two entries have values that compare as equivalent,
338     * the entry that was inserted first will be first in the built map's iteration order.
339     *
340     * @throws IllegalStateException if this method was already called
341     * @since 19.0
342     */
343    @CanIgnoreReturnValue
344    @Beta
345    public Builder<K, V> orderEntriesByValue(Comparator<? super V> valueComparator) {
346      checkState(this.valueComparator == null, "valueComparator was already set");
347      this.valueComparator = checkNotNull(valueComparator, "valueComparator");
348      return this;
349    }
350
351    @CanIgnoreReturnValue
352    Builder<K, V> combine(Builder<K, V> other) {
353      checkNotNull(other);
354      ensureCapacity(this.size + other.size);
355      System.arraycopy(other.entries, 0, this.entries, this.size, other.size);
356      this.size += other.size;
357      return this;
358    }
359
360    /*
361     * TODO(kevinb): Should build() and the ImmutableBiMap & ImmutableSortedMap
362     * versions throw an IllegalStateException instead?
363     */
364
365    /**
366     * Returns a newly-created immutable map. The iteration order of the returned map is the order
367     * in which entries were inserted into the builder, unless {@link #orderEntriesByValue} was
368     * called, in which case entries are sorted by value.
369     *
370     * @throws IllegalArgumentException if duplicate keys were added
371     */
372    public ImmutableMap<K, V> build() {
373      /*
374       * If entries is full, or if hash flooding is detected, then this implementation may end up
375       * using the entries array directly and writing over the entry objects with non-terminal
376       * entries, but this is safe; if this Builder is used further, it will grow the entries array
377       * (so it can't affect the original array), and future build() calls will always copy any
378       * entry objects that cannot be safely reused.
379       */
380      if (valueComparator != null) {
381        if (entriesUsed) {
382          entries = Arrays.copyOf(entries, size);
383        }
384        Arrays.sort(
385            entries, 0, size, Ordering.from(valueComparator).onResultOf(Maps.<V>valueFunction()));
386      }
387      switch (size) {
388        case 0:
389          return of();
390        case 1:
391          return of(entries[0].getKey(), entries[0].getValue());
392        default:
393          entriesUsed = true;
394          return RegularImmutableMap.fromEntryArray(size, entries);
395      }
396    }
397
398    @VisibleForTesting // only for testing JDK backed implementation
399    ImmutableMap<K, V> buildJdkBacked() {
400      checkState(
401          valueComparator == null, "buildJdkBacked is only for testing; can't use valueComparator");
402      switch (size) {
403        case 0:
404          return of();
405        case 1:
406          return of(entries[0].getKey(), entries[0].getValue());
407        default:
408          entriesUsed = true;
409          return JdkBackedImmutableMap.create(size, entries);
410      }
411    }
412  }
413
414  /**
415   * Returns an immutable map containing the same entries as {@code map}. The returned map iterates
416   * over entries in the same order as the {@code entrySet} of the original map. If {@code map}
417   * somehow contains entries with duplicate keys (for example, if it is a {@code SortedMap} whose
418   * comparator is not <i>consistent with equals</i>), the results of this method are undefined.
419   *
420   * <p>Despite the method name, this method attempts to avoid actually copying the data when it is
421   * safe to do so. The exact circumstances under which a copy will or will not be performed are
422   * undocumented and subject to change.
423   *
424   * @throws NullPointerException if any key or value in {@code map} is null
425   */
426  public static <K, V> ImmutableMap<K, V> copyOf(Map<? extends K, ? extends V> map) {
427    if ((map instanceof ImmutableMap) && !(map instanceof SortedMap)) {
428      @SuppressWarnings("unchecked") // safe since map is not writable
429      ImmutableMap<K, V> kvMap = (ImmutableMap<K, V>) map;
430      if (!kvMap.isPartialView()) {
431        return kvMap;
432      }
433    } else if (map instanceof EnumMap) {
434      @SuppressWarnings("unchecked") // safe since map is not writable
435      ImmutableMap<K, V> kvMap = (ImmutableMap<K, V>) copyOfEnumMap((EnumMap<?, ?>) map);
436      return kvMap;
437    }
438    return copyOf(map.entrySet());
439  }
440
441  /**
442   * Returns an immutable map containing the specified entries. The returned map iterates over
443   * entries in the same order as the original iterable.
444   *
445   * @throws NullPointerException if any key, value, or entry is null
446   * @throws IllegalArgumentException if two entries have the same key
447   * @since 19.0
448   */
449  @Beta
450  public static <K, V> ImmutableMap<K, V> copyOf(
451      Iterable<? extends Entry<? extends K, ? extends V>> entries) {
452    @SuppressWarnings("unchecked") // we'll only be using getKey and getValue, which are covariant
453    Entry<K, V>[] entryArray = (Entry<K, V>[]) Iterables.toArray(entries, EMPTY_ENTRY_ARRAY);
454    switch (entryArray.length) {
455      case 0:
456        return of();
457      case 1:
458        Entry<K, V> onlyEntry = entryArray[0];
459        return of(onlyEntry.getKey(), onlyEntry.getValue());
460      default:
461        /*
462         * The current implementation will end up using entryArray directly, though it will write
463         * over the (arbitrary, potentially mutable) Entry objects actually stored in entryArray.
464         */
465        return RegularImmutableMap.fromEntries(entryArray);
466    }
467  }
468
469  private static <K extends Enum<K>, V> ImmutableMap<K, V> copyOfEnumMap(
470      EnumMap<K, ? extends V> original) {
471    EnumMap<K, V> copy = new EnumMap<>(original);
472    for (Entry<?, ?> entry : copy.entrySet()) {
473      checkEntryNotNull(entry.getKey(), entry.getValue());
474    }
475    return ImmutableEnumMap.asImmutable(copy);
476  }
477
478  static final Entry<?, ?>[] EMPTY_ENTRY_ARRAY = new Entry<?, ?>[0];
479
480  abstract static class IteratorBasedImmutableMap<K, V> extends ImmutableMap<K, V> {
481    abstract UnmodifiableIterator<Entry<K, V>> entryIterator();
482
483    Spliterator<Entry<K, V>> entrySpliterator() {
484      return Spliterators.spliterator(
485          entryIterator(),
486          size(),
487          Spliterator.DISTINCT | Spliterator.NONNULL | Spliterator.IMMUTABLE | Spliterator.ORDERED);
488    }
489
490    @Override
491    ImmutableSet<K> createKeySet() {
492      return new ImmutableMapKeySet<>(this);
493    }
494
495    @Override
496    ImmutableSet<Entry<K, V>> createEntrySet() {
497      class EntrySetImpl extends ImmutableMapEntrySet<K, V> {
498        @Override
499        ImmutableMap<K, V> map() {
500          return IteratorBasedImmutableMap.this;
501        }
502
503        @Override
504        public UnmodifiableIterator<Entry<K, V>> iterator() {
505          return entryIterator();
506        }
507      }
508      return new EntrySetImpl();
509    }
510
511    @Override
512    ImmutableCollection<V> createValues() {
513      return new ImmutableMapValues<>(this);
514    }
515  }
516
517  ImmutableMap() {}
518
519  /**
520   * Guaranteed to throw an exception and leave the map unmodified.
521   *
522   * @throws UnsupportedOperationException always
523   * @deprecated Unsupported operation.
524   */
525  @CanIgnoreReturnValue
526  @Deprecated
527  @Override
528  public final V put(K k, V v) {
529    throw new UnsupportedOperationException();
530  }
531
532  /**
533   * Guaranteed to throw an exception and leave the map unmodified.
534   *
535   * @throws UnsupportedOperationException always
536   * @deprecated Unsupported operation.
537   */
538  @CanIgnoreReturnValue
539  @Deprecated
540  @Override
541  public final V putIfAbsent(K key, V value) {
542    throw new UnsupportedOperationException();
543  }
544
545  /**
546   * Guaranteed to throw an exception and leave the map unmodified.
547   *
548   * @throws UnsupportedOperationException always
549   * @deprecated Unsupported operation.
550   */
551  @Deprecated
552  @Override
553  public final boolean replace(K key, V oldValue, V newValue) {
554    throw new UnsupportedOperationException();
555  }
556
557  /**
558   * Guaranteed to throw an exception and leave the map unmodified.
559   *
560   * @throws UnsupportedOperationException always
561   * @deprecated Unsupported operation.
562   */
563  @Deprecated
564  @Override
565  public final V replace(K key, V value) {
566    throw new UnsupportedOperationException();
567  }
568
569  /**
570   * Guaranteed to throw an exception and leave the map unmodified.
571   *
572   * @throws UnsupportedOperationException always
573   * @deprecated Unsupported operation.
574   */
575  @Deprecated
576  @Override
577  public final V computeIfAbsent(K key, Function<? super K, ? extends V> mappingFunction) {
578    throw new UnsupportedOperationException();
579  }
580
581  /**
582   * Guaranteed to throw an exception and leave the map unmodified.
583   *
584   * @throws UnsupportedOperationException always
585   * @deprecated Unsupported operation.
586   */
587  @Deprecated
588  @Override
589  public final V computeIfPresent(
590      K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction) {
591    throw new UnsupportedOperationException();
592  }
593
594  /**
595   * Guaranteed to throw an exception and leave the map unmodified.
596   *
597   * @throws UnsupportedOperationException always
598   * @deprecated Unsupported operation.
599   */
600  @Deprecated
601  @Override
602  public final V compute(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction) {
603    throw new UnsupportedOperationException();
604  }
605
606  /**
607   * Guaranteed to throw an exception and leave the map unmodified.
608   *
609   * @throws UnsupportedOperationException always
610   * @deprecated Unsupported operation.
611   */
612  @Deprecated
613  @Override
614  public final V merge(
615      K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction) {
616    throw new UnsupportedOperationException();
617  }
618
619  /**
620   * Guaranteed to throw an exception and leave the map unmodified.
621   *
622   * @throws UnsupportedOperationException always
623   * @deprecated Unsupported operation.
624   */
625  @Deprecated
626  @Override
627  public final void putAll(Map<? extends K, ? extends V> map) {
628    throw new UnsupportedOperationException();
629  }
630
631  /**
632   * Guaranteed to throw an exception and leave the map unmodified.
633   *
634   * @throws UnsupportedOperationException always
635   * @deprecated Unsupported operation.
636   */
637  @Deprecated
638  @Override
639  public final void replaceAll(BiFunction<? super K, ? super V, ? extends V> function) {
640    throw new UnsupportedOperationException();
641  }
642
643  /**
644   * Guaranteed to throw an exception and leave the map unmodified.
645   *
646   * @throws UnsupportedOperationException always
647   * @deprecated Unsupported operation.
648   */
649  @Deprecated
650  @Override
651  public final V remove(Object o) {
652    throw new UnsupportedOperationException();
653  }
654
655  /**
656   * Guaranteed to throw an exception and leave the map unmodified.
657   *
658   * @throws UnsupportedOperationException always
659   * @deprecated Unsupported operation.
660   */
661  @Deprecated
662  @Override
663  public final boolean remove(Object key, Object value) {
664    throw new UnsupportedOperationException();
665  }
666
667  /**
668   * Guaranteed to throw an exception and leave the map unmodified.
669   *
670   * @throws UnsupportedOperationException always
671   * @deprecated Unsupported operation.
672   */
673  @Deprecated
674  @Override
675  public final void clear() {
676    throw new UnsupportedOperationException();
677  }
678
679  @Override
680  public boolean isEmpty() {
681    return size() == 0;
682  }
683
684  @Override
685  public boolean containsKey(@Nullable Object key) {
686    return get(key) != null;
687  }
688
689  @Override
690  public boolean containsValue(@Nullable Object value) {
691    return values().contains(value);
692  }
693
694  // Overriding to mark it Nullable
695  @Override
696  public abstract V get(@Nullable Object key);
697
698  /**
699   * @since 21.0 (but only since 23.5 in the Android <a
700   *     href="https://github.com/google/guava#guava-google-core-libraries-for-java">flavor</a>).
701   *     Note, however, that Java 8 users can call this method with any version and flavor of Guava.
702   */
703  @Override
704  public final V getOrDefault(@Nullable Object key, @Nullable V defaultValue) {
705    V result = get(key);
706    return (result != null) ? result : defaultValue;
707  }
708
709  @LazyInit @RetainedWith private transient ImmutableSet<Entry<K, V>> entrySet;
710
711  /**
712   * Returns an immutable set of the mappings in this map. The iteration order is specified by the
713   * method used to create this map. Typically, this is insertion order.
714   */
715  @Override
716  public ImmutableSet<Entry<K, V>> entrySet() {
717    ImmutableSet<Entry<K, V>> result = entrySet;
718    return (result == null) ? entrySet = createEntrySet() : result;
719  }
720
721  abstract ImmutableSet<Entry<K, V>> createEntrySet();
722
723  @LazyInit @RetainedWith private transient ImmutableSet<K> keySet;
724
725  /**
726   * Returns an immutable set of the keys in this map, in the same order that they appear in {@link
727   * #entrySet}.
728   */
729  @Override
730  public ImmutableSet<K> keySet() {
731    ImmutableSet<K> result = keySet;
732    return (result == null) ? keySet = createKeySet() : result;
733  }
734
735  /*
736   * This could have a good default implementation of return new ImmutableKeySet<K, V>(this),
737   * but ProGuard can't figure out how to eliminate that default when RegularImmutableMap
738   * overrides it.
739   */
740  abstract ImmutableSet<K> createKeySet();
741
742  UnmodifiableIterator<K> keyIterator() {
743    final UnmodifiableIterator<Entry<K, V>> entryIterator = entrySet().iterator();
744    return new UnmodifiableIterator<K>() {
745      @Override
746      public boolean hasNext() {
747        return entryIterator.hasNext();
748      }
749
750      @Override
751      public K next() {
752        return entryIterator.next().getKey();
753      }
754    };
755  }
756
757  Spliterator<K> keySpliterator() {
758    return CollectSpliterators.map(entrySet().spliterator(), Entry::getKey);
759  }
760
761  @LazyInit @RetainedWith private transient ImmutableCollection<V> values;
762
763  /**
764   * Returns an immutable collection of the values in this map, in the same order that they appear
765   * in {@link #entrySet}.
766   */
767  @Override
768  public ImmutableCollection<V> values() {
769    ImmutableCollection<V> result = values;
770    return (result == null) ? values = createValues() : result;
771  }
772
773  /*
774   * This could have a good default implementation of {@code return new
775   * ImmutableMapValues<K, V>(this)}, but ProGuard can't figure out how to eliminate that default
776   * when RegularImmutableMap overrides it.
777   */
778  abstract ImmutableCollection<V> createValues();
779
780  // cached so that this.multimapView().inverse() only computes inverse once
781  @LazyInit private transient ImmutableSetMultimap<K, V> multimapView;
782
783  /**
784   * Returns a multimap view of the map.
785   *
786   * @since 14.0
787   */
788  public ImmutableSetMultimap<K, V> asMultimap() {
789    if (isEmpty()) {
790      return ImmutableSetMultimap.of();
791    }
792    ImmutableSetMultimap<K, V> result = multimapView;
793    return (result == null)
794        ? (multimapView =
795            new ImmutableSetMultimap<>(new MapViewOfValuesAsSingletonSets(), size(), null))
796        : result;
797  }
798
799  @WeakOuter
800  private final class MapViewOfValuesAsSingletonSets
801      extends IteratorBasedImmutableMap<K, ImmutableSet<V>> {
802
803    @Override
804    public int size() {
805      return ImmutableMap.this.size();
806    }
807
808    @Override
809    ImmutableSet<K> createKeySet() {
810      return ImmutableMap.this.keySet();
811    }
812
813    @Override
814    public boolean containsKey(@Nullable Object key) {
815      return ImmutableMap.this.containsKey(key);
816    }
817
818    @Override
819    public ImmutableSet<V> get(@Nullable Object key) {
820      V outerValue = ImmutableMap.this.get(key);
821      return (outerValue == null) ? null : ImmutableSet.of(outerValue);
822    }
823
824    @Override
825    boolean isPartialView() {
826      return ImmutableMap.this.isPartialView();
827    }
828
829    @Override
830    public int hashCode() {
831      // ImmutableSet.of(value).hashCode() == value.hashCode(), so the hashes are the same
832      return ImmutableMap.this.hashCode();
833    }
834
835    @Override
836    boolean isHashCodeFast() {
837      return ImmutableMap.this.isHashCodeFast();
838    }
839
840    @Override
841    UnmodifiableIterator<Entry<K, ImmutableSet<V>>> entryIterator() {
842      final Iterator<Entry<K, V>> backingIterator = ImmutableMap.this.entrySet().iterator();
843      return new UnmodifiableIterator<Entry<K, ImmutableSet<V>>>() {
844        @Override
845        public boolean hasNext() {
846          return backingIterator.hasNext();
847        }
848
849        @Override
850        public Entry<K, ImmutableSet<V>> next() {
851          final Entry<K, V> backingEntry = backingIterator.next();
852          return new AbstractMapEntry<K, ImmutableSet<V>>() {
853            @Override
854            public K getKey() {
855              return backingEntry.getKey();
856            }
857
858            @Override
859            public ImmutableSet<V> getValue() {
860              return ImmutableSet.of(backingEntry.getValue());
861            }
862          };
863        }
864      };
865    }
866  }
867
868  @Override
869  public boolean equals(@Nullable Object object) {
870    return Maps.equalsImpl(this, object);
871  }
872
873  abstract boolean isPartialView();
874
875  @Override
876  public int hashCode() {
877    return Sets.hashCodeImpl(entrySet());
878  }
879
880  boolean isHashCodeFast() {
881    return false;
882  }
883
884  @Override
885  public String toString() {
886    return Maps.toStringImpl(this);
887  }
888
889  /**
890   * Serialized type for all ImmutableMap instances. It captures the logical contents and they are
891   * reconstructed using public factory methods. This ensures that the implementation types remain
892   * as implementation details.
893   */
894  static class SerializedForm<K, V> implements Serializable {
895    // This object retains references to collections returned by keySet() and value(). This saves
896    // bytes when the both the map and its keySet or value collection are written to the same
897    // instance of ObjectOutputStream.
898
899    // TODO(b/160980469): remove support for the old serialization format after some time
900    private static final boolean USE_LEGACY_SERIALIZATION = true;
901
902    private final Object keys;
903    private final Object values;
904
905    SerializedForm(ImmutableMap<K, V> map) {
906      if (USE_LEGACY_SERIALIZATION) {
907        Object[] keys = new Object[map.size()];
908        Object[] values = new Object[map.size()];
909        int i = 0;
910        for (Entry<?, ?> entry : map.entrySet()) {
911          keys[i] = entry.getKey();
912          values[i] = entry.getValue();
913          i++;
914        }
915        this.keys = keys;
916        this.values = values;
917        return;
918      }
919      this.keys = map.keySet();
920      this.values = map.values();
921    }
922
923    @SuppressWarnings("unchecked")
924    final Object readResolve() {
925      if (!(this.keys instanceof ImmutableSet)) {
926        return legacyReadResolve();
927      }
928
929      ImmutableSet<K> keySet = (ImmutableSet<K>) this.keys;
930      ImmutableCollection<V> values = (ImmutableCollection<V>) this.values;
931
932      Builder<K, V> builder = makeBuilder(keySet.size());
933
934      UnmodifiableIterator<K> keyIter = keySet.iterator();
935      UnmodifiableIterator<V> valueIter = values.iterator();
936
937      while (keyIter.hasNext()) {
938        builder.put(keyIter.next(), valueIter.next());
939      }
940
941      return builder.build();
942    }
943
944    @SuppressWarnings("unchecked")
945    final Object legacyReadResolve() {
946      K[] keys = (K[]) this.keys;
947      V[] values = (V[]) this.values;
948
949      Builder<K, V> builder = makeBuilder(keys.length);
950
951      for (int i = 0; i < keys.length; i++) {
952        builder.put(keys[i], values[i]);
953      }
954      return builder.build();
955    }
956
957    /**
958     * Returns a builder that builds the unserialized type. Subclasses should override this method.
959     */
960    Builder<K, V> makeBuilder(int size) {
961      return new Builder<>(size);
962    }
963
964    private static final long serialVersionUID = 0;
965  }
966
967  /**
968   * Returns a serializable form of this object. Non-public subclasses should not override this
969   * method. Publicly-accessible subclasses must override this method and should return a subclass
970   * of SerializedForm whose readResolve() method returns objects of the subclass type.
971   */
972  Object writeReplace() {
973    return new SerializedForm<>(this);
974  }
975}