Java HashMap replace: Update Existing Entries
java hashmap replace: Learn how the Java HashMap replace method works, its two overloads, return values, and when to use it instead of put.

The Java HashMap replace method provides a way to update an existing key's value without accidentally inserting a new entry. It's a common source of confusion because it looks similar to put but behaves differently. This article explains both overloads, their return values, and when to use them.
The Two replace Overloads and Their Signatures
The Map interface defines two replace methods that HashMap implements:
V replace(K key, V value)
boolean replace(K key, V oldValue, V newValue)The first overload replaces the value for the specified key only if the key currently has a mapping. It returns the previous value, or null if there was no mapping. The second overload replaces the value only if the key is currently mapped to the specified oldValue. It returns true if the replacement was performed, and false otherwise.
Both methods were added as default methods in Java 8 and are available in HashMap.
How replace Differs from put
The most important distinction is that put always inserts or overwrites, while replace only updates an existing mapping. Consider this example:
Map<String, Integer> map = new HashMap<>();
map.put("count", 1);
map.replace("count", 2); // updates existing key
map.replace("missing", 10); // does nothing, returns null
map.put("missing", 10); // inserts new entryIf you call replace on a key that does not exist, the map remains unchanged. This is useful when you want to update a value only if the key is already present, without risking an accidental insertion.
Return Values and Null Handling
The replace(K key, V value) overload returns the previous value associated with the key, or null if there was no mapping. This can be ambiguous when the previous value itself is null. For example:
map.put("key", null);
map.replace("key", "value"); // returns null, but key existedThe return value does not tell you whether the key existed; it only tells you the previous value. To check existence, use containsKey before calling replace, or use the three-parameter overload if you need a boolean result.
The replace(K key, V oldValue, V newValue) overload returns a boolean, which avoids the ambiguity. It also allows you to perform a conditional update only when the current value matches an expected value.
Practical Use Cases for replace
A common use case is updating a cache or a configuration map where you want to change a value only if it already exists. For example, updating a session attribute:
Map<String, Session> sessions = new HashMap<>();
sessions.put("user-123", new Session());
// Only replace the value if the current mapping is still oldSession
boolean updated = sessions.replace("user-123", oldSession, newSession);Another use case is implementing a counter that should not create a new entry if the key is missing. You might use replace in combination with get or compute for more complex logic.
Concurrency and Atomicity Considerations
HashMap is not thread-safe, and its replace methods are not atomic. If multiple threads modify the same map concurrently, you need external synchronization or a concurrent map implementation. ConcurrentHashMap provides atomic replace methods that are safe for concurrent use. For example:
ConcurrentHashMap<String, Integer> map = new ConcurrentHashMap<>();
map.put("count", 1);
// Atomic conditional update
map.replace("count", 1, 2);If you are using a plain HashMap in a multi-threaded context, you must synchronize access yourself. The replace method does not provide any locking or atomicity guarantees.
Performance and Internal Behavior
The replace methods have the same time complexity as get and put — O(1) on average, assuming a good hash function and no excessive collisions. Because they do not insert entries, they do not trigger a resize on their own.
Internally, replace locates the bucket for the key, then checks whether the key exists. If it does, it updates the value. The three-parameter overload also checks the current value equality before updating. This adds a minor overhead, but it is negligible in most applications.
Common Mistakes and Edge Cases
One common mistake is using replace when you actually need to insert a new entry if the key is absent. In that case, use put or putIfAbsent. Another mistake is assuming that replace returns the new value; it returns the old value or a boolean, depending on the overload.
Be careful with null values. If your map can contain null values, the return value of the two-parameter replace becomes unreliable for checking existence. Prefer the three-parameter overload or use containsKey explicitly.
Also note that replace does not support custom equality for keys; it uses equals and hashCode as defined by the key class. If your key objects have mutable state that affects equality, you may encounter unexpected behavior.
Try matching browser tools
All toolsSmall utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Java guides
All Java guidesJava Final Keyword: Usage and Behavior
How Java's final keyword works for variables, methods, and classes, with practical examples and decision guidance for using it.
Java Final Variable: Syntax, Behavior, and Use Cases
Understand what a final variable in Java means, how initialization works, and when to use it for constants, immutability, and clearer code.
Java Duration vs Period: When to Use Each
java duration vs period: Compare Java Duration and Period to handle time-based and date-based calculations correctly. Learn syntax, conversion, and pitfalls.
Instance vs Static Variables in Java: Key Differences
Understand the difference between instance and static variables in Java, including memory, lifecycle, and when to use each.
More in Java
All Java guidesThe guides filed next to this one in Java, in library order.