Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Java HashMap Iteration: Methods and Tradeoffs

Learn practical ways to iterate over a Java HashMap with entrySet, keySet, values, forEach, and streams, plus the performance and concurrency tradeoffs to consider.

~5 min readJava
#HashMap#Java Collections#Iteration#forEach
Illustration of iterating over a Java HashMap showing key-value pairs and iteration methods.

When you need to process every entry in a Java HashMap, the iteration strategy you choose affects readability, performance, and even correctness in concurrent scenarios. Java HashMap iteration is a common task, but the API offers several ways to do it, and they are not always interchangeable.

The Core Iteration Options

A HashMap implements the Map interface, which defines three collection views: keySet(), values(), and entrySet(). Each view can be iterated with a for-each loop, an iterator, or a Java 8 stream. Additionally, the forEach method accepts a BiConsumer and is often the most concise option. The choice depends on whether you need keys, values, or both, and whether you need to modify the map during iteration.

Iterating with entrySet() for Key-Value Access

When your logic requires both the key and the value, entrySet() is the most direct approach. Each element is a Map.Entry that exposes getKey() and getValue(). This avoids a separate lookup for each key, which is especially important for large maps.

java
Map<String, Integer> scores = new HashMap<>(); scores.put("Alice", 92); scores.put("Bob", 85); scores.put("Carol", 78); for (Map.Entry<String, Integer> entry : scores.entrySet()) { System.out.println(entry.getKey() + " -> " + entry.getValue()); }

The loop variable is a Map.Entry reference, and you can read both parts without calling get() on the map. This is the recommended pattern for most iteration tasks because it is both readable and efficient.

Using keySet() and values() When You Need Only One Side

keySet() returns a Set of keys, so it is the view to use when your logic needs only keys. A common but avoidable mistake is to iterate keySet() and call map.get(key) for each key when you also need the value; that performs an extra lookup on every iteration. If you need both keys and values, prefer entrySet(). If you only need values, values() returns a Collection of values directly.

java
// Keys only for (String key : scores.keySet()) { System.out.println("Key: " + key); } // Values only for (Integer value : scores.values()) { System.out.println("Value: " + value); }

These views are backed by the map. If you modify the map structurally while iterating over one of them, the iteration will generally throw a ConcurrentModificationException unless you remove the current entry through the iterator's own remove() method. For read-only processing, they are perfectly safe.

forEach and Stream Iteration

Java 8 introduced the forEach method and streams for working with maps. The forEach method accepts a BiConsumer and is the most compact syntax for iteration. It also works well with lambda expressions.

java
scores.forEach((key, value) -> { System.out.println(key + " -> " + value); });

If you need to filter or transform entries, a stream over entrySet() is more flexible. For example, to collect keys of entries with a value above a threshold:

java
List<String> highScorers = scores.entrySet().stream() .filter(entry -> entry.getValue() >= 90) .map(Map.Entry::getKey) .collect(Collectors.toList());

If you are using Java 16 or later, you can replace .collect(Collectors.toList()) with .toList(). Streams introduce some overhead due to the pipeline machinery, but for typical collection sizes the difference is negligible. Use streams when you need declarative operations like filtering, mapping, or reduction; use forEach when you simply need to perform an action on each entry.

Performance and Ordering Considerations

HashMap does not guarantee any iteration order. You should not rely on insertion order or any other ordering, and the order can change when entries are added or removed. If you need predictable iteration order, use LinkedHashMap, which maintains a doubly-linked list of entries in insertion order (or access order if configured).

From a performance perspective, entrySet() is generally the most efficient when you need both keys and values because it avoids the extra get() lookup that a keySet()-plus-get() approach requires. The values() view is efficient for values alone, but it does not give you access to keys. The forEach method's default implementation iterates over entrySet() internally, so its performance is similar to an explicit entrySet() loop.

Stream-based iteration adds some overhead due to the stream pipeline, but for most applications the difference is not significant. The main cost is the creation of intermediate objects for operations like filter and map. If you are processing millions of entries in a tight loop, a traditional for-each loop over entrySet() is likely the fastest option.

Concurrent Modification and Thread Safety

The iterators returned by HashMap's collection views are fail-fast: if the map is structurally modified after the iterator is created, the iterator throws ConcurrentModificationException. This is a safety mechanism, not a guarantee of consistent behavior in concurrent programs. It is not a reliable way to detect concurrent modification because it is best-effort and can miss changes in some cases.

If you need to iterate over a map while other threads may modify it, use ConcurrentHashMap. Its iterators are weakly consistent: they reflect the state of the map at some point during iteration and do not throw ConcurrentModificationException. However, they also do not guarantee that every update made during iteration will be visible. For example:

java
Map<String, Integer> concurrentScores = new ConcurrentHashMap<>(); concurrentScores.put("Alice", 92); for (Map.Entry<String, Integer> entry : concurrentScores.entrySet()) { // Safe from ConcurrentModificationException System.out.println(entry.getKey() + " -> " + entry.getValue()); }

If you need to remove entries during iteration, use the iterator's remove() method, which is the only safe way to modify the map without throwing an exception. For ConcurrentHashMap, you can also use remove(key, value) or compute methods, but the iterator's remove() is still supported.

Choosing the Right Iteration Strategy

Select the iteration approach based on what you need and the context:

  • Use entrySet() when you need both keys and values. It is the most direct and avoids extra lookups.
  • Use keySet() when you only need keys.
  • Use values() when you only need values and have no need for keys.
  • Use forEach when you have a simple action to perform on each entry and want concise syntax.
  • Use streams when you need to filter, map, or collect entries in a declarative way.
  • Use ConcurrentHashMap and its weakly consistent iterators when the map is shared across threads.

For most applications, a for-each loop over entrySet() is the safest and most readable default. It works in single-threaded code, uses the same iterator infrastructure that supports removal when you need it, and does not depend on Java 8 features. If you are using Java 8 or later, forEach is a clean alternative for simple actions. Streams are best reserved for more complex transformations where the declarative style pays off.

One edge case to keep in mind: if you modify the map's structure inside a stream pipeline (for example, by calling put or remove inside a forEach), you can still trigger a ConcurrentModificationException because the stream is backed by the map's collection view. The same fail-fast behavior applies. For concurrent modifications, always use ConcurrentHashMap or synchronize externally.

Finally, remember that iteration order is not guaranteed for HashMap. If your algorithm depends on a specific order, switch to LinkedHashMap or explicitly sort the entries before processing. The iteration method you choose does not affect order; it only affects how you access the data.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.