Course – LS – All
announcement - icon

Get started with Spring Boot and with core Spring, through the Learn Spring course:


1. Introduction

A HashMap is a widely used data structure in Java programming that stores key-value pairs, providing fast access to values based on their associated keys. However, in some cases, we may encounter scenarios where we need to associate multiple values with a single key.

In this tutorial, we’ll explore how to implement a HashMap that allows multiple values to be associated with the same key.

2. Overview

The standard implementation of a HashMap in most programming languages allows only one value to be associated with each key. When we encounter a situation where we need to store multiple values under the same key, we can consider various approaches to address this challenge.

One common solution is to use a data structure like an ArrayList, LinkedList, or HashSet to store the multiple values for each key.

3. Designing the HashMap With Multiple Values

Let’s begin by designing our custom HashMap class that allows multiple values associated with the same key. We’ll name it MultiValueHashMap.

3.1. Class Structure

First, let’s see the basic structure of our MultiValueHashMap class:

public class MultiValueHashMap<K, V> {
    private final HashMap<K, ArrayList<V>> map = new HashMap<>();

    // Methods
    // ...

In the above class structure, we use a private HashMap to store the keys and their associated ArrayLists of values. Furthermore, note that the key type (K) and value type (V) are generic to make the class flexible for various data types.

3.2. Adding a Value for a Key

Now, let’s implement a method to add a value for a specific key:

public void put(K key, V value) {
    map.computeIfAbsent(key, k -> new ArrayList<>()).add(value);

The put method adds a value to the map under a given key. If the key doesn’t exist, it creates a new entry with an empty list, then adds the value to that list. This makes it easy to store and manage multiple values associated with the same key in the map.

3.3. Retrieving Values for a Key

Next, let’s implement a method to retrieve all the values associated with a given key:

public List<V> get(K key) {
    return map.getOrDefault(key, new ArrayList<>());

The get method returns the ArrayList associated with the specified key, or an empty ArrayList if the key does not exist.

3.4. Removing a Key-Value Pair

To complete our implementation, we’ll add a method to remove a specific key-value pair:

public void remove(K key, V value) {
    map.computeIfPresent(key, (k, v) -> {
        return v;

The remove method takes a key and value as inputs and removes the value from the list associated with that key in the map if it exists. It’s a straightforward way to manage the removal of specific values from lists stored under particular keys in the map.

4. JUnit Test Examples

To ensure our MultiValueHashMap works as expected, we should write comprehensive JUnit test cases. Let’s see a few test examples:

public void given_MultiValueHashMap_whenPuttingAndGettingSingleValue_thenValueIsRetrieved() {
    MultiValueHashMap<String, Integer> map = new MultiValueHashMap<>();
    map.put("key1", 10);
    assertEquals(List.of(10), map.get("key1"));

public void given_MultiValueHashMap_whenPuttingAndGettingMultipleValues_thenAllValuesAreRetrieved() {
    MultiValueHashMap<String, String> map = new MultiValueHashMap<>();
    map.put("key2", "value1");
    map.put("key2", "value2");
    map.put("key2", "value3");

    assertEquals(List.of("value1", "value2", "value3"), map.get("key2"));

public void given_MultiValueHashMap_whenGettingNonExistentKey_thenEmptyListIsReturned() {
    MultiValueHashMap<String, Double> map = new MultiValueHashMap<>();

public void given_MultiValueHashMap_whenRemovingValue_thenValueIsSuccessfullyRemoved() {
    MultiValueHashMap<Integer, String> map = new MultiValueHashMap<>();
    map.put(1, "one");
    map.put(1, "uno");
    map.put(1, "eins");

    map.remove(1, "uno");
    assertEquals(List.of("one", "eins"), map.get(1));

public void testRemoveNonExistentValue() {
    MultiValueHashMap<Integer, String> map = new MultiValueHashMap<>();
    map.put(1, "one");
    map.remove(1, "nonexistent");
    assertEquals(List.of("one"), map.get(1));

In the JUnit test examples above, we verify the functionality of our MultiValueHashMap class for various scenarios, such as adding single and multiple values for the same key, retrieving values for both existing and non-existent keys, and removing key-value pairs.

5. Conclusion

In this article, we explored the concept of implementing a HashMap that supports multiple values associated with the same key. Moreover, we designed the MultiValueHashMap class and demonstrated its usage with JUnit test examples.

By using this custom implementation, developers can efficiently manage scenarios where multiple values are required for a single key, making their code more versatile and powerful.

As always, the complete code samples for this article can be found over on GitHub.


Course – LS – All
announcement - icon

Get started with Spring Boot and with core Spring, through the Learn Spring course:


res – REST with Spring (eBook) (everywhere)
Inline Feedbacks
View all comments