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/test/java/org/springframework/http/server/reactive/ServerHttpRequestTests.java

@@ -41,6 +41,7 @@ import static org.mockito.Mockito.*;
  * Unit tests for {@link AbstractServerHttpRequest}.
  *
  * @author Rossen Stoyanchev
+ * @author Sam Brannen
  */
 public class ServerHttpRequestTests {
 
@@ -88,7 +89,6 @@ public class ServerHttpRequestTests {
 
 	@Test
 	public void mutateRequest() throws Exception {
-
 		SslInfo sslInfo = mock(SslInfo.class);
 		ServerHttpRequest request = createHttpRequest("/").mutate().sslInfo(sslInfo).build();
 		assertSame(sslInfo, request.getSslInfo());
@@ -123,6 +123,54 @@ public class ServerHttpRequestTests {
 		assertEquals("name=%E6%89%8E%E6%A0%B9", request.getURI().getRawQuery());
 	}
 
+	@Test
+	@SuppressWarnings("deprecation")
+	public void mutateHeaderByAddingHeaderValues() throws Exception {
+		String headerName = "key";
+		String headerValue1 = "value1";
+		String headerValue2 = "value2";
+
+		ServerHttpRequest request = createHttpRequest("/path");
+		assertNull(request.getHeaders().get(headerName));
+
+		request = request.mutate().header(headerName, headerValue1).build();
+
+		assertNotNull(request.getHeaders().get(headerName));
+		assertEquals(1, request.getHeaders().get(headerName).size());
+		assertEquals(headerValue1, request.getHeaders().get(headerName).get(0));
+
+		request = request.mutate().header(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));
+	}
+
+	@Test
+	public void mutateHeaderBySettingHeaderValues() throws Exception {
+		String headerName = "key";
+		String headerValue1 = "value1";
+		String headerValue2 = "value2";
+		String headerValue3 = "value3";
+
+		ServerHttpRequest request = createHttpRequest("/path");
+		assertNull(request.getHeaders().get(headerName));
+
+		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));
+
+		request = request.mutate().header(headerName, new String[] { headerValue3 }).build();
+
+		assertNotNull(request.getHeaders().get(headerName));
+		assertEquals(1, request.getHeaders().get(headerName).size());
+		assertEquals(headerValue3, request.getHeaders().get(headerName).get(0));
+	}
+
 	private ServerHttpRequest createHttpRequest(String uriString) throws Exception {
 		URI uri = URI.create(uriString);
 		MockHttpServletRequest request = new TestHttpServletRequest(uri);