Add since and forRemoval to @deprecated

Author: rstoyanchev

spring-web/src/main/java/org/springframework/http/HttpEntity.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 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.
@@ -107,9 +107,9 @@ public HttpEntity(@Nullable T body, @Nullable HttpHeaders headers) {
 	/**
 	 * Create a new {@code HttpEntity} with the given headers and no body.
 	 * @param headers the entity headers
-	 * @deprecated Use {@link #HttpEntity(HttpHeaders)}
+	 * @deprecated in favor of {@link #HttpEntity(HttpHeaders)}
 	 */
-	@Deprecated
+	@Deprecated(since = "7.0", forRemoval = true)
 	public HttpEntity(MultiValueMap<String, String> headers) {
 		this(null, headers);
 	}
@@ -118,9 +118,9 @@ public HttpEntity(MultiValueMap<String, String> headers) {
 	 * Create a new {@code HttpEntity} with the given body and headers.
 	 * @param body the entity body
 	 * @param headers the entity headers
-	 * @deprecated Use {@link #HttpEntity(Object, HttpHeaders)}
+	 * @deprecated in favor of {@link #HttpEntity(Object, HttpHeaders)}
 	 */
-	@Deprecated
+	@Deprecated(since = "7.0", forRemoval = true)
 	public HttpEntity(@Nullable T body, @Nullable MultiValueMap<String, String> headers) {
 		this.body = body;
 		this.headers = HttpHeaders.readOnlyHttpHeaders(headers != null ? new HttpHeaders(headers) : new HttpHeaders());

spring-web/src/main/java/org/springframework/http/HttpHeaders.java

@@ -1847,11 +1847,11 @@ public Map<String, String> toSingleValueMap() {
 	 * casing variants of a given header name, see {@link #asMultiValueMap()}
 	 * javadoc.
 	 * @return a single value representation of these headers
-	 * @deprecated Use {@link #toSingleValueMap()} which performs a copy but
+	 * @deprecated in favor of {@link #toSingleValueMap()} which performs a copy but
 	 * ensures that collection-iterating methods like {@code entrySet()} are
 	 * case-insensitive
 	 */
-	@Deprecated
+	@Deprecated(since = "7.0", forRemoval = true)
 	public Map<String, String> asSingleValueMap() {
 		return this.headers.asSingleValueMap();
 	}
@@ -1870,7 +1870,7 @@ public Map<String, String> asSingleValueMap() {
 	 * that would only accept maps. Generally avoid using HttpHeaders as a Map
 	 * or MultiValueMap.
 	 */
-	@Deprecated
+	@Deprecated(since = "7.0", forRemoval = true)
 	public MultiValueMap<String, String> asMultiValueMap() {
 		return this.headers;
 	}

spring-web/src/main/java/org/springframework/http/ReadOnlyHttpHeaders.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.
@@ -120,14 +120,16 @@ public Map<String, String> toSingleValueMap() {
 		return Collections.unmodifiableMap(this.headers.toSingleValueMap());
 	}
 
+	@SuppressWarnings("removal")
 	@Override
-	@Deprecated
+	@Deprecated(since = "7.0", forRemoval = true)
 	public Map<String, String> asSingleValueMap() {
 		return Collections.unmodifiableMap(this.headers.asSingleValueMap());
 	}
 
+	@SuppressWarnings("removal")
 	@Override
-	@Deprecated
+	@Deprecated(since = "7.0", forRemoval = true)
 	public MultiValueMap<String, String> asMultiValueMap() {
 		return CollectionUtils.unmodifiableMultiValueMap(this.headers);
 	}

spring-web/src/main/java/org/springframework/http/RequestEntity.java

@@ -152,9 +152,9 @@ public RequestEntity(@Nullable T body, @Nullable HttpHeaders headers,
 	 * @param headers the headers
 	 * @param method the method
 	 * @param url the URL
-	 * @deprecated Use {@link #RequestEntity(HttpHeaders, HttpMethod, URI)}
+	 * @deprecated in favor of {@link #RequestEntity(HttpHeaders, HttpMethod, URI)}
 	 */
-	@Deprecated
+	@Deprecated(since = "7.0", forRemoval = true)
 	public RequestEntity(MultiValueMap<String, String> headers, HttpMethod method, URI url) {
 		this(null, headers, method, url, null);
 	}
@@ -165,10 +165,11 @@ public RequestEntity(MultiValueMap<String, String> headers, HttpMethod method, U
 	 * @param headers the headers
 	 * @param method the method
 	 * @param url the URL
-	 * @deprecated Use {@link #RequestEntity(Object, HttpHeaders, HttpMethod, URI)}
+	 * @deprecated in favor of {@link #RequestEntity(Object, HttpHeaders, HttpMethod, URI)}
 	 */
-	@Deprecated
-	public RequestEntity(@Nullable T body, @Nullable MultiValueMap<String, String> headers,
+	@Deprecated(since = "7.0", forRemoval = true)
+	public RequestEntity(
+			@Nullable T body, @Nullable MultiValueMap<String, String> headers,
 			@Nullable HttpMethod method, URI url) {
 
 		this(body, headers, method, url, null);
@@ -182,9 +183,10 @@ public RequestEntity(@Nullable T body, @Nullable MultiValueMap<String, String> h
 	 * @param url the URL
 	 * @param type the type used for generic type resolution
 	 * @since 4.3
-	 * @deprecated Use {@link #RequestEntity(Object, HttpHeaders, HttpMethod, URI, Type)}
+	 * @deprecated in favor of {@link #RequestEntity(Object, HttpHeaders, HttpMethod, URI, Type)}
 	 */
-	@Deprecated
+	@SuppressWarnings("removal")
+	@Deprecated(since = "7.0", forRemoval = true)
 	public RequestEntity(@Nullable T body, @Nullable MultiValueMap<String, String> headers,
 			@Nullable HttpMethod method, @Nullable URI url, @Nullable Type type) {
 

spring-web/src/main/java/org/springframework/http/ResponseEntity.java

@@ -139,9 +139,9 @@ public ResponseEntity(@Nullable T body, @Nullable HttpHeaders headers, HttpStatu
 	 * Create a {@code ResponseEntity} with headers and a status code.
 	 * @param headers the entity headers
 	 * @param status the status code
-	 * @deprecated Use {@link #ResponseEntity(HttpHeaders, HttpStatusCode)}
+	 * @deprecated in favor of {@link #ResponseEntity(HttpHeaders, HttpStatusCode)}
 	 */
-	@Deprecated
+	@Deprecated(since = "7.0", forRemoval = true)
 	public ResponseEntity(MultiValueMap<String, String> headers, HttpStatusCode status) {
 		this(null, headers, status);
 	}
@@ -152,9 +152,9 @@ public ResponseEntity(MultiValueMap<String, String> headers, HttpStatusCode stat
 	 * @param headers the entity headers
 	 * @param rawStatus the status code value
 	 * @since 5.3.2
-	 * @deprecated Use {@link #ResponseEntity(Object, HttpHeaders, int)}
+	 * @deprecated in favor of {@link #ResponseEntity(Object, HttpHeaders, int)}
 	 */
-	@Deprecated
+	@Deprecated(since = "7.0", forRemoval = true)
 	public ResponseEntity(@Nullable T body, @Nullable MultiValueMap<String, String> headers, int rawStatus) {
 		this(body, headers, HttpStatusCode.valueOf(rawStatus));
 	}
@@ -164,9 +164,10 @@ public ResponseEntity(@Nullable T body, @Nullable MultiValueMap<String, String>
 	 * @param body the entity body
 	 * @param headers the entity headers
 	 * @param statusCode the status code
-	 * @deprecated Use {@link #ResponseEntity(Object, HttpHeaders, HttpStatusCode)}
+	 * @deprecated in favor of {@link #ResponseEntity(Object, HttpHeaders, HttpStatusCode)}
 	 */
-	@Deprecated
+	@SuppressWarnings("removal")
+	@Deprecated(since = "7.0", forRemoval = true)
 	public ResponseEntity(@Nullable T body, @Nullable MultiValueMap<String, String> headers, HttpStatusCode statusCode) {
 		super(body, headers);
 		Assert.notNull(statusCode, "HttpStatusCode must not be null");

spring-web/src/main/java/org/springframework/web/cors/UrlBasedCorsConfigurationSource.java

@@ -93,7 +93,7 @@ public UrlBasedCorsConfigurationSource(PathPatternParser parser) {
 	 * {@link #setUrlPathHelper(UrlPathHelper)}, if at all. For further details,
 	 * please see {@link #setAllowInitLookupPath(boolean)}.
 	 */
-	@Deprecated
+	@Deprecated(since = "5.3", forRemoval = true)
 	public void setAlwaysUseFullPath(boolean alwaysUseFullPath) {
 		initUrlPathHelper();
 		this.urlPathHelper.setAlwaysUseFullPath(alwaysUseFullPath);
@@ -107,7 +107,7 @@ public void setAlwaysUseFullPath(boolean alwaysUseFullPath) {
 	 * {@link #setUrlPathHelper(UrlPathHelper)}, if at all. For further details,
 	 * please see {@link #setAllowInitLookupPath(boolean)}.
 	 */
-	@Deprecated
+	@Deprecated(since = "5.3", forRemoval = true)
 	public void setUrlDecode(boolean urlDecode) {
 		initUrlPathHelper();
 		this.urlPathHelper.setUrlDecode(urlDecode);
@@ -121,7 +121,7 @@ public void setUrlDecode(boolean urlDecode) {
 	 * {@link #setUrlPathHelper(UrlPathHelper)}, if at all. For further details,
 	 * please see {@link #setAllowInitLookupPath(boolean)}.
 	 */
-	@Deprecated
+	@Deprecated(since = "5.3", forRemoval = true)
 	public void setRemoveSemicolonContent(boolean removeSemicolonContent) {
 		initUrlPathHelper();
 		this.urlPathHelper.setRemoveSemicolonContent(removeSemicolonContent);

spring-web/src/test/java/org/springframework/http/HttpEntityTests.java

@@ -20,9 +20,6 @@
 
 import org.junit.jupiter.api.Test;
 
-import org.springframework.util.LinkedMultiValueMap;
-import org.springframework.util.MultiValueMap;
-
 import static org.assertj.core.api.Assertions.assertThat;
 
 /**
@@ -51,11 +48,10 @@ void httpHeaders() {
 
 	@Test
 	void multiValueMap() {
-		MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
-		map.set("Content-Type", "text/plain");
+		HttpHeaders headers = new HttpHeaders();
+		headers.set("Content-Type", "text/plain");
 		String body = "foo";
-		@SuppressWarnings("deprecation")
-		HttpEntity<String> entity = new HttpEntity<>(body, map);
+		HttpEntity<String> entity = new HttpEntity<>(body, headers);
 		assertThat(entity.getBody()).isEqualTo(body);
 		assertThat(entity.getHeaders().getContentType()).isEqualTo(MediaType.TEXT_PLAIN);
 		assertThat(entity.getHeaders().getFirst("Content-Type")).isEqualTo("text/plain");

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

@@ -133,10 +133,9 @@ void copyUsingEntrySetPutRemovesDuplicates(MultiValueMap<String, String> headers
 		assertThat(headers2.get("TestHeader")).as("TestHeader")
 				.containsExactly("first", "second", "third");
 		// Ordering and casing are not guaranteed using the entrySet+put approach
-		assertThat(headers2.asMultiValueMap()).as("two keys")
-				.containsKey("testheader")
-				.containsKey("secondheader")
-				.hasSize(2);
+		assertThat(headers2.containsHeader("testheader")).isTrue();
+		assertThat(headers2.containsHeader("secondheader")).isTrue();
+		assertThat(headers2.size()).isEqualTo(2);
 		assertThat(headers2.toString()).as("no 'with native headers' dump")
 				.doesNotContain("with native headers");
 	}
@@ -150,10 +149,9 @@ void copyUsingPutAllRemovesDuplicates(MultiValueMap<String, String> headers) {
 		assertThat(headers2.get("TestHeader")).as("TestHeader")
 				.containsExactly("first", "second", "third");
 		// Ordering and casing are not guaranteed using the putAll approach
-		assertThat(headers2.asMultiValueMap()).as("two keys")
-				.containsKey("testheader")
-				.containsKey("secondheader")
-				.hasSize(2);
+		assertThat(headers2.containsHeader("testheader")).isTrue();
+		assertThat(headers2.containsHeader("secondheader")).isTrue();
+		assertThat(headers2.size()).isEqualTo(2);
 		assertThat(headers2.toString()).as("similar toString, no 'with native headers' dump")
 				.isEqualToIgnoringCase(headers.toString().substring(0, headers.toString().indexOf(']') + 1));
 	}

spring-web/src/test/java/org/springframework/web/ErrorResponseTests.java

@@ -16,13 +16,10 @@
 
 package org.springframework.web;
 
-import java.util.List;
-
 import org.junit.jupiter.api.Test;
 
 import org.springframework.http.HttpStatus;
 
-import static java.util.Map.entry;
 import static org.assertj.core.api.Assertions.assertThat;
 
 /**
@@ -33,24 +30,24 @@
 class ErrorResponseTests {
 
 	@Test
-	@SuppressWarnings("deprecation")
 	void createWithHttpHeader() {
-		ErrorResponse response = ErrorResponse.builder(new IllegalStateException(), HttpStatus.BAD_REQUEST, "test")
-				.header("header", "value").build();
-		assertThat(response.getHeaders().asMultiValueMap()).containsOnly(entry("header", List.of("value")));
+		ErrorResponse response = ErrorResponse
+				.builder(new IllegalStateException(), HttpStatus.BAD_REQUEST, "test")
+				.header("header", "value")
+				.build();
+		assertThat(response.getHeaders().containsHeaderValue("header", "value")).isTrue();
 	}
 
 	@Test
-	@SuppressWarnings("deprecation")
 	void createWithHttpHeadersConsumer() {
 		ErrorResponse response = ErrorResponse.builder(new IllegalStateException(), HttpStatus.BAD_REQUEST, "test")
 				.header("header", "value")
 				.headers(headers -> {
 					headers.add("header", "value2");
 					headers.add("another", "value3");
 				}).build();
-		assertThat(response.getHeaders().asMultiValueMap()).containsOnly(entry("header", List.of("value", "value2")),
-				entry("another", List.of("value3")));
+		assertThat(response.getHeaders().get("header")).containsExactly("value", "value2");
+		assertThat(response.getHeaders().get("another")).containsExactly("value3");
 	}
 
 }

spring-web/src/testFixtures/java/org/springframework/web/testfixture/http/server/reactive/MockServerHttpRequest.java

@@ -282,9 +282,9 @@ public interface BaseBuilder<B extends BaseBuilder<B>> {
 		/**
 		 * Add the given header values.
 		 * @param headers the header values
-		 * @deprecated Use {@link #headers(HttpHeaders)}
+		 * @deprecated in favor of {@link #headers(HttpHeaders)}
 		 */
-		@Deprecated
+		@Deprecated(since = "7.0", forRemoval = true)
 		B headers(MultiValueMap<String, String> headers);
 
 		/**
@@ -483,7 +483,7 @@ public BodyBuilder header(String headerName, String... headerValues) {
 		}
 
 		@Override
-		@Deprecated
+		@Deprecated(since = "7.0", forRemoval = true)
 		public BodyBuilder headers(MultiValueMap<String, String> headers) {
 			this.headers.putAll(headers);
 			return this;