Support custom HTTP method for @HttpExchange

Closes gh-28504

Author: rstoyanchev

spring-web/src/main/java/org/springframework/web/service/annotation/HeadExchange.java

@@ -26,22 +26,23 @@
 import org.springframework.web.bind.annotation.Mapping;
 
 /**
- * Annotation that declares an HTTP service method as an HTTP endpoint defined
- * through attributes of the annotation and method argument values.
+ * Annotation to declare a method on an HTTP service interface as an HTTP
+ * endpoint. The endpoint details are defined statically through attributes of
+ * the annotation, as well as through the input method argument values.
  *
- * <p>The annotation may only be used at the type level &mdash; for example to
- * specify a base URL path. At the method level, use one of the HTTP method
- * specific, shortcut annotations, each of which is <em>meta-annotated</em> with
- * {@code HttpExchange}:
+ * <p>Supported at the type level to express common attributes, to be inherited
+ * by all methods, such as a base URL path.
+ *
+ * <p>At the method level, it's more common to use one of the below HTTP method
+ * specific, shortcut annotation, each of which is itself <em>meta-annotated</em>
+ * with {@code HttpExchange}:
  *
  * <ul>
  * <li>{@link GetExchange}
  * <li>{@link PostExchange}
  * <li>{@link PutExchange}
  * <li>{@link PatchExchange}
  * <li>{@link DeleteExchange}
- * <li>{@link OptionsExchange}
- * <li>{@link HeadExchange}
  * </ul>
  *
  * <p>Supported method arguments:
@@ -100,7 +101,7 @@
  * @author Rossen Stoyanchev
  * @since 6.0
  */
-@Target(ElementType.TYPE)
+@Target({ElementType.TYPE, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
 @Documented
 @Mapping

spring-web/src/main/java/org/springframework/web/service/annotation/HttpExchange.java

@@ -22,12 +22,14 @@
 import org.springframework.core.MethodParameter;
 import org.springframework.http.HttpMethod;
 import org.springframework.lang.Nullable;
+import org.springframework.util.Assert;
 
 /**
  * {@link HttpServiceArgumentResolver} that resolves the target
  * request's HTTP method from an {@link HttpMethod} argument.
  *
  * @author Olga Maciaszek-Sharma
+ * @author Rossen Stoyanchev
  * @since 6.0
  */
 public class HttpMethodArgumentResolver implements HttpServiceArgumentResolver {
@@ -43,12 +45,11 @@ public boolean resolve(
 			return false;
 		}
 
-		if (argument != null) {
-			HttpMethod httpMethod = (HttpMethod) argument;
-			requestValues.setHttpMethod(httpMethod);
-			if (logger.isTraceEnabled()) {
-				logger.trace("Resolved HTTP method to: " + httpMethod.name());
-			}
+		Assert.notNull(argument, "HttpMethod is required");
+		HttpMethod httpMethod = (HttpMethod) argument;
+		requestValues.setHttpMethod(httpMethod);
+		if (logger.isTraceEnabled()) {
+			logger.trace("Resolved HTTP method to: " + httpMethod.name());
 		}
 
 		return true;

spring-web/src/main/java/org/springframework/web/service/annotation/OptionsExchange.java

@@ -56,6 +56,7 @@ public final class HttpRequestValues {
 			CollectionUtils.toMultiValueMap(Collections.emptyMap());
 
 
+	@Nullable
 	private final HttpMethod httpMethod;
 
 	@Nullable
@@ -82,7 +83,7 @@ public final class HttpRequestValues {
 	private final ParameterizedTypeReference<?> bodyElementType;
 
 
-	private HttpRequestValues(HttpMethod httpMethod,
+	private HttpRequestValues(@Nullable HttpMethod httpMethod,
 			@Nullable URI uri, @Nullable String uriTemplate, Map<String, String> uriVariables,
 			HttpHeaders headers, MultiValueMap<String, String> cookies, Map<String, Object> attributes,
 			@Nullable Object bodyValue,
@@ -106,6 +107,7 @@ private HttpRequestValues(HttpMethod httpMethod,
 	/**
 	 * Return the HTTP method to use for the request.
 	 */
+	@Nullable
 	public HttpMethod getHttpMethod() {
 		return this.httpMethod;
 	}
@@ -187,8 +189,8 @@ public ParameterizedTypeReference<?> getBodyElementType() {
 	}
 
 
-	public static Builder builder(HttpMethod httpMethod) {
-		return new Builder(httpMethod);
+	public static Builder builder() {
+		return new Builder();
 	}
 
 
@@ -199,6 +201,7 @@ public final static class Builder {
 
 		private static final Function<MultiValueMap<String, String>, byte[]> FORM_DATA_SERIALIZER = new FormDataSerializer();
 
+		@Nullable
 		private HttpMethod httpMethod;
 
 		@Nullable
@@ -231,16 +234,10 @@ public final static class Builder {
 		@Nullable
 		private ParameterizedTypeReference<?> bodyElementType;
 
-		private Builder(HttpMethod httpMethod) {
-			Assert.notNull(httpMethod, "HttpMethod is required");
-			this.httpMethod = httpMethod;
-		}
-
 		/**
 		 * Set the HTTP method for the request.
 		 */
 		public Builder setHttpMethod(HttpMethod httpMethod) {
-			Assert.notNull(httpMethod, "HttpMethod is required");
 			this.httpMethod = httpMethod;
 			return this;
 		}

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

@@ -131,7 +131,7 @@ private static String formatArgumentError(MethodParameter param, String message)
 	 * and method-level {@link HttpExchange @HttpRequest} annotations.
 	 */
 	private record HttpRequestValuesInitializer(
-			HttpMethod httpMethod, @Nullable String url,
+			@Nullable HttpMethod httpMethod, @Nullable String url,
 			@Nullable MediaType contentType, @Nullable List<MediaType> acceptMediaTypes) {
 
 		private HttpRequestValuesInitializer(
@@ -145,7 +145,10 @@ private HttpRequestValuesInitializer(
 		}
 
 		public HttpRequestValues.Builder initializeRequestValuesBuilder() {
-			HttpRequestValues.Builder requestValues = HttpRequestValues.builder(this.httpMethod);
+			HttpRequestValues.Builder requestValues = HttpRequestValues.builder();
+			if (this.httpMethod != null) {
+				requestValues.setHttpMethod(this.httpMethod);
+			}
 			if (this.url != null) {
 				requestValues.setUriTemplate(this.url);
 			}
@@ -178,7 +181,7 @@ public static HttpRequestValuesInitializer create(
 			return new HttpRequestValuesInitializer(httpMethod, url, contentType, acceptableMediaTypes);
 		}
 
-
+		@Nullable
 		private static HttpMethod initHttpMethod(@Nullable HttpExchange typeAnnot, HttpExchange annot) {
 
 			String value1 = (typeAnnot != null ? typeAnnot.method() : null);
@@ -192,7 +195,7 @@ private static HttpMethod initHttpMethod(@Nullable HttpExchange typeAnnot, HttpE
 				return HttpMethod.valueOf(value1);
 			}
 
-			throw new IllegalStateException("HttpMethod is required");
+			return null;
 		}
 
 		@Nullable

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

@@ -20,9 +20,12 @@
 import org.junit.jupiter.api.Test;
 
 import org.springframework.http.HttpMethod;
+import org.springframework.lang.Nullable;
 import org.springframework.web.service.annotation.GetExchange;
+import org.springframework.web.service.annotation.HttpExchange;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatIllegalArgumentException;
 import static org.assertj.core.api.Assertions.assertThatIllegalStateException;
 
 /**
@@ -47,11 +50,17 @@ void setUp() throws Exception {
 
 
 	@Test
-	void requestMethodOverride() {
+	void httpMethodFromArgument() {
 		this.service.execute(HttpMethod.POST);
 		assertThat(getActualMethod()).isEqualTo(HttpMethod.POST);
 	}
 
+	@Test
+	void httpMethodFromAnnotation() {
+		this.service.executeHttpHead();
+		assertThat(getActualMethod()).isEqualTo(HttpMethod.HEAD);
+	}
+
 	@Test
 	void notHttpMethod() {
 		assertThatIllegalStateException()
@@ -63,21 +72,24 @@ void notHttpMethod() {
 	}
 
 	@Test
-	void ignoreNull() {
-		this.service.execute(null);
-		assertThat(getActualMethod()).isEqualTo(HttpMethod.GET);
+	void nullHttpMethod() {
+		assertThatIllegalArgumentException().isThrownBy(() -> this.service.execute(null));
 	}
 
+	@Nullable
 	private HttpMethod getActualMethod() {
 		return this.client.getRequestValues().getHttpMethod();
 	}
 
 
 	private interface Service {
 
-		@GetExchange
+		@HttpExchange
 		void execute(HttpMethod method);
 
+		@HttpExchange(method = "HEAD")
+		void executeHttpHead();
+
 		@GetExchange
 		void executeNotHttpMethod(String test);
 

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

@@ -38,7 +38,7 @@ public class HttpRequestValuesTests {
 
 	@Test
 	void defaultUri() {
-		HttpRequestValues requestValues = HttpRequestValues.builder(HttpMethod.GET).build();
+		HttpRequestValues requestValues = HttpRequestValues.builder().setHttpMethod(HttpMethod.GET).build();
 
 		assertThat(requestValues.getUri()).isNull();
 		assertThat(requestValues.getUriTemplate()).isEqualTo("");
@@ -48,7 +48,7 @@ void defaultUri() {
 	@ValueSource(strings = {"POST", "PUT", "PATCH"})
 	void requestParamAsFormData(String httpMethod) {
 
-		HttpRequestValues requestValues = HttpRequestValues.builder(HttpMethod.valueOf(httpMethod))
+		HttpRequestValues requestValues = HttpRequestValues.builder().setHttpMethod(HttpMethod.valueOf(httpMethod))
 				.setContentType(MediaType.APPLICATION_FORM_URLENCODED)
 				.addRequestParameter("param1", "1st value")
 				.addRequestParameter("param2", "2nd value A", "2nd value B")
@@ -62,7 +62,7 @@ void requestParamAsFormData(String httpMethod) {
 	@Test
 	void requestParamAsQueryParamsInUriTemplate() {
 
-		HttpRequestValues requestValues = HttpRequestValues.builder(HttpMethod.POST)
+		HttpRequestValues requestValues = HttpRequestValues.builder().setHttpMethod(HttpMethod.POST)
 				.setUriTemplate("/path")
 				.addRequestParameter("param1", "1st value")
 				.addRequestParameter("param2", "2nd value A", "2nd value B")
@@ -96,7 +96,7 @@ void requestParamAsQueryParamsInUriTemplate() {
 	@Test
 	void requestParamAsQueryParamsInUri() {
 
-		HttpRequestValues requestValues = HttpRequestValues.builder(HttpMethod.POST)
+		HttpRequestValues requestValues = HttpRequestValues.builder().setHttpMethod(HttpMethod.POST)
 				.setUri(URI.create("/path"))
 				.addRequestParameter("param1", "1st value")
 				.addRequestParameter("param2", "2nd value A", "2nd value B")

spring-web/src/test/java/org/springframework/web/service/invoker/HttpMethodArgumentResolverTests.java

@@ -86,7 +86,7 @@ public <T> Mono<ResponseEntity<Flux<T>>> requestToEntityFlux(HttpRequestValues r
 	private WebClient.RequestBodySpec toBodySpec(HttpRequestValues requestValues) {
 
 		HttpMethod httpMethod = requestValues.getHttpMethod();
-		Assert.notNull(httpMethod, "No HttpMethod");
+		Assert.notNull(httpMethod, "HttpMethod is required");
 
 		WebClient.RequestBodyUriSpec uriSpec = this.webClient.method(httpMethod);