Java's HashMap key replacement when storing existing value

Question

According to Java HashMap documentation, put method replaces the previously contained value (if any): https://docs.oracle.com/javase/8/docs/api/java/util/HashMap.html#put-K-V-

Associates the specified value with the specified key in this map. If the map previously contained a mapping for the key, the old value is replaced.

The documentation however does not say what happens to the (existing) key when a new value is stored. Does the existing key get replaced or not? Or is the result undefined?

Consider the following example:

public class HashMapTest
{

   private static class Key {
      private String value;
      private Boolean b;

      private Key(String value, Boolean b) {
         this.value = value;
         this.b = b;
      }

      @Override
      public int hashCode()
      {
         return value.hashCode();
      }

      @Override
      public boolean equals(Object obj)
      {
         if (obj instanceof Key)
         {
            return value.equals(((Key)obj).value);
         }
         return false;
      }

      @Override
      public String toString()
      {
         return "(" + value.toString() + "-" + b + ")";
      }
   }

   public static void main(String[] arg) {

      Key key1 = new Key("foo", true);
      Key key2 = new Key("foo", false);

      HashMap<Key, Object> map = new HashMap<Key, Object>();
      map.put(key1, 1L);

      System.out.println("Print content of original map:");
      for (Entry<Key, Object> entry : map.entrySet()) {
         System.out.println("> " + entry.getKey() + " -> " + entry.getValue());
      }

      map.put(key2, 2L);

      System.out.println();
      System.out.println("Print content of updated map:");
      for (Entry<Key, Object> entry : map.entrySet()) {
         System.out.println("> " + entry.getKey() + " -> " + entry.getValue());
      }
   }
}

When I execute the following code using Oracle jdk1.8.0_121, the following output is produced:

Print content of original map:
> (foo-true) -> 1

Print content of updated map:
> (foo-true) -> 2

Evidence says that (at least on my PC) the existing key does not get replaced.

Is this the expected/defined behaviour (where is it defined?) or is it just one among all the possible outcomes? Can I count on this behaviour to be consistent across all Java platforms/versions?

Edit: this question is not a duplicate of What happens when a duplicate key is put into a HashMap?. I am asking about the key (i.e. when you use multiple key instances that refer to the same logical key), not about the values.

Answer 1

From looking at the source, it doesn't get replaced, I'm not sure if it's guaranteed by the contract.

if (e != null) { // existing mapping for key
    V oldValue = e.value;
    if (!onlyIfAbsent || oldValue == null)
        e.value = value;
    afterNodeAccess(e);
    return oldValue;
}

It finds the existing mapping and replaces the value, nothing is done with the new key, they should be the same and immutable, so even if a different implementation can replace the key it shouldn't matter.

You can't count on this behavior but you should write your code in a way that it won't matter.

Answer 2

When a new pair is added, the map uses hasCode,equals to check if the key already present in the map. If the key already exists the old value is replaced with a new one. The key itself remains unmodified.

Map<Integer,String> map = new HashMap<>();
map.put(1,"two"); 
System.out.println(map); // {1=two}
map.put(1,"one"); 
System.out.println(map); // {1=one}
map.put(2,"two");
System.out.println(map); // {1=one, 2=two}

There is an issue with your equals and hashCode contract. ke1 and key2 are identical according to your implementation:

@Override
public boolean equals(Object obj)
{
    if (obj instanceof Key)
    {
       return value.equals(((Key)obj).value);
    }
    return false;
}

you need to compare Boolean b as well

Key other = (Key) obj;
return value.equals(other.value) && b.equals(other.b);

The same rule apples to hasCode

@Override
public int hashCode()
{
    return value.hashCode();
}

return value.hashCode() + b.hashCode();

with these changes key1 and key2 are different

System.out.println(key1.equals(key2));

and the output for your map will be

> (foo-true) -> 1
> (foo-false) -> 2

Answer 3

It is not replaced - neither it should. If you know how a HashMap works and what hashCode and equals is (or more precisely how they are used) - the decision of not touching the Key is obvious.

When you put the other Key/Entry in the map for the second time, that key is first look-up in the map - according to hashCode/equals, so according to the map IFF keys have the same hashCode and are equal according to equals they are the same. If so, why replace it? Especially since if it would have been replaced, that might rigger additional operations or at least additional code to not trigger anything else if keys are equal.

Answer 4

Apparently the current HashSet implementation relies on this HashMap behaviour in order to be compliant to the HashSet documentation. With that i mean that when you add a new element in an HashSet the documentation says that if you try to add an element in an HasSet that already contains the element, the HashSet is not changed and so the element is not substituted, In the openjdk8 implementation the HashSet uses an HashMap keys to hold the values and in the HashSet.add method it calls the HashMap.put method to add the value, thus relying on the fact that the put method will not substitute the object

Although this still not a direct specification in the documentation and it's subject to variations in the JRE implementation, it probably provides a stronger assurance that this will probably not change in the future