Map is an object that maps keys to values.

Important properties of a Map

1. A map cannot contain duplicate keys

2. Each key can map to at most one value.

3. Map interface takes the place of the abstract Dictionary class.

4. The order of a map is the order in which the iterators on the map's collection views return their elements.

   • Some map implementations, like the TreeMap class has order guarantees; others, like the HashMap class, do not have order guarantees.

5. Should be careful if mutable objects are used as map keys.

   • The behavior of a map is not specified if the value of an object is changed in a manner that affects equals comparisons while the object is a key in the map.

6. It is not permissible for a map to contain itself as a key.

7. It is permissible for a map to contain itself as a value

   • but extreme caution is advised, as the equals and hashCode methods are no longer well defined on such a map.

8. Map implementation classes generally provide two constructors:

   • a no argument constructor which creates an empty map, and

   • a constructor with a single argument of type Map, which creates a new map with the same key-value mappings as its argument.

9. Methods that modify the map on which they operate, are specified to throw UnsupportedOperationException if this map does not support the operation.

   • These methods may throw an UnsupportedOperationException if the invocation would have no effect on the map. But are not required to,

     • For example, invoking the putAll(Map) method on an unmodifiable map may throw the exception if the supplied map is empty. But is not required to.

10. Implementations of the various Collections Framework interfaces are free to take advantage of the specified behavior of underlying Object methods.

    • According to the contract for  Object.hashCode(), two objects with unequal hash codes cannot be equal.

      • Therefore, implementations are free to implement optimizations whereby the equals invocation is avoided by first comparing the hash codes of the two keys.  

11. Some implementations prohibit null keys and values.

12. Some map operations which perform recursive traversal of the map may fail with an exception for self-referential instances where the map directly or indirectly contains itself.

    • This includes the clone(), equals(), hashCode() and toString() methods.

    • Implementations may optionally handle the self-referential scenario, however most current implementations do not do so.

Map.Entry<K,V> nested static interface

• Map interface has a nested static interface Map.Entry<K,V> that can store a key-value pair and is the underlying storage structure of the Map.

• The Map.entrySet method returns a collection-view of the map, whose elements are of Map.Entry.

  • Behavior of a map entry is undefined if the backing map has been modified after the entry was returned by the iterator, except through the setValue operation on the map entry.

• Map.Entry objects are valid only for the duration of the iteration.

Method Summary

Important methods of Map interface

• clear()

  • Removes all of the mappings from this map (optional operation).

• containsKey(Object key)

  • Returns true if this map contains a mapping for the specified key.

• containsValue(Object value)

  • Returns true if this map maps one or more keys to the specified value.

• entrySet()

  • Returns a Set view of the mappings contained in this map (Set<Map.Entry<K,V>>).

  • Behavior of a map entry is undefined if the backing map has been modified after the entry was returned by the iterator, except through the setValue operation on the map entry.

• equals(Object o)

  • Compares the specified object with this map for equality.

• get(Object key)

  • Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.

• hashCode()

  • Returns the hash code value for this map.

• isEmpty()

  • Returns true if this map contains no key-value mappings.

• keySet()

  • Returns a Set view of the keys contained in this map (Set<K>).

• put(K key, V value)

  • Associates the specified value with the specified key in this map (optional operation).

  • Returns:

    • the previous value associated with key,

      • or null if there was no mapping for key.

        • A null return can also indicate that the map previously associated null with key, if the implementation supports null values.

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

  • Copies all of the mappings from the specified map to this map (optional operation).

  • Returns nothing (void).

• putIfAbsent(K key, V value)

  • If the specified key is not already associated with a value (or is mapped to null) associates it with the given value and returns null, else returns the current value.

  • Returns:

    • the previous value associated with key,

      • or null if there was no mapping for key.

• remove(Object key)

  • Removes the mapping for a key from this map if it is present (optional operation).

• remove(Object key, Object value)

  • Removes the entry for the specified key only if it is currently mapped to the specified value.

  • Returns:

    • true if the value was removed

• replace(K key, V value)

  • Replaces the entry for the specified key only if it is currently mapped to some value.

  • Returns:

    • the previous value associated with key,

      • or null if there was no mapping for key.

• ​replace(K key, V oldValue, V newValue)

  • Replaces the entry for the specified key only if currently mapped to the specified value.

  • Returns:

    • true if the value was replaced

• size()

  • Returns the number of key-value mappings in this map.

• values()

  • Returns a Collection view of the values contained in this map (Collection<V> ).

You can check the oracle documentation (link given in references and notes) for the complete list of methods.