Java Map containsKey — Null-Valued Cache Entry Bug

containsKey() is simple but has a couple of edge cases that produce bugs in production code. The main one: map.get(key) != null is NOT equivalent to map.containsKey(key). If the map contains the key with a null value, get() returns null but containsKey() returns true. When you need to distinguish 'key exists with null value' from 'key doesn't exist', you must use containsKey().

containsKey() Usage and Edge Cases

containsKey() is the standard way to ask 'is this key present?' in any Map implementation. It returns true if the key exists, regardless of the value – even if that value is null. This is the critical distinction from get(key) != null.

When you call containsKey() on a HashMap, the map calculates the key's hash, locates the bucket, and checks equals() against each entry in that bucket. For TreeMap, it performs a binary search using compareTo(). For ConcurrentHashMap, it uses a striped read lock and volatile reads for thread safety.

package io.thecodeforge.collections;

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

public class MapContainsKeyExample {

    public static void main(String[] args) {
        Map<String, String> serviceRegistry = new HashMap<>();
        serviceRegistry.put("PaymentService", "https://payment.thecodeforge.io");
        serviceRegistry.put("AuditService", null);  // registered but no URL yet

        // containsKey() — correct way to check key existence
        System.out.println(serviceRegistry.containsKey("PaymentService")); // true
        System.out.println(serviceRegistry.containsKey("AuditService"));   // true — key exists, value is null
        System.out.println(serviceRegistry.containsKey("OrderService"));   // false

        // get() != null — WRONG way when null values are possible
        System.out.println(serviceRegistry.get("AuditService") != null); // false — but key EXISTS!
        // This is the bug: AuditService is registered but get() returns null
        // Using get() != null treats it as 'not registered'

        // Modern alternatives (Java 8+)
        // getOrDefault — return fallback if key absent
        String url = serviceRegistry.getOrDefault("OrderService", "http://default.thecodeforge.io");
        System.out.println(url); // http://default.thecodeforge.io

        // computeIfAbsent — add key if absent, return computed value
        serviceRegistry.computeIfAbsent("OrderService", k -> "https://" + k.toLowerCase() + ".io");
        System.out.println(serviceRegistry.get("OrderService")); // https://orderservice.io

        // putIfAbsent — add only if key not already present
        serviceRegistry.putIfAbsent("PaymentService", "http://changed-url.io"); // Not overwritten
        System.out.println(serviceRegistry.get("PaymentService")); // https://payment.thecodeforge.io

        // containsKey with null key (HashMap allows, not all Maps do)
        serviceRegistry.put(null, "null-key-service");
        System.out.println(serviceRegistry.containsKey(null)); // true (HashMap only)
    }
}

Handling Null Values: containsKey vs get() != null

The most common production bug with containsKey() is using map.get(key) != null as a key existence check. This works fine when the map never contains null values – but the moment a null value is stored, the logic breaks silently.

Consider a feature flag map: Map<String, Boolean> features. If a feature is present but disabled, you might store false. But what about null? Some teams use null to mean 'not evaluated yet'. In that case: - features.get("new-payment") != null → false even though the key exists. - features.containsKey("new-payment") → true – the correct answer.

When you need to handle both absent keys and null values, the pattern is: 1. Use containsKey() to check if the key exists. 2. Then call get() separately to retrieve the value (which may be null). But that's two lookups. A better approach for many cases is to avoid null values in maps altogether – store Optional.empty() or a sentinel value. Java 8's Optional class works well for nullable map values.

Modern Alternatives: getOrDefault and computeIfAbsent

Java 8 introduced methods that combine the check and the action into one atomic call. These are almost always better than the classic containsKey() + get() or containsKey() + put() pattern.

• getOrDefault(key, defaultValue): Returns the value mapped to the key, or defaultValue if the key is absent. It does NOT distinguish between 'key exists with null value' and 'key absent' – both return defaultValue. If you need that distinction, stick with containsKey(). But for most use cases, getOrDefault is cleaner and avoids the two-lookup issue.
• computeIfAbsent(key, mappingFunction): If the key is absent (or exists with null value), the mapping function runs and the result is stored and returned. This is perfect for lazy initialisation, caching, and singleton factories. It's atomic – only one thread computes and stores.
• putIfAbsent(key, value): Puts the value only if the key is not already present. Returns the existing value or null. This is simpler than containsKey() + put() but still involves a potential write.

Which one to choose? If you need the value in all cases, getOrDefault wins. If you need to compute the value only once, use computeIfAbsent. If you just want to set a default without computation, putIfAbsent.

package io.thecodeforge.collections;

import java.util.concurrent.ConcurrentHashMap;

public class ModernAlternatives {
    static ConcurrentHashMap<String, String> config = new ConcurrentHashMap<>();

    public static void main(String[] args) {
        // Old way: two lookups
        String oldWay;
        if (!config.containsKey("db.url")) {
            config.put("db.url", "jdbc:default:localhost");
        }
        oldWay = config.get("db.url");

        // New way: one atomic call
        String newWay = config.computeIfAbsent("db.url", k -> "jdbc:default:localhost");

        System.out.println(oldWay.equals(newWay)); // true
        
        // getOrDefault with a null-valued key
        config.put("db.pool", null);  // existing key, null value
        String poolSize = config.getOrDefault("db.pool", "10"); // returns "10"!!! 
        System.out.println(poolSize); // "10" – even though key exists
    }
}

Null Key Support Across Map Implementations

Not every Map implementation handles null keys the same way. This is a common source of unexpected NullPointerExceptions in production, especially when refactoring from HashMap to TreeMap or ConcurrentHashMap.

• HashMap: Allows exactly one null key. It's stored in a special bucket and found via hash 0. containsKey(null) works fine.
• LinkedHashMap: Same as HashMap – allows one null key.
• TreeMap: Throws NullPointerException on any null key (including containsKey(null)). TreeMap uses compareTo() which cannot handle null without a custom Comparator that does.
• ConcurrentHashMap: Does NOT allow null keys. It throws NullPointerException on containsKey(null) and put(null, ...). This is intentional: null keys would break thread-safety guarantees and methods like computeIfAbsent.
• EnumMap: Key must be an enum. Null key throws NullPointerException.
• IdentityHashMap: Allows null keys (stored with special handling).

If you need null key support across different implementations, wrap the key in an Optional (pre-Java 9) or convert null to a sentinel string like "__null__". But the cleanest approach is to avoid null keys altogether.

Performance Considerations of containsKey()

containsKey() is O(1) on average for HashMap, O(log n) for TreeMap, and O(1) amortized for ConcurrentHashMap (though with higher constant overhead due to volatile reads). For most applications, the performance of containsKey() is not a bottleneck.

However, the pattern of containsKey() followed by get() is TWO hash lookups (or two tree traversals). This doubles the time for that code path. For high-frequency operations (e.g., inside a hot loop, parsing a large config file), that overhead adds up.

Synthetic benchmark: On a HashMap with a million entries, containsKey()+get() takes ~120ns on average vs getOrDefault at ~70ns. Not huge, but at 10M calls per second, that's ~500ms difference. In latency-sensitive systems, every microsecond counts.

Additionally, computeIfAbsent may run the function under the map's segment lock (in ConcurrentHashMap), which can stall other operations on the same segment. But in practice, for most workloads, the lock contention is negligible.