Package 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
  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 extends Object,V extends Object>`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AbstractDualBidiMap()`
  Creates an empty map, initialized 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

  Modifier and Type
  Method
  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 Details

  - ### AbstractDualBidiMap

    protected AbstractDualBidiMap()
    Creates an empty map, initialized 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 Details

  - ### clear

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

  - ### containsKey

    public boolean containsKey(Object key)
    Specified by:
      `containsKey` in interface `Get<K,V>`
    Specified by:
      `containsKey` in interface `Map<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)`

  - ### containsValue

    public boolean containsValue(Object value)
    Specified by:
      `containsValue` in interface `Get<K,V>`
    Specified by:
      `containsValue` in interface `Map<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)`

  - ### 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 bidi map

  - ### 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

  - ### 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

  - ### 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 `Get<K,V>`
    Specified by:
      `entrySet` in interface `Map<K,V>`
    Returns:
      the entrySet view
    See Also:
      - `Map.entrySet()`

  - ### equals

    public boolean equals(Object obj)
    Specified by:
      `equals` in interface `Map<K,V>`
    Overrides:
      `equals` in class `Object`

  - ### get

    public V get(Object key)
    Specified by:
      `get` in interface `Get<K,V>`
    Specified by:
      `get` in interface `Map<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)`

  - ### 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

  - ### hashCode

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

  - ### 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

  - ### isEmpty

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

  - ### 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 `Get<K,V>`
    Specified by:
      `keySet` in interface `Map<K,V>`
    Returns:
      the keySet view
    See Also:
      - `Map.keySet()`

  - ### mapIterator

    public MapIterator<K,V> mapIterator()
    Obtains a `MapIterator` over the map. The iterator implements `AbstractDualBidiMap.BidiMapIterator`. This implementation relies on the entrySet iterator.
    Specified by:
      `mapIterator` in interface `IterableGet<K,V>`
    Returns:
      a map iterator

  - ### 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 `BidiMap<K,V>`
    Specified by:
      `put` in interface `Map<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 `Get<K,V>`
    Specified by:
      `remove` in interface `Map<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)`

  - ### 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

  - ### size

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

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### 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 `BidiMap<K,V>`
    Specified by:
      `values` in interface `Get<K,V>`
    Specified by:
      `values` in interface `Map<K,V>`
    Returns:
      the values view
    See Also:
      - `Map.values()`