Pick the right value collection and stop guessing

Yes you can stuff a bunch of values under one map key in Java. No you should not do it the sloppy way that causes bugs later when someone else inherits your code. Use a List when order and duplicates matter. Use a Set when uniqueness matters. Use LinkedHashSet when you want uniqueness but you also care which item showed up first. Choosing the right collection up front will save you from five minutes of debugging and several angry lattes.

The map of collections pattern that actually works

The core idea is simple and reliable. Instead of trying to shoehorn a single value type into a map use a map from key to a collection. Then add values to that collection. The usual one liner looks like this in practice and yes it is your friend

Map> map = new HashMap<>()
map.computeIfAbsent(key, k -> new ArrayList<>()).add(value)

Map> setMap = new HashMap<>()
setMap.computeIfAbsent(key, k -> new LinkedHashSet<>()).add(value)

computeIfAbsent avoids the null check noise and keeps initialization consistent when different parts of the code add values for the same key.

When duplicates are bad

If duplicates are unacceptable use a Set and let add return a boolean to tell you whether the item was new. HashSet gives you raw speed. LinkedHashSet buys you predictable iteration order without duplicate headaches.

When a library makes life easier

If you are tired of writing the same map to collection plumbing in multiple places consider a dedicated multimapping library. Guava offers Multimap which feels like a native fit for this job. Apache Commons provides MultiValuedMap if you prefer that ecosystem. They wrap the pattern into a cleaner API and provide helpful utilities for removal iteration and view operations.

// Guava style example
Multimap mm = ArrayListMultimap.create()
mm.put(key, value)
mm.get(key).forEach(v -> doSomething(v))

Bulk grouping with streams

When you start from a collection or stream of records use the Collectors utilities to turn a stream into a map of collections in one pass. This avoids manual loops and is concise and fast.

Map> grouped = items.stream()
    .collect(Collectors.groupingBy(Item::getKey, Collectors.mapping(Item::getValue, Collectors.toList())))

Map> asSets = items.stream()
    .collect(Collectors.groupingBy(Item::getKey, Collectors.mapping(Item::getValue, Collectors.toCollection(LinkedHashSet::new))))

Concurrency tips without chaos

High concurrency changes the rules. A plain HashMap with computeIfAbsent can still race in some scenarios when multiple threads mutate the inner collections. Prefer a ConcurrentHashMap when threads will add concurrently. For sets use ConcurrentHashMap.newKeySet which avoids extra locking. If you need a thread safe list consider Collections.synchronizedList or a CopyOnWriteArrayList for mostly read scenarios.

ConcurrentMap> concurrent = new ConcurrentHashMap<>()
concurrent.computeIfAbsent(key, k -> ConcurrentHashMap.newKeySet()).add(value)

Common pitfalls to avoid

• Do not share mutable inner collections across keys unintentionally. Each key needs its own collection instance.
• Avoid reinventing the multimapping API if a library already gives you what you need.
• Think about order and duplication up front so you do not chase bugs later.

Quick takeaway

• Map to a Collection for multiple values per key
• Use computeIfAbsent to initialize safely
• Pick List or Set based on order and uniqueness needs
• Use Guava Multimap or Apache Commons MultiValuedMap for less boilerplate
• Use streams for bulk grouping and ConcurrentHashMap or newKeySet for concurrency

That is it. Build sensible maps and your future self will thank you or at least stop yelling at you in code reviews.