Build an account-to-balance map with Collectors.toMap and resolve duplicate keys with a merge function

Collectors.toMap with a merge function aggregates a stream into a Map even when keys repeat.

• Key mapper – extracts the grouping key, here the account id.
• Value mapper – extracts the value to aggregate, here the transaction amount as BigDecimal.
• Merge function – a BinaryOperator invoked when two values share a key; BigDecimal::add sums them.
• IllegalStateException – thrown by the two-argument form on the first duplicate key, because it has no rule to combine values.

Supplying the merge function turns a collision from a crash into a running total.

Why does a stream of transactions produce duplicate keys?

A transaction log naturally has many rows per account: a deposit, a withdrawal, a transfer, and so on. When you key a toMap by account id, the same id appears repeatedly. The two-argument toMap treats a repeated key as an error.

package com.bank.ledger;

import java.math.BigDecimal;

public class Transaction {
    private final String accountId;
    private final BigDecimal amount;
    public Transaction(String accountId, BigDecimal amount) {
        this.accountId = accountId;
        this.amount = amount;
    }
    public String getAccountId() { return accountId; }
    public BigDecimal getAmount() { return amount; }
}

What happens with the two-argument toMap?

It throws IllegalStateException on the first collision, naming both conflicting values. The design assumes keys are unique; a duplicate is treated as a bug.

package com.bank.ledger;

import java.math.BigDecimal;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

public class DuplicateKeyCrash {
    public static void main(String[] args) {
        List<Transaction> txns = List.of(
            new Transaction("ACC-1", new BigDecimal("1000.00")),
            new Transaction("ACC-1", new BigDecimal("250.00"))); // same account
        Map<String, BigDecimal> balances = txns.stream()
            .collect(Collectors.toMap(Transaction::getAccountId, Transaction::getAmount));
        System.out.println(balances);
    }
}

Exception in thread "main" java.lang.IllegalStateException: Duplicate key ACC-1 (attempted merging values 1000.00 and 250.00)

How does the merge function resolve the collision?

Add a third argument, a BinaryOperator. It runs only on a duplicate key, receiving the value already stored and the incoming value, and returns the combined value. BigDecimal::add sums them into a running balance.

package com.bank.ledger;

import java.math.BigDecimal;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

public class AccountBalances {
    public static Map<String, BigDecimal> totals(List<Transaction> txns) {
        return txns.stream()
            .collect(Collectors.toMap(
                Transaction::getAccountId,
                Transaction::getAmount,
                BigDecimal::add)); // sum on collision
    }
}

{ACC-1=1250.00}

Why must money use BigDecimal and not double?

double cannot represent many decimal fractions exactly, so summing money as double accumulates rounding errors. BigDecimal stores decimal digits exactly and its add is precise.

// WRONG: double arithmetic drifts
double total = 0.0;
total += 0.1; total += 0.2;
System.out.println(total); // 0.30000000000000004

// CORRECT: BigDecimal is exact
BigDecimal exact = new BigDecimal("0.10").add(new BigDecimal("0.20"));
System.out.println(exact);  // 0.30

How does toMap + merge compare with groupingBy?

Both can total balances per account. toMap with a merge aggregates values directly; groupingBy groups then reduces. Use groupingBy when the key naturally maps to many values and you want a clear grouping, and toMap when you want a single aggregate per key with explicit collision handling.

| Approach | Shape | Collision handling | Reads as |
|----------|-------|--------------------|----------|
| toMap(key, value, merge) | one value per key | explicit merge function | aggregate per key |
| groupingBy(key, reducing(...)) | grouped then reduced | implicit by grouping | group then combine |
| groupingBy(key, summingX(...)) | numeric sum per key | implicit | sum per key |

// groupingBy + reducing, equivalent total balance
Map<String, BigDecimal> byGrouping = txns.stream()
    .collect(Collectors.groupingBy(
        Transaction::getAccountId,
        Collectors.reducing(BigDecimal.ZERO, Transaction::getAmount, BigDecimal::add)));

What are the common mistakes?

The first mistake is forgetting the merge function on data that clearly has repeated keys.

// WRONG: transaction log always repeats account ids, this crashes
Map<String, BigDecimal> balances = txns.stream()
    .collect(Collectors.toMap(Transaction::getAccountId, Transaction::getAmount));

// CORRECT: sum duplicates with a merge function
Map<String, BigDecimal> balances = txns.stream()
    .collect(Collectors.toMap(Transaction::getAccountId, Transaction::getAmount, BigDecimal::add));

The second mistake is summing money with double or Double::sum, which loses precision.

// WRONG: double loses precision on money
.collect(Collectors.toMap(Transaction::getAccountId, t -> t.getAmount().doubleValue(), Double::sum));

// CORRECT: stay in BigDecimal
.collect(Collectors.toMap(Transaction::getAccountId, Transaction::getAmount, BigDecimal::add));

What are the edge cases around nulls and empty streams?

toMap rejects null values, so a null amount throws NullPointerException. An empty transaction list yields an empty map, not a crash.

// Null amount: throws NullPointerException
List<Transaction> bad = List.of(new Transaction("ACC-1", null));
// Guard by filtering or defaulting the amount first
Map<String, BigDecimal> balances = bad.stream()
    .filter(t -> t.getAmount() != null)
    .collect(Collectors.toMap(Transaction::getAccountId, Transaction::getAmount, BigDecimal::add));

When should you use toMap with a merge versus a simple grouping?

Use toMap with a merge when you want exactly one aggregated value per key and want to express the combine rule explicitly. Use groupingBy with summingX or reducing when the mental model is "group these rows, then combine each group," especially for reporting with multiple downstream aggregations.

// One aggregate per account, explicit rule
Map<String, BigDecimal> balances = txns.stream()
    .collect(Collectors.toMap(Transaction::getAccountId, Transaction::getAmount, BigDecimal::add));

What should a senior engineer know?

• Associativity for parallelism. BigDecimal::add is associative, so the merge is correct in a parallel stream where partial maps are combined.
• Scale consistency. Ensure all amounts share a scale (for example two decimal places) so totals print consistently; use setScale if sources differ.
• Choosing the map type. Add a fourth argument LinkedHashMap::new or TreeMap::new to control iteration or sorting of account ids.
• Immutability. Wrap with collectingAndThen(toMap(...), Collections::unmodifiableMap) so the balance snapshot cannot be mutated after it is produced.

What are common interview follow-up questions?

• "What exception does the two-argument toMap throw on duplicate account ids?" Answer: IllegalStateException with a "Duplicate key" message.
• "How do you total balances instead of crashing?" Answer: supply BigDecimal::add as the merge function.
• "Why BigDecimal and not double?" Answer: double introduces rounding errors; BigDecimal is exact for money.
• "When would you use groupingBy instead?" Answer: when a key maps to many rows and you want grouping with one or more downstream aggregations.