WeakHashMap

#Introduction

WeakHashMap is one of those Java collections that interviewers use to distinguish between someone who knows the API and someone who understands Java references + Garbage Collection. The central idea:

WeakHashMap allows entries to disappear automatically when their keys are no longer strongly reachable elsewhere.

The important word is key.

#What Is WeakHashMap?

Package:

java.util.WeakHashMap

It implements Map<K,V>.

Map<Key, String> map = new WeakHashMap<>();

Unlike HashMap, the Map does not strongly retain its keys.

#HashMap vs WeakHashMap References

This is the most important distinction.

• HashMap — as long as the HashMap contains the key, the key remains strongly reachable through the Map.
• WeakHashMap — if there are no other strong references to the key, the key can become eligible for garbage collection.

What Is a Strong Reference?

Most normal Java references are strong references:

Employee employee = new Employee();

Here employee → Employee object. As long as employee is strongly reachable, the object isn't eligible for GC.

What Is a Weak Reference?

A weak reference does not prevent an object from being garbage collected.

This is the behaviour WeakHashMap relies on.

#The Key Lifecycle

The Key Relationship

Key key = new Key();

WeakHashMap<Key, String> map = new WeakHashMap<>();

map.put(key, "Data");

What Happens When the Strong Reference Disappears?

key = null;

If there are no other strong references to that Key, it becomes eligible for GC. After garbage collection and WeakHashMap's cleanup processing, the corresponding entry can disappear.

GC Is Not Deterministic

The correct sequence is:

Example

WeakHashMap<Object, String> map = new WeakHashMap<>();

Object key = new Object();
map.put(key, "Hello");

System.out.println(map.size());

1

Now key = null; — the entry becomes eligible for eventual removal once the key is collected. You should not write code that assumes the next statement will definitely print 0.

#Values Can Keep Keys Alive

Why Doesn't the Value Keep the Key Alive?

This is a subtle but important point. WeakHashMap is designed so that the map's internal entry does not create a strong path from the map to its key. However, you must be careful if the value itself strongly references its key:

Key key = new Key();
map.put(key, key);

The Key Must Be Weakly Reachable

The basic condition: no strong reference path to the key → key eligible for GC. The WeakHashMap's weak reference alone does not keep it alive.

Value Can Accidentally Keep Key Alive

A sophisticated interview question:

class Data {
    Key key;
}

Key key = new Key();
Data data = new Data(key);
map.put(key, data);

#How Cleanup Works

Weak References Internally

The implementation uses mechanisms from java.lang.ref, particularly weak references:

ReferenceQueue

A key implementation concept is ReferenceQueue. A simplified lifecycle:

Why Does WeakHashMap Need ReferenceQueue?

When a key gets garbage collected, the Map must eventually remove the corresponding entry. The ReferenceQueue provides a mechanism for detecting processed weak references: Garbage Collector → clears weak reference → ReferenceQueue → WeakHashMap cleanup → remove stale entry.

Does WeakHashMap Run a Background Thread?

No — an important misconception. WeakHashMap doesn't require a dedicated background thread constantly scanning all keys. Cleanup is integrated with Map operations and reference processing: Map operation → process stale references → remove obsolete entries. The exact implementation details can vary by Java version.

#GC-Sensitive Behaviour

size() Can Change Unexpectedly

One of the most important WeakHashMap interview traps. You insert several keys, then external strong references disappear. After GC, map.size() can become smaller.

Why This Matters

With HashMap, an entry normally remains until you explicitly remove it or clear the Map. With WeakHashMap: key becomes unreachable → GC → entry may disappear. So the Map's contents are partly dependent on object reachability.

System.gc() Trap

You might see examples like:

key = null;
System.gc();

and expect map.size() == 0. Don't rely on this. System.gc() is only a request/hint to the JVM — it doesn't guarantee immediate garbage collection.

Does WeakHashMap Guarantee Immediate Removal?

No. The correct wording: entries whose keys have been garbage collected become eligible for removal, and the Map removes stale entries as it processes cleared references. Don't say "the entry disappears immediately when the key becomes unreachable."

Iteration Behaviour

Because entries can disappear due to GC, iteration should not assume that a previously observed entry will remain indefinitely if its key has become weakly reachable.

for (Map.Entry<Key, String> entry : map.entrySet()) {
    System.out.println(entry.getValue());
}

Remember: the Map is GC-sensitive.

#Weak Keys, Not Weak Values

This is extremely important. WeakHashMap's special behaviour is primarily about WEAK KEYS, not weak values. The values are not automatically weak simply because the Map is a WeakHashMap.

#WeakHashMap Is Not a Normal Cache

A common interview misconception: "WeakHashMap is an LRU cache." No.

• LRU (Least Recently Used) is about access recency.
• WeakHashMap is about object reachability.

WeakHashMap and Cache Design

A common mistake: "I'll use WeakHashMap as my application cache." Be careful. A cache generally requires explicit semantics around size, eviction, expiration, refresh, concurrency, hit rate and memory limits.

WeakHashMap instead says: "If nobody strongly needs this key, the association can disappear." Those are very different semantics.

#Use Cases

Typical Use Case

WeakHashMap is useful when you want to:

Associate metadata with an object without making the object stay alive solely because of that association.

You don't want a metadata map that keeps objects alive forever. WeakHashMap can help avoid that retention.

Example — Object Metadata

WeakHashMap<Object, String> metadata = new WeakHashMap<>();

Object object = new Object();
metadata.put(object, "Temporary metadata");

As long as object is strongly reachable, the mapping can exist. Once the object is otherwise unreachable, the mapping can eventually disappear.

Example — Listener/Metadata Associations

Weak references can be useful for metadata, temporary associations and object-lifecycle tracking, where you don't want the tracking structure itself to extend the lifetime of the tracked object. The exact design should still be evaluated carefully; WeakHashMap is not automatically the right solution for every memory-management problem.

Example — Temporary Object Metadata

class Parser {
    // ...
}

WeakHashMap<Object, Metadata> metadata = new WeakHashMap<>();

The metadata association for parser-created objects doesn't need to extend their lifetime. This is a much better conceptual use case than treating WeakHashMap as a traditional cache.

Does WeakHashMap Prevent Memory Leaks?

It can help prevent certain forms of memory retention. But WeakHashMap is not a universal memory-leak solution. You still need to understand strong references, object graphs, thread-local references, static references, listener registrations, caches and resource lifecycle. Weak references are one tool, not a magic solution.

#Null, Ordering and Thread Safety

Null Key

WeakHashMap allows:

map.put(null, "Hello");

Unlike ordinary weakly referenced keys, null itself cannot be garbage collected, so the null-key mapping does not disappear merely because of weak-key processing.

Null Values

WeakHashMap also allows null values — map.put(key, null); — with no special restriction comparable to ConcurrentHashMap.

Is WeakHashMap Ordered?

No ordering guarantee. For insertion order use LinkedHashMap; for sorted keys use TreeMap. WeakHashMap's purpose is weak-key lifecycle behaviour.

Is WeakHashMap Thread-Safe?

No. If multiple threads access it concurrently and at least one structurally modifies it, you need an appropriate synchronization strategy. There isn't a standard ConcurrentWeakHashMap in the Java Collections Framework.

WeakHashMap and Synchronization

Collections.synchronizedMap(new WeakHashMap<>());

This does not magically create every property of a specialized concurrent collection. Iteration still requires following the normal synchronization rules for synchronized collection wrappers.

#Comparisons

WeakHashMap vs HashMap

WeakHashMap vs LinkedHashMap

WeakHashMap vs ConcurrentHashMap

Don't choose WeakHashMap just because you want memory optimization in a multithreaded application — concurrency requirements are separate.

WeakHashMap vs WeakReference

Don't confuse the two:

• WeakReference<T> — a reference mechanism (the building block).
• WeakHashMap — a Map implementation that uses weak references for keys (a collection abstraction).

#Java Reference Types

You should know these four categories: Strong, Soft, Weak, Phantom. For this chapter, the important one is WeakReference: a weak reference does not prevent collection when the referent is otherwise strongly unreachable.

Weak vs Soft Reference

#Decision Framework

The Map Family So Far

Most Important WeakHashMap Diagram

Memorize this — it's the entire concept:

Interview One-Liner

Final Mental Model

Remember: WeakHashMap = WEAK KEYS + GC-SENSITIVE. Not weak values. Not LRU. Not thread-safe.