Add advice on using exchange from an ExchangeFilterFunction

Closes gh-26819

spring-webflux/src/main/java/org/springframework/web/reactive/function/client/ExchangeFilterFunction.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2021 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -39,6 +39,13 @@ public interface ExchangeFilterFunction {
 	 * in the chain, to be invoked via
 	 * {@linkplain ExchangeFunction#exchange(ClientRequest) invoked} in order to
 	 * proceed with the exchange, or not invoked to shortcut the chain.
+	 *
+	 * <p><strong>Note:</strong> When a filter handles the response after the
+	 * call to {@link ExchangeFunction#exchange}, extra care must be taken to
+	 * always consume its content or otherwise propagate it downstream for
+	 * further handling, for example by the {@link WebClient}. Please, see the
+	 * reference documentation for more details on this.
+	 *
 	 * @param request the current request
 	 * @param next the next exchange function in the chain
 	 * @return the filtered response

spring-webflux/src/main/java/org/springframework/web/reactive/function/client/ExchangeFunction.java

@@ -43,6 +43,14 @@ public interface ExchangeFunction {
 
 	/**
 	 * Exchange the given request for a {@link ClientResponse} promise.
+	 *
+	 * <p><strong>Note:</strong> When a calling this method from an
+	 * {@link ExchangeFilterFunction} that handles the response in some way,
+	 * extra care must be taken to always consume its content or otherwise
+	 * propagate it downstream for further handling, for example by the
+	 * {@link WebClient}. Please, see the reference documentation for more
+	 * details on this.
+	 *
 	 * @param request the request to exchange
 	 * @return the delayed response
 	 */