ForwardingMap
Date: 2016-05-24

com.google.common.collect

## Class ForwardingMap<K,V>

- java.lang.Object
- - com.google.common.collect.ForwardingObject
  - - com.google.common.collect.ForwardingMap<K,V>

- All Implemented Interfaces:
    java.util.Map<K,V>
  Direct Known Subclasses:
    EnumBiMap, EnumHashBiMap, ForwardingConcurrentMap, ForwardingNavigableMap.StandardDescendingMap, ForwardingSortedMap, ImmutableClassToInstanceMap, ImmutableTypeToInstanceMap, MutableClassToInstanceMap, MutableTypeToInstanceMap

      @GwtCompatible
      public abstract class ForwardingMap<K,V>
      extends ForwardingObject
      implements java.util.Map<K,V>

  A map which forwards all its method calls to another map. Subclasses should override one or more methods to modify the behavior of the backing map as desired per the decorator pattern.

  Warning: The methods of `ForwardingMap` forward indiscriminately to the methods of the delegate. For example, overriding `put(K, V)` alone will not change the behavior of `putAll(java.util.Map<? extends K, ? extends V>)`, which can lead to unexpected behavior. In this case, you should override `putAll` as well, either providing your own implementation, or delegating to the provided `standardPutAll` method.

  Each of the `standard` methods, where appropriate, use `Objects.equal(java.lang.Object, java.lang.Object)` to test equality for both keys and values. This may not be the desired behavior for map implementations that use non-standard notions of key equality, such as a `SortedMap` whose comparator is not consistent with `equals`.

  The `standard` methods and the collection views they return are not guaranteed to be thread-safe, even when all of the methods that they depend on are thread-safe.

  Since:
    2.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected class` | `ForwardingMap.StandardEntrySet` A sensible implementation of `Map.entrySet()` in terms of the following methods: `clear()`, `containsKey(java.lang.Object)`, `get(java.lang.Object)`, `isEmpty()`, `remove(java.lang.Object)`, and `size()`.
    `protected class` | `ForwardingMap.StandardKeySet` A sensible implementation of `Map.keySet()` in terms of the following methods: `clear()`, `containsKey(java.lang.Object)`, `isEmpty()`, `remove(java.lang.Object)`, `size()`, and the `Set.iterator()` method of `entrySet()`.
    `protected class` | `ForwardingMap.StandardValues` A sensible implementation of `Map.values()` in terms of the following methods: `clear()`, `containsValue(java.lang.Object)`, `isEmpty()`, `size()`, and the `Set.iterator()` method of `entrySet()`.

    - ### Nested classes/interfaces inherited from interface java.util.Map

      `java.util.Map.Entry<K,V>`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `ForwardingMap()` Constructor for use by subclasses.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()`
    `boolean` | `containsKey(java.lang.Object key)`
    `boolean` | `containsValue(java.lang.Object value)`
    `protected abstract java.util.Map<K,V>` | `delegate()` Returns the backing delegate instance that methods are forwarded to.
    `java.util.Set<java.util.Map.Entry<K,V>>` | `entrySet()`
    `boolean` | `equals(java.lang.Object object)`
    `V` | `get(java.lang.Object key)`
    `int` | `hashCode()`
    `boolean` | `isEmpty()`
    `java.util.Set<K>` | `keySet()`
    `V` | `put(K key, V value)`
    `void` | `putAll(java.util.Map<? extends K,? extends V> map)`
    `V` | `remove(java.lang.Object object)`
    `int` | `size()`
    `protected void` | `standardClear()` A sensible definition of `clear()` in terms of the `iterator` method of `entrySet()`.
    `protected boolean` | `standardContainsKey(java.lang.Object key)` A sensible, albeit inefficient, definition of `containsKey(java.lang.Object)` in terms of the `iterator` method of `entrySet()`.
    `protected boolean` | `standardContainsValue(java.lang.Object value)` A sensible definition of `containsValue(java.lang.Object)` in terms of the `iterator` method of `entrySet()`.
    `protected boolean` | `standardEquals(java.lang.Object object)` A sensible definition of `equals(java.lang.Object)` in terms of the `equals` method of `entrySet()`.
    `protected int` | `standardHashCode()` A sensible definition of `hashCode()` in terms of the `iterator` method of `entrySet()`.
    `protected boolean` | `standardIsEmpty()` A sensible definition of `isEmpty()` in terms of the `iterator` method of `entrySet()`.
    `protected void` | `standardPutAll(java.util.Map<? extends K,? extends V> map)` A sensible definition of `putAll(Map)` in terms of `put(Object, Object)`.
    `protected V` | `standardRemove(java.lang.Object key)` A sensible, albeit inefficient, definition of `remove(java.lang.Object)` in terms of the `iterator` method of `entrySet()`.
    `protected java.lang.String` | `standardToString()` A sensible definition of `ForwardingObject.toString()` in terms of the `iterator` method of `entrySet()`.
    `java.util.Collection<V>` | `values()`

    - ### Methods inherited from class com.google.common.collect.ForwardingObject

      `toString`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### ForwardingMap

          protected ForwardingMap()

      Constructor for use by subclasses.

  - ### Method Detail

    - #### delegate

          protected abstract java.util.Map<K,V> delegate()

      Description copied from class: `ForwardingObject`
      Returns the backing delegate instance that methods are forwarded to. Abstract subclasses generally override this method with an abstract method that has a more specific return type, such as `ForwardingSet.delegate()`. Concrete subclasses override this method to supply the instance being decorated.
      Specified by:
        `delegate` in class `ForwardingObject`

    - #### size

          public int size()

      Specified by:
        `size` in interface `java.util.Map<K,V>`

    - #### isEmpty

          public boolean isEmpty()

      Specified by:
        `isEmpty` in interface `java.util.Map<K,V>`

    - #### remove

          public V remove(java.lang.Object object)

      Specified by:
        `remove` in interface `java.util.Map<K,V>`

    - #### clear

          public void clear()

      Specified by:
        `clear` in interface `java.util.Map<K,V>`

    - #### containsKey

          public boolean containsKey(@Nullable
                            java.lang.Object key)

      Specified by:
        `containsKey` in interface `java.util.Map<K,V>`

    - #### containsValue

          public boolean containsValue(@Nullable
                              java.lang.Object value)

      Specified by:
        `containsValue` in interface `java.util.Map<K,V>`

    - #### get

          public V get(@Nullable
              java.lang.Object key)

      Specified by:
        `get` in interface `java.util.Map<K,V>`

    - #### put

          public V put(K key,
              V value)

      Specified by:
        `put` in interface `java.util.Map<K,V>`

    - #### putAll

          public void putAll(java.util.Map<? extends K,? extends V> map)

      Specified by:
        `putAll` in interface `java.util.Map<K,V>`

    - #### keySet

          public java.util.Set<K> keySet()

      Specified by:
        `keySet` in interface `java.util.Map<K,V>`

    - #### values

          public java.util.Collection<V> values()

      Specified by:
        `values` in interface `java.util.Map<K,V>`

    - #### entrySet

          public java.util.Set<java.util.Map.Entry<K,V>> entrySet()

      Specified by:
        `entrySet` in interface `java.util.Map<K,V>`

    - #### equals

          public boolean equals(@Nullable
                       java.lang.Object object)

      Specified by:
        `equals` in interface `java.util.Map<K,V>`
      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Specified by:
        `hashCode` in interface `java.util.Map<K,V>`
      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### standardPutAll

          protected void standardPutAll(java.util.Map<? extends K,? extends V> map)

      A sensible definition of `putAll(Map)` in terms of `put(Object, Object)`. If you override `put(Object, Object)`, you may wish to override `putAll(Map)` to forward to this implementation.
      Since:
        7.0

    - #### standardRemove

          @Beta
          protected V standardRemove(@Nullable
                              java.lang.Object key)

      A sensible, albeit inefficient, definition of `remove(java.lang.Object)` in terms of the `iterator` method of `entrySet()`. If you override `entrySet()`, you may wish to override `remove(java.lang.Object)` to forward to this implementation.

      Alternately, you may wish to override `remove(java.lang.Object)` with `keySet().remove`, assuming that approach would not lead to an infinite loop.

      Since:
        7.0

    - #### standardClear

          protected void standardClear()

      A sensible definition of `clear()` in terms of the `iterator` method of `entrySet()`. In many cases, you may wish to override `clear()` to forward to this implementation.
      Since:
        7.0

    - #### standardContainsKey

          @Beta
          protected boolean standardContainsKey(@Nullable
                                         java.lang.Object key)

      A sensible, albeit inefficient, definition of `containsKey(java.lang.Object)` in terms of the `iterator` method of `entrySet()`. If you override `entrySet()`, you may wish to override `containsKey(java.lang.Object)` to forward to this implementation.
      Since:
        7.0

    - #### standardContainsValue

          protected boolean standardContainsValue(@Nullable
                                      java.lang.Object value)

      A sensible definition of `containsValue(java.lang.Object)` in terms of the `iterator` method of `entrySet()`. If you override `entrySet()`, you may wish to override `containsValue(java.lang.Object)` to forward to this implementation.
      Since:
        7.0

    - #### standardIsEmpty

          protected boolean standardIsEmpty()

      A sensible definition of `isEmpty()` in terms of the `iterator` method of `entrySet()`. If you override `entrySet()`, you may wish to override `isEmpty()` to forward to this implementation.
      Since:
        7.0

    - #### standardEquals

          protected boolean standardEquals(@Nullable
                               java.lang.Object object)

      A sensible definition of `equals(java.lang.Object)` in terms of the `equals` method of `entrySet()`. If you override `entrySet()`, you may wish to override `equals(java.lang.Object)` to forward to this implementation.
      Since:
        7.0

    - #### standardHashCode

          protected int standardHashCode()

      A sensible definition of `hashCode()` in terms of the `iterator` method of `entrySet()`. If you override `entrySet()`, you may wish to override `hashCode()` to forward to this implementation.
      Since:
        7.0

    - #### standardToString

          protected java.lang.String standardToString()

      A sensible definition of `ForwardingObject.toString()` in terms of the `iterator` method of `entrySet()`. If you override `entrySet()`, you may wish to override `ForwardingObject.toString()` to forward to this implementation.
      Since:
        7.0