Introduction

In Java, an entry is a key-value pair, usually represented by Map.Entry. Most of the time you do not create one directly because calling put on a Map is enough. But there are still cases where a standalone entry object is useful, especially in immutable maps, stream pipelines, or temporary transformations.

The Most Common Case: Put into a Map

If your real goal is just to store a key and value in a map, create the map and call put.

1import java.util.HashMap;
2import java.util.Map;
3
4public class Main {
5    public static void main(String[] args) {
6        Map<String, Integer> stock = new HashMap<>();
7        stock.put("apple", 10);
8        stock.put("banana", 6);
9
10        System.out.println(stock);
11    }
12}

This is usually the correct answer because the map implementation manages its own internal entry objects. You do not need to create one manually first.

Create an Entry with Map.entry

If you really do want a standalone entry object, Java 9 added Map.entry.

1import java.util.Map;
2
3public class Main {
4    public static void main(String[] args) {
5        Map.Entry<String, Integer> item = Map.entry("orange", 12);
6
7        System.out.println(item.getKey());
8        System.out.println(item.getValue());
9    }
10}

This is compact and useful, but it creates an immutable entry. It is ideal for constants, stream code, and Map.ofEntries.

For example:

1import java.util.Map;
2
3public class Main {
4    public static void main(String[] args) {
5        Map<String, Integer> prices = Map.ofEntries(
6            Map.entry("apple", 10),
7            Map.entry("orange", 12),
8            Map.entry("pear", 8)
9        );
10
11        System.out.println(prices);
12    }
13}

The resulting map is immutable too, which is often exactly what you want for fixed data.

Use SimpleEntry for a Mutable Entry

If you need a standalone entry object whose value can change, use AbstractMap.SimpleEntry.

1import java.util.AbstractMap;
2import java.util.Map;
3
4public class Main {
5    public static void main(String[] args) {
6        Map.Entry<String, Integer> item =
7            new AbstractMap.SimpleEntry<>("apple", 10);
8
9        System.out.println(item.getKey() + " -> " + item.getValue());
10
11        item.setValue(15);
12        System.out.println(item.getKey() + " -> " + item.getValue());
13    }
14}

There is also AbstractMap.SimpleImmutableEntry if you want the same idea without allowing updates.

Entries Are Useful in Streams

A common modern use case is building entries temporarily in a stream before collecting them into a map.

1import java.util.List;
2import java.util.Map;
3import java.util.stream.Collectors;
4
5public class Main {
6    public static void main(String[] args) {
7        List<String> names = List.of("alice", "bob", "carol");
8
9        Map<String, Integer> lengths = names.stream()
10            .map(name -> Map.entry(name, name.length()))
11            .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue));
12
13        System.out.println(lengths);
14    }
15}

This is a strong use case for Map.entry because it lets you produce a pair without inventing a helper class just for one stream transformation.

Know When a Custom Type Is Better

Sometimes developers ask for Map.Entry when the pair is really domain data. If the values have business meaning, a custom type is usually clearer.

record ProductPrice(String product, int cents) {}

Use Map.Entry when you genuinely mean "some key associated with some value." Use a record or class when the pair represents something richer.

Common Pitfalls

• Creating a standalone entry when map.put(key, value) was all you needed.
• Expecting Map.entry to be mutable. It is not.
• Creating an entry object and assuming it automatically inserts itself into a map.
• Using Map.ofEntries and then trying to call put later on the returned map.
• Collecting stream entries into a map without handling duplicate keys.

Summary

• If you just want to add data to a map, use map.put(key, value).
• Use Map.entry for a compact immutable key-value pair.
• Use AbstractMap.SimpleEntry when you need a mutable standalone Map.Entry.
• Entries are especially useful in stream transformations and immutable map creation.
• If the pair represents real domain data, a custom record or class is often clearer than a map entry.