Merge branch '6.2.x'

Author: sdeleuze

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

@@ -537,6 +537,13 @@ public ResponseSpec retrieve() {
 			return exchangeInternal(exchangeFunction, close);
 		}
 
+		@Override
+		public <T> T exchangeForRequiredValue(RequiredValueExchangeFunction<T> exchangeFunction, boolean close) {
+			T value = exchangeInternal(exchangeFunction, close);
+			Assert.state(value != null, "The exchanged value must not be null");
+			return value;
+		}
+
 		private <T> @Nullable T exchangeInternal(ExchangeFunction<T> exchangeFunction, boolean close) {
 			Assert.notNull(exchangeFunction, "ExchangeFunction must not be null");
 

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

@@ -679,8 +679,8 @@ interface RequestHeadersSpec<S extends RequestHeadersSpec<S>> {
 		ResponseSpec retrieve();
 
 		/**
-		 * Exchange the {@link ClientHttpResponse} for a type {@code T}. This
-		 * can be useful for advanced scenarios, for example to decode the
+		 * Exchange the {@link ClientHttpResponse} for a value of type {@code T}.
+		 * This can be useful for advanced scenarios, for example to decode the
 		 * response differently depending on the response status:
 		 * <pre class="code">
 		 * Person person = client.get()
@@ -700,15 +700,44 @@ interface RequestHeadersSpec<S extends RequestHeadersSpec<S>> {
 		 * function has been invoked.
 		 * @param exchangeFunction the function to handle the response with
 		 * @param <T> the type the response will be transformed to
-		 * @return the value returned from the exchange function
+		 * @return the value returned from the exchange function, potentially {@code null}
+		 * @see RequestHeadersSpec#exchangeForRequiredValue(RequiredValueExchangeFunction)
 		 */
 		default <T> @Nullable 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
+		 * Exchange the {@link ClientHttpResponse} for a value of type {@code T}.
+		 * This can be useful for advanced scenarios, for example to decode the
+		 * response differently depending on the response status:
+		 * <pre class="code">
+		 * 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> The response is
+		 * {@linkplain ClientHttpResponse#close() closed} after the exchange
+		 * function has been invoked.
+		 * @param exchangeFunction the function to handle the response with
+		 * @param <T> the type the response will be transformed to
+		 * @return the value returned from the exchange function, never {@code null}
+		 */
+		default <T> T exchangeForRequiredValue(RequiredValueExchangeFunction<T> exchangeFunction) {
+			return exchangeForRequiredValue(exchangeFunction, true);
+		}
+
+		/**
+		 * Exchange the {@link ClientHttpResponse} for a value of type {@code T}.
+		 * This can be useful for advanced scenarios, for example to decode the
 		 * response differently depending on the response status:
 		 * <pre class="code">
 		 * Person person = client.get()
@@ -731,10 +760,40 @@ interface RequestHeadersSpec<S extends RequestHeadersSpec<S>> {
 		 * @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
+		 * @return the value returned from the exchange function, potentially {@code null}
+		 * @see RequestHeadersSpec#exchangeForRequiredValue(RequiredValueExchangeFunction, boolean)
 		 */
 		<T> @Nullable T exchange(ExchangeFunction<T> exchangeFunction, boolean close);
 
+		/**
+		 * Exchange the {@link ClientHttpResponse} for a value of type {@code T}.
+		 * This can be useful for advanced scenarios, for example to decode the
+		 * response differently depending on the response status:
+		 * <pre class="code">
+		 * 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, never {@code null}
+		 */
+		<T> T exchangeForRequiredValue(RequiredValueExchangeFunction<T> exchangeFunction, boolean close);
+
 
 		/**
 		 * Defines the contract for {@link #exchange(ExchangeFunction)}.
@@ -744,15 +803,31 @@ interface RequestHeadersSpec<S extends RequestHeadersSpec<S>> {
 		interface ExchangeFunction<T> {
 
 			/**
-			 * Exchange the given response into a type {@code T}.
+			 * Exchange the given response into a value of type {@code T}.
 			 * @param clientRequest the request
 			 * @param clientResponse the response
-			 * @return the exchanged type
+			 * @return the exchanged value, potentially {@code null}
 			 * @throws IOException in case of I/O errors
 			 */
 			@Nullable T exchange(HttpRequest clientRequest, ConvertibleClientHttpResponse clientResponse) throws IOException;
 		}
 
+		/**
+		 * Variant of {@link ExchangeFunction} returning a non-null required value.
+		 * @param <T> the type the response will be transformed to
+		 */
+		@FunctionalInterface
+		interface RequiredValueExchangeFunction<T> extends ExchangeFunction<T> {
+
+			/**
+			 * Exchange the given response into a value of type {@code T}.
+			 * @param clientRequest the request
+			 * @param clientResponse the response
+			 * @return the exchanged value, never {@code null}
+			 * @throws IOException in case of I/O errors
+			 */
+			T exchange(HttpRequest clientRequest, ConvertibleClientHttpResponse clientResponse) throws IOException;
+		}
 
 		/**
 		 * Extension of {@link ClientHttpResponse} that can convert the body.

Diff for: spring-web/src/main/kotlin/org/springframework/web/client/RestClientExtensions.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2025 the original author or authors.
+ * Copyright 2002-2024 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.
@@ -18,8 +18,6 @@ package org.springframework.web.client
 
 import org.springframework.core.ParameterizedTypeReference
 import org.springframework.http.ResponseEntity
-import org.springframework.web.client.RestClient.RequestHeadersSpec
-import org.springframework.web.client.RestClient.RequestHeadersSpec.ExchangeFunction
 
 /**
  * Extension for [RestClient.RequestBodySpec.body] providing a `bodyWithType<Foo>(...)` variant
@@ -53,15 +51,6 @@ inline fun <reified T : Any> RestClient.ResponseSpec.body(): T? =
 inline fun <reified T : Any> RestClient.ResponseSpec.requiredBody(): T =
     body(object : ParameterizedTypeReference<T>() {}) ?: throw NoSuchElementException("Response body is required")
 
-/**
- * Extension for [RestClient.RequestHeadersSpec.exchange] providing a `requiredExchange(...)` variant with a
- * non-nullable return value.
- * @throws NoSuchElementException if there is no response value
- * @since 6.2.6
- */
-fun <T: Any> RequestHeadersSpec<*>.requiredExchange(exchangeFunction: ExchangeFunction<T>, close: Boolean = true): T =
-	exchange(exchangeFunction, close) ?: throw NoSuchElementException("Response value is required")
-
 /**
  * Extension for [RestClient.ResponseSpec.toEntity] providing a `toEntity<Foo>()` variant
  * leveraging Kotlin reified type parameters. This extension is not subject to type
@@ -71,5 +60,4 @@ fun <T: Any> RequestHeadersSpec<*>.requiredExchange(exchangeFunction: ExchangeFu
  * @since 6.1
  */
 inline fun <reified T : Any> RestClient.ResponseSpec.toEntity(): ResponseEntity<T> =
-	toEntity(object : ParameterizedTypeReference<T>() {})
-
+	toEntity(object : ParameterizedTypeReference<T>() {})

Diff for: spring-web/src/test/java/org/springframework/web/client/RestClientIntegrationTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 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.
@@ -59,6 +59,7 @@
 import static java.nio.charset.StandardCharsets.UTF_8;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.assertj.core.api.Assertions.assertThatIllegalStateException;
 import static org.junit.jupiter.api.Assumptions.assumeFalse;
 import static org.junit.jupiter.params.provider.Arguments.argumentSet;
 
@@ -765,6 +766,39 @@ void exchangeFor404(ClientHttpRequestFactory requestFactory) {
 		expectRequest(request -> assertThat(request.getPath()).isEqualTo("/greeting"));
 	}
 
+	@ParameterizedRestClientTest
+	void exchangeForRequiredValue(ClientHttpRequestFactory requestFactory) {
+		startServer(requestFactory);
+
+		prepareResponse(response -> response.setBody("Hello Spring!"));
+
+		String result = this.restClient.get()
+				.uri("/greeting")
+				.header("X-Test-Header", "testvalue")
+				.exchangeForRequiredValue((request, response) -> new String(RestClientUtils.getBody(response), UTF_8));
+
+		assertThat(result).isEqualTo("Hello Spring!");
+
+		expectRequestCount(1);
+		expectRequest(request -> {
+			assertThat(request.getHeader("X-Test-Header")).isEqualTo("testvalue");
+			assertThat(request.getPath()).isEqualTo("/greeting");
+		});
+	}
+
+	@ParameterizedRestClientTest
+	@SuppressWarnings("DataFlowIssue")
+	void exchangeForNullRequiredValue(ClientHttpRequestFactory requestFactory) {
+		startServer(requestFactory);
+
+		prepareResponse(response -> response.setBody("Hello Spring!"));
+
+		assertThatIllegalStateException().isThrownBy(() -> this.restClient.get()
+				.uri("/greeting")
+				.header("X-Test-Header", "testvalue")
+				.exchangeForRequiredValue((request, response) -> null));
+	}
+
 	@ParameterizedRestClientTest
 	void requestInitializer(ClientHttpRequestFactory requestFactory) {
 		startServer(requestFactory);

Diff for: spring-web/src/test/kotlin/org/springframework/web/client/RestClientExtensionsTests.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2025 the original author or authors.
+ * Copyright 2002-2024 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.
@@ -19,12 +19,9 @@ package org.springframework.web.client
 import io.mockk.every
 import io.mockk.mockk
 import io.mockk.verify
-import org.assertj.core.api.Assertions.assertThat
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.assertThrows
 import org.springframework.core.ParameterizedTypeReference
-import org.springframework.http.HttpRequest
-import org.springframework.web.client.RestClient.RequestHeadersSpec
 
 /**
  * Mock object based tests for [RestClient] Kotlin extensions
@@ -62,24 +59,6 @@ class RestClientExtensionsTests {
 		assertThrows<NoSuchElementException> { responseSpec.requiredBody<Foo>() }
 	}
 
-	@Test
-	fun `RequestHeadersSpec#requiredExchange`() {
-		val foo = Foo()
-		every { requestBodySpec.exchange(any<RequestHeadersSpec.ExchangeFunction<Foo>>(), any()) } returns foo
-		val exchangeFunction: (HttpRequest, RequestHeadersSpec.ConvertibleClientHttpResponse) -> Foo? =
-			{ _, _ -> foo }
-		val value = requestBodySpec.requiredExchange(exchangeFunction)
-		assertThat(value).isEqualTo(foo)
-	}
-
-	@Test
-	fun `RequestHeadersSpec#requiredExchange with null response throws NoSuchElementException`() {
-		every { requestBodySpec.exchange(any<RequestHeadersSpec.ExchangeFunction<Foo>>(), any()) } returns null
-		val exchangeFunction: (HttpRequest, RequestHeadersSpec.ConvertibleClientHttpResponse) -> Foo? =
-			{ _, _ -> null }
-		assertThrows<NoSuchElementException> { requestBodySpec.requiredExchange(exchangeFunction) }
-	}
-
 	@Test
 	fun `ResponseSpec#toEntity with reified type parameters`() {
 		responseSpec.toEntity<List<Foo>>()