Introduce ServerHttpRequest.Builder.header() variant for setting headers

Prior to this commit, the `header(String, String)` method in the
ServerHttpRequest.Builder API actually added a header value instead of
setting or overriding a header value. Since this conflicted with the
stated behavior in the Javadoc as well as the original intention of the
method, we have decided to introduce an overloaded variant
`header(String, String...)` which accepts a var-args list of header
values to set or override.

In addition, this commit deprecates the existing `header(String, String)`
method for removal in Spring Framework 5.2.

In order not to be a breaking change for custom implementations of the
builder API, this commit implements the new `header(String, String...)`
method as an interface `default` method, with the intent to remove the
default implementation in Spring Framework 5.2

closes gh-23333

spring-web/src/main/java/org/springframework/http/server/reactive/DefaultServerHttpRequestBuilder.java

@@ -19,6 +19,7 @@ package org.springframework.http.server.reactive;
 import java.net.InetSocketAddress;
 import java.net.URI;
 import java.net.URISyntaxException;
+import java.util.Arrays;
 import java.util.LinkedList;
 import java.util.function.Consumer;
 
@@ -111,9 +112,8 @@ class DefaultServerHttpRequestBuilder implements ServerHttpRequest.Builder {
 	}
 
 	@Override
-	@SuppressWarnings("deprecation")
-	public ServerHttpRequest.Builder header(String key, String value) {
-		this.httpHeaders.add(key, value);
+	public ServerHttpRequest.Builder header(String headerName, String... headerValues) {
+		this.httpHeaders.put(headerName, Arrays.asList(headerValues));
 		return this;
 	}
 

spring-web/src/main/java/org/springframework/http/server/reactive/ServerHttpRequest.java

@@ -18,7 +18,6 @@ package org.springframework.http.server.reactive;
 
 import java.net.InetSocketAddress;
 import java.net.URI;
-import java.util.Arrays;
 import java.util.function.Consumer;
 
 import org.springframework.http.HttpCookie;
@@ -138,30 +137,16 @@ public interface ServerHttpRequest extends HttpRequest, ReactiveHttpInputMessage
 		 */
 		Builder contextPath(String contextPath);
 
-		/**
-		 * Add the given, single header value under the given name.
-		 * @param headerName the header name
-		 * @param headerValue the header value
-		 * @deprecated This method will be removed in Spring Framework 5.2 in
-		 * favor of {@link #header(String, String...)}.
-		 */
-		@Deprecated
-		Builder header(String headerName, String headerValue);
-
 		/**
 		 * Set or override the specified header values under the given name.
-		 * <p>If you need to set a single header value, you may invoke this
-		 * method with an explicit one-element array &mdash; for example,
-		 * <code>header("key", new String[] { "value" })</code> &mdash; or you
-		 * may choose to use {@link #headers(Consumer)} for greater control.
+		 * <p>If you need to add header values, remove headers, etc., use
+		 * {@link #headers(Consumer)} for greater control.
 		 * @param headerName the header name
 		 * @param headerValues the header values
 		 * @since 5.1.9
 		 * @see #headers(Consumer)
 		 */
-		default Builder header(String headerName, String... headerValues) {
-			return headers(httpHeaders -> httpHeaders.put(headerName, Arrays.asList(headerValues)));
-		}
+		Builder header(String headerName, String... headerValues);
 
 		/**
 		 * Manipulate request headers. The provided {@code HttpHeaders} contains

spring-web/src/test/java/org/springframework/http/server/reactive/ServerHttpRequestTests.java

@@ -126,27 +126,21 @@ public class ServerHttpRequestTests {
 	}
 
 	@Test
-	@SuppressWarnings("deprecation")
-	public void mutateHeaderByAddingHeaderValues() throws Exception {
+	public void mutateHeadersViaConsumer() throws Exception {
 		String headerName = "key";
 		String headerValue1 = "value1";
 		String headerValue2 = "value2";
 
 		ServerHttpRequest request = createHttpRequest("/path");
-		assertNull(request.getHeaders().get(headerName));
+		assertThat(request.getHeaders().get(headerName)).isNull();
 
-		request = request.mutate().header(headerName, headerValue1).build();
+		request = request.mutate().headers(headers -> headers.add(headerName, headerValue1)).build();
 
-		assertNotNull(request.getHeaders().get(headerName));
-		assertEquals(1, request.getHeaders().get(headerName).size());
-		assertEquals(headerValue1, request.getHeaders().get(headerName).get(0));
+		assertThat(request.getHeaders().get(headerName)).containsExactly(headerValue1);
 
-		request = request.mutate().header(headerName, headerValue2).build();
+		request = request.mutate().headers(headers -> headers.add(headerName, headerValue2)).build();
 
-		assertNotNull(request.getHeaders().get(headerName));
-		assertEquals(2, request.getHeaders().get(headerName).size());
-		assertEquals(headerValue1, request.getHeaders().get(headerName).get(0));
-		assertEquals(headerValue2, request.getHeaders().get(headerName).get(1));
+		assertThat(request.getHeaders().get(headerName)).containsExactly(headerValue1, headerValue2);
 	}
 
 	@Test
@@ -157,20 +151,15 @@ public class ServerHttpRequestTests {
 		String headerValue3 = "value3";
 
 		ServerHttpRequest request = createHttpRequest("/path");
-		assertNull(request.getHeaders().get(headerName));
+		assertThat(request.getHeaders().get(headerName)).isNull();
 
 		request = request.mutate().header(headerName, headerValue1, headerValue2).build();
 
-		assertNotNull(request.getHeaders().get(headerName));
-		assertEquals(2, request.getHeaders().get(headerName).size());
-		assertEquals(headerValue1, request.getHeaders().get(headerName).get(0));
-		assertEquals(headerValue2, request.getHeaders().get(headerName).get(1));
+		assertThat(request.getHeaders().get(headerName)).containsExactly(headerValue1, headerValue2);
 
-		request = request.mutate().header(headerName, new String[] { headerValue3 }).build();
+		request = request.mutate().header(headerName, headerValue3).build();
 
-		assertNotNull(request.getHeaders().get(headerName));
-		assertEquals(1, request.getHeaders().get(headerName).size());
-		assertEquals(headerValue3, request.getHeaders().get(headerName).get(0));
+		assertThat(request.getHeaders().get(headerName)).containsExactly(headerValue3);
 	}
 
 	private ServerHttpRequest createHttpRequest(String uriString) throws Exception {