What is WeakHashMap?

• WeakReference keys – every key is wrapped in a WeakReference; once no strong reference to the key exists outside the map, the GC may collect it
• Automatic entry removal – after the key is collected, the map removes the entry during its next internal operation via a ReferenceQueue
• Same API as HashMap – implements Map with put, get, remove, size, and iteration
• Not thread-safe – requires external synchronisation or Collections.synchronizedMap for concurrent access
• Null keys and values – both are permitted, unlike ConcurrentHashMap

What is WeakHashMap?

WeakHashMap is a Map implementation in java.util where each key is stored inside a WeakReference. When no strong reference to the key exists outside the map, the garbage collector is free to collect it. On the next map operation, the entry is silently removed.

This differs from HashMap, which holds strong references to keys. In a HashMap, entries persist until explicitly removed, even when the key object is no longer used anywhere else in the program.

package com.bank.demo;

import java.util.HashMap;
import java.util.Map;
import java.util.WeakHashMap;

public class WeakHashMapBasicDemo {
    public static void main(String[] args) {
        Map<Object, String> weak = new WeakHashMap<>();
        Object accountKey = new Object();
        weak.put(accountKey, "Rajesh's loan metadata");

        System.out.println("Before nulling key: size = " + weak.size());

        accountKey = null; // remove the only strong reference
        System.gc();       // hint to the GC

        // Allow GC time to run
        try { Thread.sleep(200); } catch (InterruptedException ignored) {}

        System.out.println("After GC: size = " + weak.size());
    }
}

Before nulling key: size = 1
After GC: size = 0

Why does WeakHashMap exist?

WeakHashMap solves a specific problem: memory leaks caused by long-lived maps that hold references to objects the rest of the application has abandoned. Without weak keys, a cache or metadata map keeps every key alive forever, even if no other part of the program uses it.

In a banking application, consider a cache that maps ClassLoader instances to configuration metadata. When a microservice module is hot-reloaded, the old ClassLoader should be garbage-collected. A HashMap would prevent that because it holds a strong reference to the ClassLoader key. A WeakHashMap allows the old ClassLoader to be collected, and the stale entry disappears automatically.

package com.bank.demo;

import java.util.Map;
import java.util.WeakHashMap;

public class ClassLoaderCacheDemo {
    // Simulates a ClassLoader-scoped cache
    private static final Map<ClassLoader, String> configCache = new WeakHashMap<>();

    public static void main(String[] args) {
        ClassLoader loader = new ClassLoader() {};
        configCache.put(loader, "db.url=jdbc:oracle:thin:@nbi-prod:1521:BANKING");

        System.out.println("Config cached: " + configCache.size());

        loader = null;
        System.gc();
        try { Thread.sleep(200); } catch (InterruptedException ignored) {}

        System.out.println("After classloader GC: " + configCache.size());
    }
}

Config cached: 1
After classloader GC: 0

How does WeakHashMap work internally?

WeakHashMap maintains an array of buckets, similar to HashMap. Each entry wraps the key in a WeakReference that is registered with a ReferenceQueue. When the GC collects a weakly-reachable key, the JVM enqueues the reference into that queue.

Before every get, put, size, or iteration, WeakHashMap calls an internal expungeStaleEntries() method. This method drains the ReferenceQueue and removes every entry whose key has been collected.

• The key is stored as new Entry<>(key, value, queue, hash, next) where Entry extends WeakReference