add flatMapPayload(Fn<A,Response<B>>) to Response

apollo-api/src/main/java/com/spotify/apollo/Response.java

@@ -90,6 +90,42 @@ default <P> Response<P> mapPayload(Function<? super T, ? extends P> mapFunction)
         : withPayload(mapFunction.apply(payload().get()));
   }
 
+  /**
+   * Maps the contained payload if it exists, otherwise does nothing except changing the type
+   * of the response.
+   *
+   * The new response contents will be merged with this response using {@link #merge(Response)}.
+   *
+   * @param mapFunction  The function for mapping the payload
+   * @param <P>          The type of the mapped payload
+   * @return A response with a converted payload
+   */
+  default <P> Response<P> flatMapPayload(Function<? super T, ? extends Response<? extends P>> mapFunction) {
+    //noinspection unchecked
+    return !payload().isPresent()
+        ? (Response<P>) this
+        : merge(mapFunction.apply(payload().get()));
+  }
+
+  /**
+   * Merge another response with this response.
+   *
+   * The payload of the other response will override the payload in this response,
+   * even if not present, in which case it will reset the payload.
+   *
+   * Headers keys will be merged with headers from the other response taking precedence.
+   *
+   * The status of the other response will always be ignored.
+   *
+   * @param other  The other response to merge with this
+   * @param <P>    The type of the other response payload
+   * @return A merged response
+   */
+  default <P> Response<P> merge(Response<? extends P> other) {
+    return withPayload(other.payload().orElse(null))
+        .withHeaders(other.headers());
+  }
+
   /**
    * Returns a typed 200 OK {@link Response}.
    *

apollo-api/src/test/java/com/spotify/apollo/ResponsePayloadMapTest.java

@@ -57,11 +57,57 @@ public void mapsPayload(Response<String> input) throws Exception {
     }
   }
 
+  @Theory
+  public void removePayloadIfNull(Response<String> input) throws Exception {
+    Response<Integer> intResponse = input.mapPayload(ignored -> null);
+
+    assertFalse(intResponse.payload().isPresent());
+  }
+
   @Theory
   public void preserveStatusAndHeaderOnMap(Response<String> input) throws Exception {
     Response<Integer> intResponse = input.mapPayload(String::length);
 
     assertThat(intResponse.status(), is(Status.IM_A_TEAPOT));
     assertThat(intResponse.headers(), hasEntry("foo", "bar"));
   }
+
+  @Theory
+  public void mapsPayloadOnFlatMap(Response<String> input) throws Exception {
+    Response<Integer> intResponse = input.flatMapPayload(
+        str -> Response.forPayload(str.length()));
+
+    if (input.payload().isPresent()) {
+      assertThat(intResponse.payload().get().intValue(), is(5));
+    } else {
+      assertFalse(intResponse.payload().isPresent());
+    }
+  }
+
+  @Theory
+  public void mergesHeadersOnFlatMap(Response<String> input) throws Exception {
+    Response<Integer> intResponse = input.flatMapPayload(
+        str -> Response.forPayload(str.length())
+            .withHeader("baz", str));
+
+    assertThat(intResponse.headers(), hasEntry("foo", "bar"));
+    if (input.payload().isPresent()) {
+      assertThat(intResponse.headers(), hasEntry("baz", "hello"));
+    }
+  }
+
+  @Theory
+  public void preservesStatusOnFlatMap(Response<String> input) throws Exception {
+    Response<Integer> intResponse = input.flatMapPayload(
+        ignored -> Response.forStatus(Status.GONE));
+
+    assertThat(intResponse.status(), is(Status.IM_A_TEAPOT));
+  }
+
+  @Theory
+  public void removePayloadIfNotSetOnFlatMap(Response<String> input) throws Exception {
+    Response<Integer> intResponse = input.flatMapPayload(ignored -> Response.ok());
+
+    assertFalse(intResponse.payload().isPresent());
+  }
 }