Java Stream map() vs flatMap()

Java 8 map() and flatMap() are two important methods of java.util.stream.Stream interface used for transformation or mapping operations. Both are intermediate operations. The only difference is that map() takes Stream as input and return Stream where as flatMap() takes Stream<Stream as input and return Stream i.e flatmap() removes extra layer of nesting around input values.

map() is used for transformation only, but flatMap() is used for both transformation and flattening.
flatMap() = map() + Flattening

Map() :

The map() method produces one output value for each input value in the stream. So if there are n elements in the stream, map() operation will produce a stream of n output elements.

public static void main(String[] args) {
        List<String> listOfStrings = Arrays.asList("1", "2", "3", "4", "5");

        List<Integer> listOfIntegers = listOfStrings.stream()
                .map(Integer::valueOf)
                .collect(Collectors.toList());
        System.out.println(listOfIntegers);
    }

Output:

[1, 2, 3, 4, 5]

flatMap()

flatMap() is two step process i.e. map() + Flattening. It helps in converting Collection<Collection> to Collection.

public static void main(String[] args) {
        List<Integer> list1 = Arrays.asList(1,2,3);
        List<Integer> list2 = Arrays.asList(4,5,6);
        List<Integer> list3 = Arrays.asList(7,8,9);

        List<List<Integer>> listOfLists = Arrays.asList(list1, list2, list3);

        List<Integer> listOfAllIntegers = listOfLists.stream()
                .flatMap(x -> x.stream())
                .collect(Collectors.toList());

        System.out.println(listOfAllIntegers);
    }

Output:

[1, 2, 3, 4, 5, 6, 7, 8, 9]

For example, suppose we have a instituteList where each Institute consists of two fields. One is its name and another one is its different locations wrapped in another List as below.

 public static void main(String[] args) {
        List<Institute> instituteList = new ArrayList<>();

        instituteList.add(new Institute("IIM", Arrays.asList("Bangalore", "Ahmedabad", "Kozhikode", "Lucknow")));
        instituteList.add(new Institute("IIT", Arrays.asList("Delhi", "Mumbai", "Kharagpur")));
        instituteList.add(new Institute("NIFT", Arrays.asList("Hyderabad", "Mumbai", "Patna", "Bangalore")));

        //Java 8 FlatMap() : Get unique locations of all institutes

        Set<String> locationsOfInstitutes = (Set<String>) instituteList.stream().flatMap(institute -> institute.getLocations().stream()).collect(Collectors.toSet());
        System.out.println(locationsOfInstitutes);
    }

Output:

[Ahmedabad, Lucknow, Delhi, Patna, Kozhikode, Kharagpur, Mumbai, Hyderabad, Bangalore]

Conclusion

We can use map() operation when we have a stream of objects, and we need to get some unique value for each element in the stream. There is one-to-one mapping between input and output element. For example, we can write a program to find the date of birth of all employees in a stream of employees.

In case of flatMap(), a one-to-many mapping is created where for each input element/stream, we first get a multiple values and then we flatten the values from all such input streams into a single output stream. For example, we may write program to find all district words from all lines in a text file.