Package com.macrofocus.utils

# Class AbstractMap<K,V>

java.lang.Object
com.macrofocus.utils.AbstractMap<K,V>

Type Parameters:
  `K` - the type of keys maintained by this map
  `V` - the type of mapped values

All Implemented Interfaces:
  `Map<K,V>`

Direct Known Subclasses:
  `IndexedTreeMap`

public abstract class AbstractMap<K,V> extends Object implements Map<K,V>
This class provides a skeletal implementation of the `Map` interface, to minimize the effort required to implement this interface.

To implement an unmodifiable map, the programmer needs only to extend this class and provide an implementation for the `entrySet` method, which returns a set-view of the map's mappings. Typically, the returned set will, in turn, be implemented atop `AbstractSet`. This set should not support the `add` or `remove` methods, and its iterator should not support the `remove` method.

To implement a modifiable map, the programmer must additionally override this class's `put` method (which otherwise throws an `UnsupportedOperationException`), and the iterator returned by `entrySet().iterator()` must additionally implement its `remove` method.

The programmer should generally provide a void (no argument) and map constructor, as per the recommendation in the `Map` interface specification.

The documentation for each non-abstract method in this class describes its implementation in detail. Each of these methods may be overridden if the map being implemented admits a more efficient implementation.

This class is a member of the Java Collections Framework.

Since:
  1.2
See Also:
  - `Map`
  - `Collection`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `AbstractMap.SimpleEntry<K,V>`
  An Entry maintaining a key and a value.
  `static class`
  `AbstractMap.SimpleImmutableEntry<K,V>`
  An Entry maintaining an immutable key and value.

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

  `Map.Entry<K,V>`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AbstractMap()`
  Sole constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  `boolean`
  `containsKey(Object key)`
  `boolean`
  `containsValue(Object value)`
  `abstract Set<Map.Entry<K,V>>`
  `entrySet()`
  `boolean`
  `equals(Object o)`
  Compares the specified object with this map for equality.
  `V`
  `get(Object key)`
  `int`
  `hashCode()`
  Returns the hash code value for this map.
  `boolean`
  `isEmpty()`
  `Set<K>`
  `keySet()`
  `V`
  `put(K key, V value)`
  `void`
  `putAll(Map<? extends K,? extends V> m)`
  `V`
  `remove(Object key)`
  `int`
  `size()`
  `String`
  `toString()`
  Returns a string representation of this map.
  `Collection<V>`
  `values()`

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

  - ### AbstractMap

    protected AbstractMap()
    Sole constructor. (For invocation by subclass constructors, typically implicit.)

- ## Method Details

  - ### size

    public int size()

    This implementation returns `entrySet().size()`.

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

  - ### isEmpty

    public boolean isEmpty()

    This implementation returns `size() == 0`.

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

  - ### containsValue

    public boolean containsValue(Object value)

    This implementation iterates over `entrySet()` searching for an entry with the specified value. If such an entry is found, `true` is returned. If the iteration terminates without finding such an entry, `false` is returned. Note that this implementation requires linear time in the size of the map.

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

  - ### containsKey

    public boolean containsKey(Object key)

    This implementation iterates over `entrySet()` searching for an entry with the specified key. If such an entry is found, `true` is returned. If the iteration terminates without finding such an entry, `false` is returned. Note that this implementation requires linear time in the size of the map; many implementations will override this method.

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

  - ### get

    public V get(Object key)

    This implementation iterates over `entrySet()` searching for an entry with the specified key. If such an entry is found, the entry's value is returned. If the iteration terminates without finding such an entry, `null` is returned. Note that this implementation requires linear time in the size of the map; many implementations will override this method.

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

  - ### put

    public V put(K key, V value)

    This implementation always throws an `UnsupportedOperationException`.

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

  - ### remove

    public V remove(Object key)

    This implementation iterates over `entrySet()` searching for an entry with the specified key. If such an entry is found, its value is obtained with its `getValue` operation, the entry is removed from the collection (and the backing map) with the iterator's `remove` operation, and the saved value is returned. If the iteration terminates without finding such an entry, `null` is returned. Note that this implementation requires linear time in the size of the map; many implementations will override this method.

    Note that this implementation throws an `UnsupportedOperationException` if the `entrySet` iterator does not support the `remove` method and this map contains a mapping for the specified key.

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

  - ### putAll

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

    This implementation iterates over the specified map's `entrySet()` collection, and calls this map's `put` operation once for each entry returned by the iteration.

    Note that this implementation throws an `UnsupportedOperationException` if this map does not support the `put` operation and the specified map is nonempty.

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

  - ### clear

    public void clear()

    This implementation calls `entrySet().clear()`.

    Note that this implementation throws an `UnsupportedOperationException` if the `entrySet` does not support the `clear` operation.

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

  - ### keySet

    public Set<K> keySet()

    This implementation returns a set that subclasses `AbstractSet`. The subclass's iterator method returns a "wrapper object" over this map's `entrySet()` iterator. The `size` method delegates to this map's `size` method and the `contains` method delegates to this map's `containsKey` method.

    The set is created the first time this method is called, and returned in response to all subsequent calls. No synchronization is performed, so there is a slight chance that multiple calls to this method will not all return the same set.

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

  - ### values

    public Collection<V> values()

    This implementation returns a collection that subclasses `AbstractCollection`. The subclass's iterator method returns a "wrapper object" over this map's `entrySet()` iterator. The `size` method delegates to this map's `size` method and the `contains` method delegates to this map's `containsValue` method.

    The collection is created the first time this method is called, and returned in response to all subsequent calls. No synchronization is performed, so there is a slight chance that multiple calls to this method will not all return the same collection.

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

  - ### entrySet

    public abstract Set<Map.Entry<K,V>> entrySet()
    Specified by:
      `entrySet` in interface `Map<K,V>`

  - ### equals

    public boolean equals(Object o)
    Compares the specified object with this map for equality. Returns `true` if the given object is also a map and the two maps represent the same mappings. More formally, two maps `m1` and `m2` represent the same mappings if `m1.entrySet().equals(m2.entrySet())`. This ensures that the `equals` method works properly across different implementations of the `Map` interface.

    This implementation first checks if the specified object is this map; if so it returns `true`. Then, it checks if the specified object is a map whose size is identical to the size of this map; if not, it returns `false`. If so, it iterates over this map's `entrySet` collection, and checks that the specified map contains each mapping that this map contains. If the specified map fails to contain such a mapping, `false` is returned. If the iteration completes, `true` is returned.

    Specified by:
      `equals` in interface `Map<K,V>`
    Overrides:
      `equals` in class `Object`
    Parameters:
      `o` - object to be compared for equality with this map
    Returns:
      `true` if the specified object is equal to this map

  - ### hashCode

    public int hashCode()
    Returns the hash code value for this map. The hash code of a map is defined to be the sum of the hash codes of each entry in the map's `entrySet()` view. This ensures that `m1.equals(m2)` implies that `m1.hashCode()==m2.hashCode()` for any two maps `m1` and `m2`, as required by the general contract of `Object.hashCode()`.

    This implementation iterates over `entrySet()`, calling `hashCode()` on each element (entry) in the set, and adding up the results.

    Specified by:
      `hashCode` in interface `Map<K,V>`
    Overrides:
      `hashCode` in class `Object`
    Returns:
      the hash code value for this map
    See Also:
      - `Map.Entry.hashCode()`
      - `Object.equals(Object)`
      - `Set.equals(Object)`

  - ### toString

    public String toString()
    Returns a string representation of this map. The string representation consists of a list of key-value mappings in the order returned by the map's `entrySet` view's iterator, enclosed in braces (`"{}"`). Adjacent mappings are separated by the characters `", "` (comma and space). Each key-value mapping is rendered as the key followed by an equals sign (`"="`) followed by the associated value. Keys and values are converted to strings as by `String.valueOf(Object)`.
    Overrides:
      `toString` in class `Object`
    Returns:
      a string representation of this map