IdentityHashMap in Java: Reference Equality, Internals & Real Use Cases

import java.util.IdentityHashMap;
import java.util.Map;

public class IdentityHashMapInternals {

    public static void main(String[] args) {

        // Two String objects with IDENTICAL content but different references.
        // 'new String(...)' deliberately bypasses the string pool so we get
        // two physically separate objects in the heap.
        String keyA = new String("session");
        String keyB = new String("session");

        System.out.println("--- Equality checks ---");
        System.out.println("keyA.equals(keyB) : " + keyA.equals(keyB));  // true  — same content
        System.out.println("keyA == keyB       : " + (keyA == keyB));    // false — different objects
        System.out.println("identityHashCode A : " + System.identityHashCode(keyA));
        System.out.println("identityHashCode B : " + System.identityHashCode(keyB));

        // ------- IdentityHashMap behaviour -------
        IdentityHashMap<String, String> identityMap = new IdentityHashMap<>();

        identityMap.put(keyA, "value-for-A");
        identityMap.put(keyB, "value-for-B");  // keyB != keyA by ==, so this is a SECOND entry

        // Two entries exist even though the keys look identical!
        System.out.println("\n--- IdentityHashMap ---");
        System.out.println("Size (expect 2) : " + identityMap.size());
        System.out.println("Get with keyA   : " + identityMap.get(keyA));  // value-for-A
        System.out.println("Get with keyB   : " + identityMap.get(keyB));  // value-for-B

        // ------- HashMap behaviour for contrast -------
        Map<String, String> hashMap = new java.util.HashMap<>();

        hashMap.put(keyA, "value-for-A");
        hashMap.put(keyB, "value-for-B");  // keyB.equals(keyA) == true, so this OVERWRITES

        System.out.println("\n--- HashMap (for comparison) ---");
        System.out.println("Size (expect 1) : " + hashMap.size());  // only 1 entry survives
        System.out.println("Get with keyA   : " + hashMap.get(keyA)); // value-for-B (overwritten)
        System.out.println("Get with keyB   : " + hashMap.get(keyB)); // value-for-B
    }
}

import java.util.IdentityHashMap;
import java.util.ArrayList;
import java.util.List;

/**
 * Demonstrates IdentityHashMap as a 'visited' tracker during
 * recursive object graph traversal. This is the pattern Java's
 * own serialization engine uses internally.
 */
public class ObjectGraphVisitor {

    // A simple node that deliberately overrides equals() by content.
    // This is the key: two nodes with the same label are 'equal' by value
    // but may be two physically separate objects in a cyclic graph.
    static class GraphNode {
        String label;
        List<GraphNode> neighbours = new ArrayList<>();

        GraphNode(String label) { this.label = label; }

        // equals() and hashCode() are based on label content — NOT reference
        @Override public boolean equals(Object other) {
            if (!(other instanceof GraphNode)) return false;
            return this.label.equals(((GraphNode) other).label);
        }
        @Override public int hashCode() { return label.hashCode(); }
        @Override public String toString() { return "Node(" + label + ")"; }
    }

    // IdentityHashMap as a visited-set. Value is irrelevant; we use Boolean.TRUE
    // as a lightweight placeholder — the key IS the visited tracking mechanism.
    private final IdentityHashMap<GraphNode, Boolean> visited = new IdentityHashMap<>();

    public void traverse(GraphNode startNode) {
        // containsKey uses == internally — correct for cycle detection
        if (visited.containsKey(startNode)) {
            System.out.println("Already visited (by reference): " + startNode);
            return;
        }

        visited.put(startNode, Boolean.TRUE);  // mark this exact object as seen
        System.out.println("Visiting: " + startNode);

        for (GraphNode neighbour : startNode.neighbours) {
            traverse(neighbour);  // recurse into neighbours
        }
    }

    public static void main(String[] args) {
        GraphNode nodeA = new GraphNode("auth-service");
        GraphNode nodeB = new GraphNode("user-service");
        GraphNode nodeC = new GraphNode("auth-service");  // SAME label as nodeA, different object!

        // Build a graph: A -> B -> C -> A (cycle back to A, not C)
        nodeA.neighbours.add(nodeB);
        nodeB.neighbours.add(nodeC);
        nodeC.neighbours.add(nodeA);  // points back to the ORIGINAL nodeA instance

        System.out.println("nodeA.equals(nodeC) = " + nodeA.equals(nodeC)); // true — same label!
        System.out.println("nodeA == nodeC      = " + (nodeA == nodeC));    // false — different objects
        System.out.println();

        // If we used a HashSet<GraphNode> or HashMap<GraphNode,...> for 'visited',
        // visiting nodeC would INCORRECTLY appear as 'already visited' because
        // nodeC.equals(nodeA) == true. IdentityHashMap prevents that false positive.
        new ObjectGraphVisitor().traverse(nodeA);
    }
}

import java.util.IdentityHashMap;

/**
 * Demonstrates the autoboxing trap in IdentityHashMap.
 * This is one of the most surprising bugs you can hit in production
 * when using IdentityHashMap with Integer keys.
 */
public class AutoboxingTrap {

    public static void main(String[] args) {

        IdentityHashMap<Integer, String> sessionMap = new IdentityHashMap<>();

        // Integer.valueOf() caches values from -128 to 127.
        // Both of these calls return THE EXACT SAME cached Integer object.
        Integer sessionIdSmall1 = Integer.valueOf(42);   // returns cached instance
        Integer sessionIdSmall2 = Integer.valueOf(42);   // returns the SAME cached instance

        System.out.println("--- Small Integer (within cache range) ---");
        System.out.println("sessionIdSmall1 == sessionIdSmall2 : " + (sessionIdSmall1 == sessionIdSmall2)); // true!

        sessionMap.put(sessionIdSmall1, "user-alice");
        sessionMap.put(sessionIdSmall2, "user-bob");   // same reference! OVERWRITES, size stays 1

        System.out.println("Map size (expect 1 due to cache): " + sessionMap.size()); // 1
        System.out.println("Value: " + sessionMap.get(Integer.valueOf(42)));           // user-bob

        sessionMap.clear();

        // Integer.valueOf(1000) is OUTSIDE the cache range.
        // Each call creates a brand new Integer object on the heap.
        Integer sessionIdLarge1 = Integer.valueOf(1000); // new object
        Integer sessionIdLarge2 = Integer.valueOf(1000); // another new object

        System.out.println("\n--- Large Integer (outside cache range) ---");
        System.out.println("sessionIdLarge1 == sessionIdLarge2 : " + (sessionIdLarge1 == sessionIdLarge2)); // false!

        sessionMap.put(sessionIdLarge1, "user-charlie");
        sessionMap.put(sessionIdLarge2, "user-diana");  // different reference — TWO entries!

        System.out.println("Map size (expect 2, surprise!): " + sessionMap.size()); // 2

        // Trying to retrieve with a THIRD Integer(1000) won't find anything
        // because it's yet another new reference, unknown to the map.
        Integer lookupAttempt = Integer.valueOf(1000);
        System.out.println("Lookup with new Integer(1000): " + sessionMap.get(lookupAttempt)); // null!

        // FIX: Always hold onto the exact reference you put in, and use it to retrieve.
        System.out.println("Lookup with original ref     : " + sessionMap.get(sessionIdLarge1)); // user-charlie
    }
}