Support 404 handling for HttpExchange interfaces

Closes gh-32105

Author: rstoyanchev

framework-docs/modules/ROOT/pages/integration/rest-clients.adoc

@@ -1141,6 +1141,34 @@ documentation for each client, as well as the Javadoc of `defaultStatusHandler`
 
 
 
+[[rest-http-interface-adapter-decorator]]
+=== Decorating the Adapter
+
+`HttpExchangeAdapter` and `ReactorHttpExchangeAdapter` are contracts that decouple HTTP
+Interface client infrastructure from the details of invoking the underlying
+client. There are adapter implementations for `RestClient`, `WebClient`, and
+`RestTemplate`.
+
+Occasionally, it may be useful to intercept client invocations through a decorator
+configurable in the `HttpServiceProxyFactory.Builder`. For example, you can apply
+built-in decorators to suppress 404 exceptions and return a `ResponseEntity` with
+`NOT_FOUND` and a `null` body:
+
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+	// For RestClient
+	HttpServiceProxyFactory factory = HttpServiceProxyFactory.builderFor(restCqlientAdapter)
+			.exchangeAdapterDecorator(NotFoundRestClientAdapterDecorator::new)
+			.build();
+
+	// or for WebClient...
+	HttpServiceProxyFactory proxyFactory = HttpServiceProxyFactory.builderFor(webClientAdapter)
+			.exchangeAdapterDecorator(NotFoundWebClientAdapterDecorator::new)
+			.build();
+----
+
+
+
 [[rest-http-interface-group-config]]
 === HTTP Interface Groups
 

spring-web/src/main/java/org/springframework/web/client/support/NotFoundRestClientAdapterDecorator.java

@@ -0,0 +1,76 @@
+/*
+ * Copyright 2002-present 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.web.client.support;
+
+import org.jspecify.annotations.Nullable;
+
+import org.springframework.core.ParameterizedTypeReference;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.client.HttpClientErrorException;
+import org.springframework.web.service.invoker.HttpExchangeAdapter;
+import org.springframework.web.service.invoker.HttpExchangeAdapterDecorator;
+import org.springframework.web.service.invoker.HttpRequestValues;
+
+/**
+ * {@code HttpExchangeAdapterDecorator} that suppresses the
+ * {@link HttpClientErrorException.NotFound} exception raised on a 404 response
+ * and returns a {@code ResponseEntity} with the status set to
+ * {@link org.springframework.http.HttpStatus#NOT_FOUND} status, or
+ * {@code null} from {@link #exchangeForBody}.
+ *
+ * @author Rossen Stoyanchev
+ * @since 7.0
+ */
+public final class NotFoundRestClientAdapterDecorator extends HttpExchangeAdapterDecorator {
+
+
+	public NotFoundRestClientAdapterDecorator(HttpExchangeAdapter delegate) {
+		super(delegate);
+	}
+
+
+	@Override
+	public <T> @Nullable T exchangeForBody(HttpRequestValues values, ParameterizedTypeReference<T> bodyType) {
+		try {
+			return super.exchangeForBody(values, bodyType);
+		}
+		catch (HttpClientErrorException.NotFound ex) {
+			return null;
+		}
+	}
+
+	@Override
+	public ResponseEntity<Void> exchangeForBodilessEntity(HttpRequestValues values) {
+		try {
+			return super.exchangeForBodilessEntity(values);
+		}
+		catch (HttpClientErrorException.NotFound ex) {
+			return ResponseEntity.notFound().build();
+		}
+	}
+
+	@Override
+	public <T> ResponseEntity<T> exchangeForEntity(HttpRequestValues values, ParameterizedTypeReference<T> bodyType) {
+		try {
+			return super.exchangeForEntity(values, bodyType);
+		}
+		catch (HttpClientErrorException.NotFound ex) {
+			return ResponseEntity.notFound().build();
+		}
+	}
+
+}

spring-web/src/main/java/org/springframework/web/service/invoker/HttpServiceProxyFactory.java

@@ -140,10 +140,10 @@ public static final class Builder {
 
 		private final List<HttpServiceArgumentResolver> customArgumentResolvers = new ArrayList<>();
 
-		private final List<HttpRequestValues.Processor> requestValuesProcessors = new ArrayList<>();
-
 		private @Nullable ConversionService conversionService;
 
+		private final List<HttpRequestValues.Processor> requestValuesProcessors = new ArrayList<>();
+
 		private @Nullable StringValueResolver embeddedValueResolver;
 
 		private Builder() {
@@ -182,25 +182,25 @@ public Builder customArgumentResolver(HttpServiceArgumentResolver resolver) {
 		}
 
 		/**
-		 * Register an {@link HttpRequestValues} processor that can further
-		 * customize request values based on the method and all arguments.
-		 * @param processor the processor to add
+		 * Set the {@link ConversionService} to use where input values need to
+		 * be formatted as Strings.
+		 * <p>By default, this is {@link DefaultFormattingConversionService}.
 		 * @return this same builder instance
-		 * @since 7.0
 		 */
-		public Builder httpRequestValuesProcessor(HttpRequestValues.Processor processor) {
-			this.requestValuesProcessors.add(processor);
+		public Builder conversionService(ConversionService conversionService) {
+			this.conversionService = conversionService;
 			return this;
 		}
 
 		/**
-		 * Set the {@link ConversionService} to use where input values need to
-		 * be formatted as Strings.
-		 * <p>By default this is {@link DefaultFormattingConversionService}.
+		 * Register an {@link HttpRequestValues} processor that can further
+		 * customize request values based on the method and all arguments.
+		 * @param processor the processor to add
 		 * @return this same builder instance
+		 * @since 7.0
 		 */
-		public Builder conversionService(ConversionService conversionService) {
-			this.conversionService = conversionService;
+		public Builder httpRequestValuesProcessor(HttpRequestValues.Processor processor) {
+			this.requestValuesProcessors.add(processor);
 			return this;
 		}
 

spring-web/src/main/java/org/springframework/web/service/invoker/ReactorHttpExchangeAdapterDecorator.java

@@ -43,7 +43,7 @@ public ReactorHttpExchangeAdapterDecorator(HttpExchangeAdapter delegate) {
 
 
 	/**
-	 * Return the wrapped delgate {@code HttpExchangeAdapter}.
+	 * Return the wrapped delegate {@code HttpExchangeAdapter}.
 	 */
 	@Override
 	public ReactorHttpExchangeAdapter getHttpExchangeAdapter() {

spring-web/src/test/java/org/springframework/web/client/support/RestClientAdapterTests.java

@@ -28,6 +28,7 @@
 import java.util.Optional;
 import java.util.Set;
 import java.util.function.BiFunction;
+import java.util.function.Consumer;
 import java.util.stream.Stream;
 
 import io.micrometer.observation.tck.TestObservationRegistry;
@@ -79,17 +80,15 @@
 @SuppressWarnings("JUnitMalformedDeclaration")
 class RestClientAdapterTests {
 
-	private final MockWebServer anotherServer = anotherServer();
+	private final MockWebServer anotherServer = new MockWebServer();
 
 
-	@SuppressWarnings("ConstantValue")
 	@AfterEach
 	void shutdown() throws IOException {
-		if (this.anotherServer != null) {
-			this.anotherServer.shutdown();
-		}
+		this.anotherServer.shutdown();
 	}
 
+
 	@Retention(RetentionPolicy.RUNTIME)
 	@Target(ElementType.METHOD)
 	@ParameterizedTest
@@ -173,6 +172,9 @@ void greetingWithDynamicUri(MockWebServer server, Service service, TestObservati
 
 	@Test
 	void greetingWithApiVersion() throws Exception {
+		prepareResponse(response ->
+				response.setHeader("Content-Type", "text/plain").setBody("Hello Spring 2!"));
+
 		RestClient restClient = RestClient.builder()
 				.baseUrl(anotherServer.url("/").toString())
 				.apiVersionInserter(ApiVersionInserter.useHeader("X-API-Version"))
@@ -181,15 +183,18 @@ void greetingWithApiVersion() throws Exception {
 		RestClientAdapter adapter = RestClientAdapter.create(restClient);
 		Service service = HttpServiceProxyFactory.builderFor(adapter).build().createClient(Service.class);
 
-		String response = service.getGreetingWithVersion();
+		String actualResponse = service.getGreetingWithVersion();
 
 		RecordedRequest request = anotherServer.takeRequest();
 		assertThat(request.getHeader("X-API-Version")).isEqualTo("1.2");
-		assertThat(response).isEqualTo("Hello Spring 2!");
+		assertThat(actualResponse).isEqualTo("Hello Spring 2!");
 	}
 
 	@ParameterizedAdapterTest
 	void getWithUriBuilderFactory(MockWebServer server, Service service) throws InterruptedException {
+		prepareResponse(response ->
+				response.setHeader("Content-Type", "text/plain").setBody("Hello Spring 2!"));
+
 		String url = this.anotherServer.url("/").toString();
 		UriBuilderFactory factory = new DefaultUriBuilderFactory(url);
 
@@ -205,6 +210,9 @@ void getWithUriBuilderFactory(MockWebServer server, Service service) throws Inte
 
 	@ParameterizedAdapterTest
 	void getWithFactoryPathVariableAndRequestParam(MockWebServer server, Service service) throws InterruptedException {
+		prepareResponse(response ->
+				response.setHeader("Content-Type", "text/plain").setBody("Hello Spring 2!"));
+
 		String url = this.anotherServer.url("/").toString();
 		UriBuilderFactory factory = new DefaultUriBuilderFactory(url);
 
@@ -220,6 +228,9 @@ void getWithFactoryPathVariableAndRequestParam(MockWebServer server, Service ser
 
 	@ParameterizedAdapterTest
 	void getWithIgnoredUriBuilderFactory(MockWebServer server, Service service) throws InterruptedException {
+		prepareResponse(response ->
+				response.setHeader("Content-Type", "text/plain").setBody("Hello Spring 2!"));
+
 		URI dynamicUri = server.url("/greeting/123").uri();
 		UriBuilderFactory factory = new DefaultUriBuilderFactory(this.anotherServer.url("/").toString());
 
@@ -306,6 +317,9 @@ void putWithSameNameCookies(MockWebServer server, Service service) throws Except
 
 	@Test
 	void getInputStream() throws Exception {
+		prepareResponse(response ->
+				response.setHeader("Content-Type", "text/plain").setBody("Hello Spring 2!"));
+
 		InputStream inputStream = initService().getInputStream();
 
 		RecordedRequest request = this.anotherServer.takeRequest();
@@ -315,6 +329,9 @@ void getInputStream() throws Exception {
 
 	@Test
 	void postOutputStream() throws Exception {
+		prepareResponse(response ->
+				response.setHeader("Content-Type", "text/plain").setBody("Hello Spring 2!"));
+
 		String body = "test stream";
 		initService().postOutputStream(outputStream -> outputStream.write(body.getBytes()));
 
@@ -323,13 +340,23 @@ void postOutputStream() throws Exception {
 		assertThat(request.getBody().readUtf8()).isEqualTo(body);
 	}
 
-
-	private static MockWebServer anotherServer() {
-		MockWebServer server = new MockWebServer();
+	@Test
+	void handleNotFoundException() {
 		MockResponse response = new MockResponse();
-		response.setHeader("Content-Type", "text/plain").setBody("Hello Spring 2!");
-		server.enqueue(response);
-		return server;
+		response.setResponseCode(404);
+		this.anotherServer.enqueue(response);
+
+		RestClientAdapter clientAdapter = RestClientAdapter.create(
+				RestClient.builder().baseUrl(this.anotherServer.url("/").toString()).build());
+
+		HttpServiceProxyFactory factory = HttpServiceProxyFactory.builderFor(clientAdapter)
+				.exchangeAdapterDecorator(NotFoundRestClientAdapterDecorator::new)
+				.build();
+
+		ResponseEntity<String> responseEntity = factory.createClient(Service.class).getGreetingById("1");
+
+		assertThat(responseEntity.getStatusCode()).isEqualTo(HttpStatus.NOT_FOUND);
+		assertThat(responseEntity.getBody()).isNull();
 	}
 
 	private Service initService() {
@@ -339,6 +366,12 @@ private Service initService() {
 		return HttpServiceProxyFactory.builderFor(adapter).build().createClient(Service.class);
 	}
 
+	private void prepareResponse(Consumer<MockResponse> consumer) {
+		MockResponse response = new MockResponse();
+		consumer.accept(response);
+		this.anotherServer.enqueue(response);
+	}
+
 
 	private interface Service {