Allow RestClient::exchange to keep connection open

This commit introduces an overloaded version of RestClient::exchange,
adding a boolean parameter that indicates whether the connection is
closed after the exchange function is executed.

See gh-29552

Author: poutsma

spring-web/src/main/java/org/springframework/web/client/DefaultRestClient.java

@@ -360,8 +360,8 @@ public ResponseSpec retrieve() {
 		}
 
 		@Override
-		public <T> T exchange(ExchangeFunction<T> exchangeFunction) {
-			return exchangeInternal(exchangeFunction, true);
+		public <T> T exchange(ExchangeFunction<T> exchangeFunction, boolean close) {
+			return exchangeInternal(exchangeFunction, close);
 		}
 
 		private <T> T exchangeInternal(ExchangeFunction<T> exchangeFunction, boolean close) {

spring-web/src/main/java/org/springframework/web/client/RestClient.java

@@ -548,7 +548,38 @@ interface RequestHeadersSpec<S extends RequestHeadersSpec<S>> {
 		 * @param <T> the type the response will be transformed to
 		 * @return the value returned from the exchange function
 		 */
-		<T> T exchange(ExchangeFunction<T> exchangeFunction);
+		default <T> T exchange(ExchangeFunction<T> exchangeFunction) {
+			return exchange(exchangeFunction, true);
+		}
+
+		/**
+		 * Exchange the {@link ClientHttpResponse} for a type {@code T}. This
+		 * can be useful for advanced scenarios, for example to decode the
+		 * response differently depending on the response status:
+		 * <p><pre>
+		 * Person person = client.get()
+		 *     .uri("/people/1")
+		 *     .accept(MediaType.APPLICATION_JSON)
+		 *     .exchange((request, response) -&gt; {
+		 *         if (response.getStatusCode().equals(HttpStatus.OK)) {
+		 *             return deserialize(response.getBody());
+		 *         }
+		 *         else {
+		 *             throw new BusinessException();
+		 *         }
+		 *     });
+		 * </pre>
+		 * <p><strong>Note:</strong> If {@code close} is {@code true},
+		 * then the response is {@linkplain ClientHttpResponse#close() closed}
+		 * after the exchange function has been invoked. When set to
+		 * {@code false}, the caller is responsible for closing the response.
+		 * @param exchangeFunction the function to handle the response with
+		 * @param close {@code true} to close the response after
+		 * {@code exchangeFunction} is invoked, {@code false} to keep it open
+		 * @param <T> the type the response will be transformed to
+		 * @return the value returned from the exchange function
+		 */
+		<T> T exchange(ExchangeFunction<T> exchangeFunction, boolean close);
 
 
 		/**