Quais são as diferenças entre os métodos map e flatMap na API Stream do Java e quais são suas características de uso?

Os métodos map e flatMap na API de Streams do Java servem para transformar os elementos de um fluxo, mas funcionam de forma diferente:

• map aceita uma função que transforma cada elemento do fluxo em outro elemento. Como resultado, obtém-se um fluxo com o mesmo número de elementos, mas de um tipo ou forma diferente.

• flatMap aceita uma função que transforma cada elemento em um fluxo (Stream) de elementos, e depois combina ("achata") todos esses fluxos num fluxo comum. Isto é útil quando de um único elemento se pretendem obter vários elementos.

Exemplo:

List<String> words = Arrays.asList("hello", "world");

// map: transformamos cada palavra na sua extensão
List<Integer> lengths = words.stream()
    .map(String::length)
    .collect(Collectors.toList()); // [5, 5]

// flatMap: dividimos cada palavra em letras e combinamos todas as letras num fluxo
List<String> letters = words.stream()
    .flatMap(word -> Arrays.stream(word.split("")))
    .collect(Collectors.toList()); // [h, e, l, l, o, w, o, r, l, d]

Características de uso:

• map é adequado para transformações simples de elementos um a um.
• flatMap é necessário quando de um único elemento se quer obter vários, e é preciso "achatar" estruturas aninhadas.