org.apache.commons.collections4.bidimap

## Class AbstractDualBidiMap<K,V>

- java.lang.Object
- - org.apache.commons.collections4.bidimap.AbstractDualBidiMap<K,V>

- Type Parameters:
    `K` - the type of the keys in the map
    `V` - the type of the values in the map
  All Implemented Interfaces:
    Map<K,V>, BidiMap<K,V>, Get<K,V>, IterableGet<K,V>, IterableMap<K,V>, Put<K,V>
  Direct Known Subclasses:
    DualHashBidiMap, DualLinkedHashBidiMap, DualTreeBidiMap

      public abstract class AbstractDualBidiMap<K,V>
      extends Object
      implements BidiMap<K,V>

  Abstract `BidiMap` implemented using two maps.

  An implementation can be written simply by implementing the `createBidiMap(Map, Map, BidiMap)` method.

  Since:
    3.0
  See Also:
    `DualHashBidiMap`, `DualTreeBidiMap`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `AbstractDualBidiMap.BidiMapIterator<K,V>` Inner class MapIterator.
    `protected static class` | `AbstractDualBidiMap.EntrySet<K,V>` Inner class EntrySet.
    `protected static class` | `AbstractDualBidiMap.EntrySetIterator<K,V>` Inner class EntrySetIterator.
    `protected static class` | `AbstractDualBidiMap.KeySet<K>` Inner class KeySet.
    `protected static class` | `AbstractDualBidiMap.KeySetIterator<K>` Inner class KeySetIterator.
    `protected static class` | `AbstractDualBidiMap.MapEntry<K,V>` Inner class MapEntry.
    `protected static class` | `AbstractDualBidiMap.Values<V>` Inner class Values.
    `protected static class` | `AbstractDualBidiMap.ValuesIterator<V>` Inner class ValuesIterator.
    `protected static class` | `AbstractDualBidiMap.View<K,V,E>` Inner class View.

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

      `Map.Entry<K,V>`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractDualBidiMap()` Creates an empty map, initialised by `createMap`.
    `protected` | `AbstractDualBidiMap(Map<K,V> normalMap, Map<V,K> reverseMap)` Creates an empty map using the two maps specified as storage.
    `protected` | `AbstractDualBidiMap(Map<K,V> normalMap, Map<V,K> reverseMap, BidiMap<V,K> inverseBidiMap)` Constructs a map that decorates the specified maps, used by the subclass `createBidiMap` implementation.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()`
    `boolean` | `containsKey(Object key)`
    `boolean` | `containsValue(Object value)`
    `protected abstract BidiMap<V,K>` | `createBidiMap(Map<V,K> normalMap, Map<K,V> reverseMap, BidiMap<K,V> inverseMap)` Creates a new instance of the subclass.
    `protected Iterator<Map.Entry<K,V>>` | `createEntrySetIterator(Iterator<Map.Entry<K,V>> iterator)` Creates an entry set iterator.
    `protected Iterator<K>` | `createKeySetIterator(Iterator<K> iterator)` Creates a key set iterator.
    `protected Iterator<V>` | `createValuesIterator(Iterator<V> iterator)` Creates a values iterator.
    `Set<Map.Entry<K,V>>` | `entrySet()` Gets an entrySet view of the map.
    `boolean` | `equals(Object obj)`
    `V` | `get(Object key)`
    `K` | `getKey(Object value)` Gets the key that is currently mapped to the specified value.
    `int` | `hashCode()`
    `BidiMap<V,K>` | `inverseBidiMap()` Gets a view of this map where the keys and values are reversed.
    `boolean` | `isEmpty()`
    `Set<K>` | `keySet()` Gets a keySet view of the map.
    `MapIterator<K,V>` | `mapIterator()` Obtains a `MapIterator` over the map.
    `V` | `put(K key, V value)` Puts the key-value pair into the map, replacing any previous pair.
    `void` | `putAll(Map<? extends K,? extends V> map)`
    `V` | `remove(Object key)`
    `K` | `removeValue(Object value)` Removes the key-value pair that is currently mapped to the specified value (optional operation).
    `int` | `size()`
    `String` | `toString()`
    `Set<V>` | `values()` Gets a values view of the map.

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

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

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

      `compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll`

- - ### Constructor Detail

    - #### AbstractDualBidiMap

          protected AbstractDualBidiMap()

      Creates an empty map, initialised by `createMap`.

      This constructor remains in place for deserialization. All other usage is deprecated in favour of `AbstractDualBidiMap(Map, Map)`.

    - #### AbstractDualBidiMap

          protected AbstractDualBidiMap(Map<K,V> normalMap,
                                        Map<V,K> reverseMap)

      Creates an empty map using the two maps specified as storage.

      The two maps must be a matching pair, normal and reverse. They will typically both be empty.

      Neither map is validated, so nulls may be passed in. If you choose to do this then the subclass constructor must populate the `maps[]` instance variable itself.

      Parameters:
        `normalMap` - the normal direction map
        `reverseMap` - the reverse direction map
      Since:
        3.1

    - #### AbstractDualBidiMap

          protected AbstractDualBidiMap(Map<K,V> normalMap,
                                        Map<V,K> reverseMap,
                                        BidiMap<V,K> inverseBidiMap)

      Constructs a map that decorates the specified maps, used by the subclass `createBidiMap` implementation.
      Parameters:
        `normalMap` - the normal direction map
        `reverseMap` - the reverse direction map
        `inverseBidiMap` - the inverse BidiMap

  - ### Method Detail

    - #### createBidiMap

          protected abstract BidiMap<V,K> createBidiMap(Map<V,K> normalMap,
                                                        Map<K,V> reverseMap,
                                                        BidiMap<K,V> inverseMap)

      Creates a new instance of the subclass.
      Parameters:
        `normalMap` - the normal direction map
        `reverseMap` - the reverse direction map
        `inverseMap` - this map, which is the inverse in the new map
      Returns:
        the inverse map

    - #### get

          public V get(Object key)

      Specified by:
        `get` in interface `Map<K,V>`
      Specified by:
        `get` in interface `Get<K,V>`
      Parameters:
        `key` - the key whose associated value is to be returned
      Returns:
        the value to which the specified key is mapped, or `null` if this map contains no mapping for the key
      See Also:
        `Map.get(Object)`

    - #### size

          public int size()

      Specified by:
        `size` in interface `Map<K,V>`
      Specified by:
        `size` in interface `Get<K,V>`
      Returns:
        the number of key-value mappings in this map
      See Also:
        `Map.size()`

    - #### isEmpty

          public boolean isEmpty()

      Specified by:
        `isEmpty` in interface `Map<K,V>`
      Specified by:
        `isEmpty` in interface `Get<K,V>`
      Returns:
        `true` if this map contains no key-value mappings
      See Also:
        `Map.isEmpty()`

    - #### containsKey

          public boolean containsKey(Object key)

      Specified by:
        `containsKey` in interface `Map<K,V>`
      Specified by:
        `containsKey` in interface `Get<K,V>`
      Parameters:
        `key` - key whose presence in this map is to be tested
      Returns:
        `true` if this map contains a mapping for the specified key
      See Also:
        `Map.containsKey(Object)`

    - #### equals

          public boolean equals(Object obj)

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

    - #### hashCode

          public int hashCode()

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

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### put

          public V put(K key,
                       V value)

      Description copied from interface: `BidiMap`
      Puts the key-value pair into the map, replacing any previous pair.

      When adding a key-value pair, the value may already exist in the map against a different key. That mapping is removed, to ensure that the value only occurs once in the inverse map.

            BidiMap map1 = new DualHashBidiMap();
            map.put("A","B");  // contains A mapped to B, as per Map
            map.put("A","C");  // contains A mapped to C, as per Map

            BidiMap map2 = new DualHashBidiMap();
            map.put("A","B");  // contains A mapped to B, as per Map
            map.put("C","B");  // contains C mapped to B, key A is removed

      Specified by:
        `put` in interface `Map<K,V>`
      Specified by:
        `put` in interface `BidiMap<K,V>`
      Specified by:
        `put` in interface `Put<K,V>`
      Parameters:
        `key` - the key to store
        `value` - the value to store
      Returns:
        the previous value mapped to this key
      See Also:
        `Map.put(Object, Object)`

    - #### putAll

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

      Specified by:
        `putAll` in interface `Map<K,V>`
      Specified by:
        `putAll` in interface `Put<K,V>`
      Parameters:
        `map` - mappings to be stored in this map
      See Also:
        `Map.putAll(Map)`

    - #### remove

          public V remove(Object key)

      Specified by:
        `remove` in interface `Map<K,V>`
      Specified by:
        `remove` in interface `Get<K,V>`
      Parameters:
        `key` - key whose mapping is to be removed from the map
      Returns:
        the previous value associated with `key`, or `null` if there was no mapping for `key`.
      See Also:
        `Map.remove(Object)`

    - #### clear

          public void clear()

      Specified by:
        `clear` in interface `Map<K,V>`
      Specified by:
        `clear` in interface `Put<K,V>`
      See Also:
        `Map.clear()`

    - #### containsValue

          public boolean containsValue(Object value)

      Specified by:
        `containsValue` in interface `Map<K,V>`
      Specified by:
        `containsValue` in interface `Get<K,V>`
      Parameters:
        `value` - value whose presence in this map is to be tested
      Returns:
        `true` if this map maps one or more keys to the specified value
      See Also:
        `Map.containsValue(Object)`

    - #### mapIterator

          public MapIterator<K,V> mapIterator()

      Obtains a `MapIterator` over the map. The iterator implements `ResetableMapIterator`. This implementation relies on the entrySet iterator.

      The setValue() methods only allow a new value to be set. If the value being set is already in the map, an IllegalArgumentException is thrown (as setValue cannot change the size of the map).

      Specified by:
        `mapIterator` in interface `IterableGet<K,V>`
      Returns:
        a map iterator

    - #### getKey

          public K getKey(Object value)

      Description copied from interface: `BidiMap`
      Gets the key that is currently mapped to the specified value.

      If the value is not contained in the map, `null` is returned.

      Implementations should seek to make this method perform equally as well as `get(Object)`.

      Specified by:
        `getKey` in interface `BidiMap<K,V>`
      Parameters:
        `value` - the value to find the key for
      Returns:
        the mapped key, or `null` if not found

    - #### removeValue

          public K removeValue(Object value)

      Description copied from interface: `BidiMap`
      Removes the key-value pair that is currently mapped to the specified value (optional operation).

      If the value is not contained in the map, `null` is returned.

      Implementations should seek to make this method perform equally as well as `remove(Object)`.

      Specified by:
        `removeValue` in interface `BidiMap<K,V>`
      Parameters:
        `value` - the value to find the key-value pair for
      Returns:
        the key that was removed, `null` if nothing removed

    - #### inverseBidiMap

          public BidiMap<V,K> inverseBidiMap()

      Description copied from interface: `BidiMap`
      Gets a view of this map where the keys and values are reversed.

      Changes to one map will be visible in the other and vice versa. This enables both directions of the map to be accessed as a `Map`.

      Implementations should seek to avoid creating a new object every time this method is called. See `AbstractMap.values()` etc. Calling this method on the inverse map should return the original.

      Specified by:
        `inverseBidiMap` in interface `BidiMap<K,V>`
      Returns:
        an inverted bidirectional map

    - #### keySet

          public Set<K> keySet()

      Gets a keySet view of the map. Changes made on the view are reflected in the map. The set supports remove and clear but not add.
      Specified by:
        `keySet` in interface `Map<K,V>`
      Specified by:
        `keySet` in interface `Get<K,V>`
      Returns:
        the keySet view
      See Also:
        `Map.keySet()`

    - #### createKeySetIterator

          protected Iterator<K> createKeySetIterator(Iterator<K> iterator)

      Creates a key set iterator. Subclasses can override this to return iterators with different properties.
      Parameters:
        `iterator` - the iterator to decorate
      Returns:
        the keySet iterator

    - #### values

          public Set<V> values()

      Gets a values view of the map. Changes made on the view are reflected in the map. The set supports remove and clear but not add.
      Specified by:
        `values` in interface `Map<K,V>`
      Specified by:
        `values` in interface `BidiMap<K,V>`
      Specified by:
        `values` in interface `Get<K,V>`
      Returns:
        the values view
      See Also:
        `Map.values()`

    - #### createValuesIterator

          protected Iterator<V> createValuesIterator(Iterator<V> iterator)

      Creates a values iterator. Subclasses can override this to return iterators with different properties.
      Parameters:
        `iterator` - the iterator to decorate
      Returns:
        the values iterator

    - #### entrySet

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

      Gets an entrySet view of the map. Changes made on the set are reflected in the map. The set supports remove and clear but not add.

      The Map Entry setValue() method only allow a new value to be set. If the value being set is already in the map, an IllegalArgumentException is thrown (as setValue cannot change the size of the map).

      Specified by:
        `entrySet` in interface `Map<K,V>`
      Specified by:
        `entrySet` in interface `Get<K,V>`
      Returns:
        the entrySet view
      See Also:
        `Map.entrySet()`

    - #### createEntrySetIterator

          protected Iterator<Map.Entry<K,V>> createEntrySetIterator(Iterator<Map.Entry<K,V>> iterator)

      Creates an entry set iterator. Subclasses can override this to return iterators with different properties.
      Parameters:
        `iterator` - the iterator to decorate
      Returns:
        the entrySet iterator

Copyright © 2001–2019 The Apache Software Foundation. All rights reserved.