map vs flatMap in reactor

Question

I\'ve found a lot of answers regarding RxJava, but I want to understand how it works in Reactor.

My current understanding is very vague, i tend to think of map as being

Answer 1

The flatMap method is similar to the map method with the key difference that the supplier you provide to it should return a Mono or Flux.

Using the map method would result in a Mono> whereas using flatMap results in a Mono.

For example, it is useful when you have to make a network call to retrieve data, with a java API that returns a Mono, and then another network call that needs the result of the first one.

// Signature of the HttpClient.get method
Mono get(String url);

// The two urls to call
String firstUserUrl = "my-api/first-user";
String userDetailsUrl = "my-api/users/details/"; // needs the id at the end

// Example with map
Mono> result = HttpClient.get(firstUserUrl).
  map(user -> HttpClient.get(userDetailsUrl + user.getId()));
// This results with a Mono> because HttpClient.get(...)
// returns a Mono

// Same example with flatMap
Mono bestResult = HttpClient.get(firstUserUrl).
  flatMap(user -> HttpClient.get(userDetailsUrl + user.getId()));
// Now the result has the type we expected

Also, it allows for handling errors precisely:

public UserApi {
  
  private HttpClient httpClient;
    
  Mono findUser(String username) {
    String queryUrl = "http://my-api-address/users/" + username;
    
    return Mono.fromCallable(() -> httpClient.get(queryUrl)).
      flatMap(response -> {
        if (response.statusCode == 404) return Mono.error(new NotFoundException("User " + username + " not found"));
        else if (response.statusCode == 500) return Mono.error(new InternalServerErrorException());
        else if (response.statusCode != 200) return Mono.error(new Exception("Unknown error calling my-api"));
        return Mono.just(response.data);
      });
  }
                                           
}