Update javadoc of ImmutableMap.Builder to reflect buildKeepingLast() changes.

eamonnmcmanus · Google Java Core Libraries · commit 89a2e994c848 · 2021-12-23T11:38:53.000-08:00
It is no longer necessarily the case that a `put` of a duplicate key will lead to an exception.

Although `buildKeepingLast()` will usually perform better than the equivalent `LinkedHashMap` + `ImmutableMap.copyOf`, the builder does retain all key/value pairs that were put. So in some cases it may still be preferable to use `LinkedHashMap`.

RELNOTES=n/a
PiperOrigin-RevId: 418040612
diff --git a/android/guava/src/com/google/common/collect/ImmutableMap.java b/android/guava/src/com/google/common/collect/ImmutableMap.java
@@ -420,8 +420,9 @@ private void ensureCapacity(int minCapacity) {
     }
 
     /**
-     * Associates {@code key} with {@code value} in the built map. Duplicate keys are not allowed,
-     * and will cause {@link #build} to fail.
+     * Associates {@code key} with {@code value} in the built map. If the same key is put more than
+     * once, {@link #buildOrThrow} will fail, while {@link #buildKeepingLast} will keep the last
+     * value put for that key.
      */
     @CanIgnoreReturnValue
     public Builder<K, V> put(K key, V value) {
@@ -434,8 +435,9 @@ public Builder<K, V> put(K key, V value) {
     }
 
     /**
-     * Adds the given {@code entry} to the map, making it immutable if necessary. Duplicate keys are
-     * not allowed, and will cause {@link #build} to fail.
+     * Adds the given {@code entry} to the map, making it immutable if necessary. If the same key is
+     * put more than once, {@link #buildOrThrow} will fail, while {@link #buildKeepingLast} will
+     * keep the last value put for that key.
      *
      * @since 11.0
      */
@@ -445,8 +447,9 @@ public Builder<K, V> put(Entry<? extends K, ? extends V> entry) {
     }
 
     /**
-     * Associates all of the given map's keys and values in the built map. Duplicate keys are not
-     * allowed, and will cause {@link #build} to fail.
+     * Associates all of the given map's keys and values in the built map. If the same key is put
+     * more than once, {@link #buildOrThrow} will fail, while {@link #buildKeepingLast} will keep
+     * the last value put for that key.
      *
      * @throws NullPointerException if any key or value in {@code map} is null
      */
@@ -456,8 +459,9 @@ public Builder<K, V> putAll(Map<? extends K, ? extends V> map) {
     }
 
     /**
-     * Adds all of the given entries to the built map. Duplicate keys are not allowed, and will
-     * cause {@link #build} to fail.
+     * Adds all of the given entries to the built map. If the same key is put more than once, {@link
+     * #buildOrThrow} will fail, while {@link #buildKeepingLast} will keep the last value put for
+     * that key.
      *
      * @throws NullPointerException if any key, value, or entry is null
      * @since 19.0
@@ -582,6 +586,12 @@ public ImmutableMap<K, V> buildOrThrow() {
      * entries are sorted by value. If a key was added more than once, it appears in iteration order
      * based on the first time it was added, again unless {@link #orderEntriesByValue} was called.
      *
+     * <p>In the current implementation, all values associated with a given key are stored in the
+     * {@code Builder} object, even though only one of them will be used in the built map. If there
+     * can be many repeated keys, it may be more space-efficient to use a {@link
+     * java.util.LinkedHashMap LinkedHashMap} and {@link ImmutableMap#copyOf} rather than {@code
+     * ImmutableMap.Builder}.
+     *
      * @since NEXT
      */
     public ImmutableMap<K, V> buildKeepingLast() {
diff --git a/guava/src/com/google/common/collect/ImmutableMap.java b/guava/src/com/google/common/collect/ImmutableMap.java
@@ -439,8 +439,9 @@ private void ensureCapacity(int minCapacity) {
     }
 
     /**
-     * Associates {@code key} with {@code value} in the built map. Duplicate keys are not allowed,
-     * and will cause {@link #build} to fail.
+     * Associates {@code key} with {@code value} in the built map. If the same key is put more than
+     * once, {@link #buildOrThrow} will fail, while {@link #buildKeepingLast} will keep the last
+     * value put for that key.
      */
     @CanIgnoreReturnValue
     public Builder<K, V> put(K key, V value) {
@@ -452,8 +453,9 @@ public Builder<K, V> put(K key, V value) {
     }
 
     /**
-     * Adds the given {@code entry} to the map, making it immutable if necessary. Duplicate keys are
-     * not allowed, and will cause {@link #build} to fail.
+     * Adds the given {@code entry} to the map, making it immutable if necessary. If the same key is
+     * put more than once, {@link #buildOrThrow} will fail, while {@link #buildKeepingLast} will
+     * keep the last value put for that key.
      *
      * @since 11.0
      */
@@ -463,8 +465,9 @@ public Builder<K, V> put(Entry<? extends K, ? extends V> entry) {
     }
 
     /**
-     * Associates all of the given map's keys and values in the built map. Duplicate keys are not
-     * allowed, and will cause {@link #build} to fail.
+     * Associates all of the given map's keys and values in the built map. If the same key is put
+     * more than once, {@link #buildOrThrow} will fail, while {@link #buildKeepingLast} will keep
+     * the last value put for that key.
      *
      * @throws NullPointerException if any key or value in {@code map} is null
      */
@@ -474,8 +477,9 @@ public Builder<K, V> putAll(Map<? extends K, ? extends V> map) {
     }
 
     /**
-     * Adds all of the given entries to the built map. Duplicate keys are not allowed, and will
-     * cause {@link #build} to fail.
+     * Adds all of the given entries to the built map. If the same key is put more than once, {@link
+     * #buildOrThrow} will fail, while {@link #buildKeepingLast} will keep the last value put for
+     * that key.
      *
      * @throws NullPointerException if any key, value, or entry is null
      * @since 19.0
@@ -604,6 +608,12 @@ public ImmutableMap<K, V> buildOrThrow() {
      * entries are sorted by value. If a key was added more than once, it appears in iteration order
      * based on the first time it was added, again unless {@link #orderEntriesByValue} was called.
      *
+     * <p>In the current implementation, all values associated with a given key are stored in the
+     * {@code Builder} object, even though only one of them will be used in the built map. If there
+     * can be many repeated keys, it may be more space-efficient to use a {@link
+     * java.util.LinkedHashMap LinkedHashMap} and {@link ImmutableMap#copyOf} rather than {@code
+     * ImmutableMap.Builder}.
+     *
      * @since NEXT
      */
     public ImmutableMap<K, V> buildKeepingLast() {
