ForwardingNavigableMap
Date: 2016-05-24

com.google.common.collect

## Class ForwardingNavigableMap<K,V>

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

- All Implemented Interfaces:
    java.util.Map<K,V>, java.util.NavigableMap<K,V>, java.util.SortedMap<K,V>

      public abstract class ForwardingNavigableMap<K,V>
      extends ForwardingSortedMap<K,V>
      implements java.util.NavigableMap<K,V>

  A navigable map which forwards all its method calls to another navigable 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 `ForwardingNavigableMap` forward indiscriminately to the methods of the delegate. For example, overriding `ForwardingMap.put(K, V)` alone will not change the behavior of `ForwardingMap.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 uses the map's comparator (or the natural ordering of the elements, if there is no comparator) to test element equality. As a result, if the comparator is not consistent with equals, some of the standard implementations may violate the `Map` contract.

  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:
    12.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected class` | `ForwardingNavigableMap.StandardDescendingMap` A sensible implementation of `NavigableMap.descendingMap()` in terms of the methods of this `NavigableMap`.
    `protected class` | `ForwardingNavigableMap.StandardNavigableKeySet` A sensible implementation of `NavigableMap.navigableKeySet()` in terms of the methods of this `NavigableMap`.

    - ### Nested classes/interfaces inherited from class com.google.common.collect.ForwardingSortedMap

      `ForwardingSortedMap.StandardKeySet`

    - ### Nested classes/interfaces inherited from class com.google.common.collect.ForwardingMap

      `ForwardingMap.StandardEntrySet, ForwardingMap.StandardValues`

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

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

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.Map.Entry<K,V>` | `ceilingEntry(K key)`
    `K` | `ceilingKey(K key)`
    `protected abstract java.util.NavigableMap<K,V>` | `delegate()` Returns the backing delegate instance that methods are forwarded to.
    `java.util.NavigableSet<K>` | `descendingKeySet()`
    `java.util.NavigableMap<K,V>` | `descendingMap()`
    `java.util.Map.Entry<K,V>` | `firstEntry()`
    `java.util.Map.Entry<K,V>` | `floorEntry(K key)`
    `K` | `floorKey(K key)`
    `java.util.NavigableMap<K,V>` | `headMap(K toKey, boolean inclusive)`
    `java.util.Map.Entry<K,V>` | `higherEntry(K key)`
    `K` | `higherKey(K key)`
    `java.util.Map.Entry<K,V>` | `lastEntry()`
    `java.util.Map.Entry<K,V>` | `lowerEntry(K key)`
    `K` | `lowerKey(K key)`
    `java.util.NavigableSet<K>` | `navigableKeySet()`
    `java.util.Map.Entry<K,V>` | `pollFirstEntry()`
    `java.util.Map.Entry<K,V>` | `pollLastEntry()`
    `protected java.util.Map.Entry<K,V>` | `standardCeilingEntry(K key)` A sensible definition of `ceilingEntry(K)` in terms of the `firstEntry()` of `tailMap(Object, boolean)`.
    `protected K` | `standardCeilingKey(K key)` A sensible definition of `ceilingKey(K)` in terms of `ceilingEntry`.
    `protected java.util.NavigableSet<K>` | `standardDescendingKeySet()` A sensible definition of `descendingKeySet()` as the `navigableKeySet` of `descendingMap()`.
    `protected java.util.Map.Entry<K,V>` | `standardFirstEntry()` A sensible definition of `firstEntry()` in terms of the `iterator()` of `ForwardingMap.entrySet()`.
    `protected K` | `standardFirstKey()` A sensible definition of `ForwardingSortedMap.firstKey()` in terms of `firstEntry`.
    `protected java.util.Map.Entry<K,V>` | `standardFloorEntry(K key)` A sensible definition of `floorEntry(K)` in terms of the `lastEntry()` of `headMap(Object, boolean)`.
    `protected K` | `standardFloorKey(K key)` A sensible definition of `floorKey(K)` in terms of `floorEntry`.
    `protected java.util.SortedMap<K,V>` | `standardHeadMap(K toKey)` A sensible definition of `ForwardingSortedMap.headMap(Object)` in terms of `headMap(Object, boolean)`.
    `protected java.util.Map.Entry<K,V>` | `standardHigherEntry(K key)` A sensible definition of `higherEntry(K)` in terms of the `firstEntry()` of `tailMap(Object, boolean)`.
    `protected K` | `standardHigherKey(K key)` A sensible definition of `higherKey(K)` in terms of `higherEntry`.
    `protected java.util.Map.Entry<K,V>` | `standardLastEntry()` A sensible definition of `lastEntry()` in terms of the `iterator()` of the `ForwardingMap.entrySet()` of `descendingMap()`.
    `protected K` | `standardLastKey()` A sensible definition of `ForwardingSortedMap.lastKey()` in terms of `lastEntry`.
    `protected java.util.Map.Entry<K,V>` | `standardLowerEntry(K key)` A sensible definition of `lowerEntry(K)` in terms of the `lastEntry()` of `headMap(Object, boolean)`.
    `protected K` | `standardLowerKey(K key)` A sensible definition of `lowerKey(K)` in terms of `lowerEntry`.
    `protected java.util.Map.Entry<K,V>` | `standardPollFirstEntry()` A sensible definition of `pollFirstEntry()` in terms of the `iterator` of `entrySet`.
    `protected java.util.Map.Entry<K,V>` | `standardPollLastEntry()` A sensible definition of `pollFirstEntry()` in terms of the `iterator` of the `entrySet` of `descendingMap`.
    `protected java.util.SortedMap<K,V>` | `standardSubMap(K fromKey, K toKey)` A sensible definition of `ForwardingSortedMap.subMap(Object, Object)` in terms of `subMap(Object, boolean, Object, boolean)`.
    `protected java.util.SortedMap<K,V>` | `standardTailMap(K fromKey)` A sensible definition of `ForwardingSortedMap.tailMap(Object)` in terms of `tailMap(Object, boolean)`.
    `java.util.NavigableMap<K,V>` | `subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)`
    `java.util.NavigableMap<K,V>` | `tailMap(K fromKey, boolean inclusive)`

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

      `comparator, firstKey, headMap, lastKey, standardContainsKey, subMap, tailMap`

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

      `clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, standardClear, standardContainsValue, standardEquals, standardHashCode, standardIsEmpty, standardPutAll, standardRemove, standardToString, 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`

    - ### Methods inherited from interface java.util.NavigableMap

      `headMap, subMap, tailMap`

    - ### Methods inherited from interface java.util.SortedMap

      `comparator, entrySet, firstKey, keySet, lastKey, values`

    - ### Methods inherited from interface java.util.Map

      `clear, containsKey, containsValue, equals, get, hashCode, isEmpty, put, putAll, remove, size`

- - ### Constructor Detail

    - #### ForwardingNavigableMap

          protected ForwardingNavigableMap()

      Constructor for use by subclasses.

  - ### Method Detail

    - #### delegate

          protected abstract java.util.NavigableMap<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 `ForwardingSortedMap<K,V>`

    - #### lowerEntry

          public java.util.Map.Entry<K,V> lowerEntry(K key)

      Specified by:
        `lowerEntry` in interface `java.util.NavigableMap<K,V>`

    - #### standardLowerEntry

          protected java.util.Map.Entry<K,V> standardLowerEntry(K key)

      A sensible definition of `lowerEntry(K)` in terms of the `lastEntry()` of `headMap(Object, boolean)`. If you override `headMap`, you may wish to override `lowerEntry` to forward to this implementation.

    - #### lowerKey

          public K lowerKey(K key)

      Specified by:
        `lowerKey` in interface `java.util.NavigableMap<K,V>`

    - #### standardLowerKey

          protected K standardLowerKey(K key)

      A sensible definition of `lowerKey(K)` in terms of `lowerEntry`. If you override `lowerEntry(K)`, you may wish to override `lowerKey` to forward to this implementation.

    - #### floorEntry

          public java.util.Map.Entry<K,V> floorEntry(K key)

      Specified by:
        `floorEntry` in interface `java.util.NavigableMap<K,V>`

    - #### standardFloorEntry

          protected java.util.Map.Entry<K,V> standardFloorEntry(K key)

      A sensible definition of `floorEntry(K)` in terms of the `lastEntry()` of `headMap(Object, boolean)`. If you override `headMap`, you may wish to override `floorEntry` to forward to this implementation.

    - #### floorKey

          public K floorKey(K key)

      Specified by:
        `floorKey` in interface `java.util.NavigableMap<K,V>`

    - #### standardFloorKey

          protected K standardFloorKey(K key)

      A sensible definition of `floorKey(K)` in terms of `floorEntry`. If you override `floorEntry`, you may wish to override `floorKey` to forward to this implementation.

    - #### ceilingEntry

          public java.util.Map.Entry<K,V> ceilingEntry(K key)

      Specified by:
        `ceilingEntry` in interface `java.util.NavigableMap<K,V>`

    - #### standardCeilingEntry

          protected java.util.Map.Entry<K,V> standardCeilingEntry(K key)

      A sensible definition of `ceilingEntry(K)` in terms of the `firstEntry()` of `tailMap(Object, boolean)`. If you override `tailMap`, you may wish to override `ceilingEntry` to forward to this implementation.

    - #### ceilingKey

          public K ceilingKey(K key)

      Specified by:
        `ceilingKey` in interface `java.util.NavigableMap<K,V>`

    - #### standardCeilingKey

          protected K standardCeilingKey(K key)

      A sensible definition of `ceilingKey(K)` in terms of `ceilingEntry`. If you override `ceilingEntry`, you may wish to override `ceilingKey` to forward to this implementation.

    - #### higherEntry

          public java.util.Map.Entry<K,V> higherEntry(K key)

      Specified by:
        `higherEntry` in interface `java.util.NavigableMap<K,V>`

    - #### standardHigherEntry

          protected java.util.Map.Entry<K,V> standardHigherEntry(K key)

      A sensible definition of `higherEntry(K)` in terms of the `firstEntry()` of `tailMap(Object, boolean)`. If you override `tailMap`, you may wish to override `higherEntry` to forward to this implementation.

    - #### higherKey

          public K higherKey(K key)

      Specified by:
        `higherKey` in interface `java.util.NavigableMap<K,V>`

    - #### standardHigherKey

          protected K standardHigherKey(K key)

      A sensible definition of `higherKey(K)` in terms of `higherEntry`. If you override `higherEntry`, you may wish to override `higherKey` to forward to this implementation.

    - #### firstEntry

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

      Specified by:
        `firstEntry` in interface `java.util.NavigableMap<K,V>`

    - #### standardFirstEntry

          protected java.util.Map.Entry<K,V> standardFirstEntry()

      A sensible definition of `firstEntry()` in terms of the `iterator()` of `ForwardingMap.entrySet()`. If you override `entrySet`, you may wish to override `firstEntry` to forward to this implementation.

    - #### standardFirstKey

          protected K standardFirstKey()

      A sensible definition of `ForwardingSortedMap.firstKey()` in terms of `firstEntry`. If you override `firstEntry`, you may wish to override `firstKey` to forward to this implementation.

    - #### lastEntry

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

      Specified by:
        `lastEntry` in interface `java.util.NavigableMap<K,V>`

    - #### standardLastEntry

          protected java.util.Map.Entry<K,V> standardLastEntry()

      A sensible definition of `lastEntry()` in terms of the `iterator()` of the `ForwardingMap.entrySet()` of `descendingMap()`. If you override `descendingMap`, you may wish to override `lastEntry` to forward to this implementation.

    - #### standardLastKey

          protected K standardLastKey()

      A sensible definition of `ForwardingSortedMap.lastKey()` in terms of `lastEntry`. If you override `lastEntry`, you may wish to override `lastKey` to forward to this implementation.

    - #### pollFirstEntry

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

      Specified by:
        `pollFirstEntry` in interface `java.util.NavigableMap<K,V>`

    - #### standardPollFirstEntry

          protected java.util.Map.Entry<K,V> standardPollFirstEntry()

      A sensible definition of `pollFirstEntry()` in terms of the `iterator` of `entrySet`. If you override `entrySet`, you may wish to override `pollFirstEntry` to forward to this implementation.

    - #### pollLastEntry

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

      Specified by:
        `pollLastEntry` in interface `java.util.NavigableMap<K,V>`

    - #### standardPollLastEntry

          protected java.util.Map.Entry<K,V> standardPollLastEntry()

      A sensible definition of `pollFirstEntry()` in terms of the `iterator` of the `entrySet` of `descendingMap`. If you override `descendingMap`, you may wish to override `pollFirstEntry` to forward to this implementation.

    - #### descendingMap

          public java.util.NavigableMap<K,V> descendingMap()

      Specified by:
        `descendingMap` in interface `java.util.NavigableMap<K,V>`

    - #### navigableKeySet

          public java.util.NavigableSet<K> navigableKeySet()

      Specified by:
        `navigableKeySet` in interface `java.util.NavigableMap<K,V>`

    - #### descendingKeySet

          public java.util.NavigableSet<K> descendingKeySet()

      Specified by:
        `descendingKeySet` in interface `java.util.NavigableMap<K,V>`

    - #### standardDescendingKeySet

          @Beta
          protected java.util.NavigableSet<K> standardDescendingKeySet()

      A sensible definition of `descendingKeySet()` as the `navigableKeySet` of `descendingMap()`. (The `ForwardingNavigableMap.StandardDescendingMap` implementation implements `navigableKeySet` on its own, so as not to cause an infinite loop.) If you override `descendingMap`, you may wish to override `descendingKeySet` to forward to this implementation.

    - #### standardSubMap

          protected java.util.SortedMap<K,V> standardSubMap(K fromKey,
                                                K toKey)

      A sensible definition of `ForwardingSortedMap.subMap(Object, Object)` in terms of `subMap(Object, boolean, Object, boolean)`. If you override `subMap(K, boolean, K, boolean)`, you may wish to override `subMap` to forward to this implementation.
      Overrides:
        `standardSubMap` in class `ForwardingSortedMap<K,V>`

    - #### subMap

          public java.util.NavigableMap<K,V> subMap(K fromKey,
                                           boolean fromInclusive,
                                           K toKey,
                                           boolean toInclusive)

      Specified by:
        `subMap` in interface `java.util.NavigableMap<K,V>`

    - #### headMap

          public java.util.NavigableMap<K,V> headMap(K toKey,
                                            boolean inclusive)

      Specified by:
        `headMap` in interface `java.util.NavigableMap<K,V>`

    - #### tailMap

          public java.util.NavigableMap<K,V> tailMap(K fromKey,
                                            boolean inclusive)

      Specified by:
        `tailMap` in interface `java.util.NavigableMap<K,V>`

    - #### standardHeadMap

          protected java.util.SortedMap<K,V> standardHeadMap(K toKey)

      A sensible definition of `ForwardingSortedMap.headMap(Object)` in terms of `headMap(Object, boolean)`. If you override `headMap(K, boolean)`, you may wish to override `headMap` to forward to this implementation.

    - #### standardTailMap

          protected java.util.SortedMap<K,V> standardTailMap(K fromKey)

      A sensible definition of `ForwardingSortedMap.tailMap(Object)` in terms of `tailMap(Object, boolean)`. If you override `tailMap(K, boolean)`, you may wish to override `tailMap` to forward to this implementation.