Add handling of deprecated API versions

See gh-35049

Author: rstoyanchev

spring-web/src/main/java/org/springframework/web/accept/ApiDeprecationHandler.java

@@ -0,0 +1,43 @@
+/*
+ * 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.accept;
+
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+
+/**
+ * Contract to add handling of requests with a deprecated API version. Typically,
+ * this involves use of response headers to send hints and information about
+ * the deprecation to clients.
+ *
+ * @author Rossen Stoyanchev
+ * @since 7.0
+ * @see StandardApiDeprecationHandler
+ */
+public interface ApiDeprecationHandler {
+
+	/**
+	 * Check if the requested API version is deprecated, and if so handle it
+	 * accordingly, e.g. by setting response headers to signal the deprecation,
+	 * to specify relevant dates and provide links to further details.
+	 * @param version the resolved and parsed request version
+	 * @param request the current request
+	 * @param response the current response
+	 */
+	void handleVersion(Comparable<?> version, HttpServletRequest request, HttpServletResponse response);
+
+}

spring-web/src/main/java/org/springframework/web/accept/ApiVersionStrategy.java

@@ -17,6 +17,7 @@
 package org.springframework.web.accept;
 
 import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -25,13 +26,15 @@
  *
  * @author Rossen Stoyanchev
  * @since 7.0
+ * @see DefaultApiVersionStrategy
  */
 public interface ApiVersionStrategy {
 
 	/**
 	 * Resolve the version value from a request, e.g. from a request header.
 	 * @param request the current request
 	 * @return the version, if present or {@code null}
+	 * @see ApiVersionResolver
 	 */
 	@Nullable
 	String resolveVersion(HttpServletRequest request);
@@ -40,6 +43,7 @@ public interface ApiVersionStrategy {
 	 * Parse the version of a request into an Object.
 	 * @param version the value to parse
 	 * @return an Object that represents the version
+	 * @see ApiVersionParser
 	 */
 	Comparable<?> parseVersion(String version);
 
@@ -58,4 +62,15 @@ void validateVersion(@Nullable Comparable<?> requestVersion, HttpServletRequest
 	 */
 	@Nullable Comparable<?> getDefaultVersion();
 
+	/**
+	 * Check if the requested API version is deprecated, and if so handle it
+	 * accordingly, e.g. by setting response headers to signal the deprecation,
+	 * to specify relevant dates and provide links to further details.
+	 * @param version the resolved and parsed request version
+	 * @param request the current request
+	 * @param response the current response
+	 * @see ApiDeprecationHandler
+	 */
+	void handleDeprecations(Comparable<?> version, HttpServletRequest request, HttpServletResponse response);
+
 }

spring-web/src/main/java/org/springframework/web/accept/DefaultApiVersionStrategy.java

@@ -22,13 +22,14 @@
 import java.util.TreeSet;
 
 import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
 import org.jspecify.annotations.Nullable;
 
 import org.springframework.util.Assert;
 
 /**
  * Default implementation of {@link ApiVersionStrategy} that delegates to the
- * configured version resolvers and version parser.
+ * configured version resolvers, version parser, and deprecation handler.
  *
  * @author Rossen Stoyanchev
  * @since 7.0
@@ -43,6 +44,8 @@ public class DefaultApiVersionStrategy implements ApiVersionStrategy {
 
 	private final @Nullable Comparable<?> defaultVersion;
 
+	private final @Nullable ApiDeprecationHandler deprecationHandler;
+
 	private final Set<Comparable<?>> supportedVersions = new TreeSet<>();
 
 
@@ -56,10 +59,13 @@ public class DefaultApiVersionStrategy implements ApiVersionStrategy {
 	 * validation fails with {@link MissingApiVersionException}
 	 * @param defaultVersion a default version to assign to requests that
 	 * don't specify one
+	 * @param deprecationHandler handler to send hints and information about
+	 * deprecated API versions to clients
 	 */
 	public DefaultApiVersionStrategy(
 			List<ApiVersionResolver> versionResolvers, ApiVersionParser<?> versionParser,
-			boolean versionRequired, @Nullable String defaultVersion) {
+			boolean versionRequired, @Nullable String defaultVersion,
+			@Nullable ApiDeprecationHandler deprecationHandler) {
 
 		Assert.notEmpty(versionResolvers, "At least one ApiVersionResolver is required");
 		Assert.notNull(versionParser, "ApiVersionParser is required");
@@ -68,6 +74,7 @@ public DefaultApiVersionStrategy(
 		this.versionParser = versionParser;
 		this.versionRequired = (versionRequired && defaultVersion == null);
 		this.defaultVersion = (defaultVersion != null ? versionParser.parseVersion(defaultVersion) : null);
+		this.deprecationHandler = deprecationHandler;
 	}
 
 
@@ -120,6 +127,13 @@ public void validateVersion(@Nullable Comparable<?> requestVersion, HttpServletR
 		}
 	}
 
+	@Override
+	public void handleDeprecations(Comparable<?> version, HttpServletRequest request, HttpServletResponse response) {
+		if (this.deprecationHandler != null) {
+			this.deprecationHandler.handleVersion(version, request, response);
+		}
+	}
+
 	@Override
 	public String toString() {
 		return "DefaultApiVersionStrategy[supportedVersions=" + this.supportedVersions +