Summary

Implement remove(Object, Object) and replace(Object, Object, Object) in IdentityHashMap so they only remove existing mappings if the values match by identity.

Problem

IdentityHashMap's class specification says "This class [uses] reference-equality in place of object-equality when comparing keys (and values)", but it does not compare values by reference equality in the remove(Object, Object) and replace(Object, Object, Object) methods.

Solution

Explicitly implement remove and replace to compare values by == instead of object equality, and document this behavior.

Specification

Specifications of newly overridden methods are shown below. In addition, various changes have been made elsewhere in the IdentityHashMap class to clarify where object reference equality is used. See attached specdiff for full changes.

    /**
     * {@inheritDoc}
     *
     * <p>More formally, if this map contains a mapping from a key
     * {@code k} to a value {@code v} such that {@code (key == k)}
     * and {@code (value == v)}, then this method removes the mapping
     * for this key and returns {@code true}; otherwise it returns
     * {@code false}.
     */
    @Override
    public boolean remove(Object key, Object value) ...

    /**
     * {@inheritDoc}
     *
     * <p>More formally, if this map contains a mapping from a key
     * {@code k} to a value {@code v} such that {@code (key == k)}
     * and {@code (oldValue == v)}, then this method associates
     * {@code k} with {@code newValue} and returns {@code true};
     * otherwise it returns {@code false}.
     */
    @Override
    public boolean replace(K key, V oldValue, V newValue) ...