Deprecate pathExtension routing predicates

Closes gh-34103

Author: rstoyanchev

framework-docs/modules/ROOT/pages/web/webflux-functional.adoc

@@ -803,8 +803,7 @@ Java::
 [source,java,indent=0,subs="verbatim,quotes"]
 ----
 	ClassPathResource index = new ClassPathResource("static/index.html");
-	List<String> extensions = List.of("js", "css", "ico", "png", "jpg", "gif");
-	RequestPredicate spaPredicate = path("/api/**").or(path("/error")).or(pathExtension(extensions::contains)).negate();
+	RequestPredicate spaPredicate = path("/api/**").or(path("/error")).negate();
 	RouterFunction<ServerResponse> redirectToIndex = route()
 		.resource(spaPredicate, index)
 		.build();
@@ -816,9 +815,7 @@ Kotlin::
 ----
 	val redirectToIndex = router {
 		val index = ClassPathResource("static/index.html")
-		val extensions = listOf("js", "css", "ico", "png", "jpg", "gif")
-		val spaPredicate = !(path("/api/**") or path("/error") or
-			pathExtension(extensions::contains))
+		val spaPredicate = !(path("/api/**") or path("/error"))
 		resource(spaPredicate, index)
 	}
 ----

framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc

@@ -782,7 +782,7 @@ Java::
 ----
     ClassPathResource index = new ClassPathResource("static/index.html");
 	List<String> extensions = List.of("js", "css", "ico", "png", "jpg", "gif");
-	RequestPredicate spaPredicate = path("/api/**").or(path("/error")).or(pathExtension(extensions::contains)).negate();
+	RequestPredicate spaPredicate = path("/api/**").or(path("/error")).negate();
 	RouterFunction<ServerResponse> redirectToIndex = route()
 		.resource(spaPredicate, index)
 		.build();
@@ -794,9 +794,7 @@ Kotlin::
 ----
     val redirectToIndex = router {
 		val index = ClassPathResource("static/index.html")
-		val extensions = listOf("js", "css", "ico", "png", "jpg", "gif")
-		val spaPredicate = !(path("/api/**") or path("/error") or
-			pathExtension(extensions::contains))
+		val spaPredicate = !(path("/api/**") or path("/error"))
 		resource(spaPredicate, index)
 	}
 ----

spring-webflux/src/main/java/org/springframework/web/reactive/function/server/RequestPredicates.java

@@ -270,7 +270,12 @@ public static RequestPredicate OPTIONS(String pattern) {
 	 * Return a {@code RequestPredicate} that matches if the request's path has the given extension.
 	 * @param extension the path extension to match against, ignoring case
 	 * @return a predicate that matches if the request's path has the given file extension
+	 * @deprecated without replacement to discourage use of path extensions for request
+	 * mapping and for content negotiation (with similar deprecations and removals already
+	 * applied to annotated controllers). For further context, please read issue
+	 * <a href="https://github.com/spring-projects/spring-framework/issues/24179">#24179</a>
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public static RequestPredicate pathExtension(String extension) {
 		Assert.notNull(extension, "'extension' must not be null");
 		return new PathExtensionPredicate(extension);
@@ -282,7 +287,12 @@ public static RequestPredicate pathExtension(String extension) {
 	 * @param extensionPredicate the predicate to test against the request path extension
 	 * @return a predicate that matches if the given predicate matches against the request's path
 	 * file extension
+	 * @deprecated without replacement to discourage use of path extensions for request
+	 * mapping and for content negotiation (with similar deprecations and removals already
+	 * applied to annotated controllers). For further context, please read issue
+	 * <a href="https://github.com/spring-projects/spring-framework/issues/24179">#24179</a>
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public static RequestPredicate pathExtension(Predicate<String> extensionPredicate) {
 		return new PathExtensionPredicate(extensionPredicate);
 	}
@@ -354,7 +364,12 @@ public interface Visitor {
 		 * Receive notification of a path extension predicate.
 		 * @param extension the path extension that makes up the predicate
 		 * @see RequestPredicates#pathExtension(String)
+		 * @deprecated without replacement to discourage use of path extensions for request
+		 * mapping and for content negotiation (with similar deprecations and removals already
+		 * applied to annotated controllers). For further context, please read issue
+		 * <a href="https://github.com/spring-projects/spring-framework/issues/24179">#24179</a>
 		 */
+		@Deprecated(since = "7.0", forRemoval = true)
 		void pathExtension(String extension);
 
 		/**
@@ -816,6 +831,7 @@ public String toString() {
 	}
 
 
+	@Deprecated(since = "7.0", forRemoval = true)
 	private static class PathExtensionPredicate implements RequestPredicate {
 
 		private final Predicate<String> extensionPredicate;

spring-webflux/src/main/java/org/springframework/web/reactive/function/server/ToStringVisitor.java

@@ -102,6 +102,8 @@ public void path(String pattern) {
 		this.builder.append(pattern);
 	}
 
+	@SuppressWarnings("removal")
+	@Deprecated(since = "7.0", forRemoval = true)
 	@Override
 	public void pathExtension(String extension) {
 		this.builder.append(String.format("*.%s", extension));

spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/server/CoRouterFunctionDsl.kt

@@ -507,6 +507,11 @@ class CoRouterFunctionDsl internal constructor (private val init: (CoRouterFunct
 	 * Route to the given handler function if the given pathExtension predicate applies.
 	 * @see RouterFunctions.route
 	 */
+	@Deprecated("without replacement to discourage use of path extensions for request mapping and for" +
+			"content negotiation (with similar deprecations and removals already applied to" +
+			"annotated controllers). For further context, please read issue " +
+			"https://github.com/spring-projects/spring-framework/issues/24179", replaceWith = ReplaceWith("None"))
+	@Suppress("removal", "DEPRECATION")
 	fun pathExtension(extension: String, f: suspend (ServerRequest) -> ServerResponse) {
 		builder.add(RouterFunctions.route(RequestPredicates.pathExtension(extension), asHandlerFunction(f)))
 	}
@@ -516,21 +521,35 @@ class CoRouterFunctionDsl internal constructor (private val init: (CoRouterFunct
 	 * @param extension the path extension to match against, ignoring case
 	 * @return a predicate that matches if the request's path has the given file extension
 	 */
+	@Suppress("removal", "DEPRECATION")
+	@Deprecated("without replacement to discourage use of path extensions for request mapping and for" +
+			"content negotiation (with similar deprecations and removals already applied to" +
+			"annotated controllers). For further context, please read issue " +
+			"https://github.com/spring-projects/spring-framework/issues/24179", replaceWith = ReplaceWith("None"))
 	fun pathExtension(extension: String): RequestPredicate = RequestPredicates.pathExtension(extension)
 
 	/**
 	 * Route to the given handler function if the given pathExtension predicate applies.
 	 * @see RouterFunctions.route
 	 */
+	@Suppress("removal", "DEPRECATION")
+	@Deprecated("without replacement to discourage use of path extensions for request mapping and for" +
+			"content negotiation (with similar deprecations and removals already applied to" +
+			"annotated controllers). For further context, please read issue " +
+			"https://github.com/spring-projects/spring-framework/issues/24179", replaceWith = ReplaceWith("None"))
 	fun pathExtension(predicate: (String?) -> Boolean, f: suspend (ServerRequest) -> ServerResponse) {
 		builder.add(RouterFunctions.route(RequestPredicates.pathExtension(predicate), asHandlerFunction(f)))
 	}
 
 	/**
 	 * Return a [RequestPredicate] that matches if the request's path matches the given
 	 * predicate.
-	 * @see RequestPredicates.pathExtension
 	 */
+	@Suppress("removal", "DEPRECATION")
+	@Deprecated("without replacement to discourage use of path extensions for request mapping and for" +
+			"content negotiation (with similar deprecations and removals already applied to" +
+			"annotated controllers). For further context, please read issue " +
+			"https://github.com/spring-projects/spring-framework/issues/24179", replaceWith = ReplaceWith("None"))
 	fun pathExtension(predicate: (String?) -> Boolean): RequestPredicate =
 			RequestPredicates.pathExtension(predicate)
 

spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/server/RouterFunctionDsl.kt

@@ -554,6 +554,11 @@ class RouterFunctionDsl internal constructor (private val init: RouterFunctionDs
 	 * Route to the given handler function if the given pathExtension predicate applies.
 	 * @see RouterFunctions.route
 	 */
+	@Suppress("removal", "DEPRECATION")
+	@Deprecated("without replacement to discourage use of path extensions for request mapping and for" +
+			"content negotiation (with similar deprecations and removals already applied to" +
+			"annotated controllers). For further context, please read issue " +
+			"https://github.com/spring-projects/spring-framework/issues/24179", replaceWith = ReplaceWith("None"))
 	fun pathExtension(extension: String, f: (ServerRequest) -> Mono<out ServerResponse>) {
 		builder.add(RouterFunctions.route(RequestPredicates.pathExtension(extension)) { f(it).cast(ServerResponse::class.java) })
 	}
@@ -563,21 +568,35 @@ class RouterFunctionDsl internal constructor (private val init: RouterFunctionDs
 	 * @param extension the path extension to match against, ignoring case
 	 * @return a predicate that matches if the request's path has the given file extension
 	 */
+	@Suppress("removal", "DEPRECATION")
+	@Deprecated("without replacement to discourage use of path extensions for request mapping and for" +
+			"content negotiation (with similar deprecations and removals already applied to" +
+			"annotated controllers). For further context, please read issue " +
+			"https://github.com/spring-projects/spring-framework/issues/24179", replaceWith = ReplaceWith("None"))
 	fun pathExtension(extension: String): RequestPredicate = RequestPredicates.pathExtension(extension)
 
 	/**
 	 * Route to the given handler function if the given pathExtension predicate applies.
 	 * @see RouterFunctions.route
 	 */
+	@Suppress("removal", "DEPRECATION")
+	@Deprecated("without replacement to discourage use of path extensions for request mapping and for" +
+			"content negotiation (with similar deprecations and removals already applied to" +
+			"annotated controllers). For further context, please read issue " +
+			"https://github.com/spring-projects/spring-framework/issues/24179", replaceWith = ReplaceWith("None"))
 	fun pathExtension(predicate: (String?) -> Boolean, f: (ServerRequest) -> Mono<out ServerResponse>) {
 		builder.add(RouterFunctions.route(RequestPredicates.pathExtension(predicate)) { f(it).cast(ServerResponse::class.java) })
 	}
 
 	/**
 	 * Return a [RequestPredicate] that matches if the request's path matches the given
 	 * predicate.
-	 * @see RequestPredicates.pathExtension
 	 */
+	@Suppress("removal", "DEPRECATION")
+	@Deprecated("without replacement to discourage use of path extensions for request mapping and for" +
+			"content negotiation (with similar deprecations and removals already applied to" +
+			"annotated controllers). For further context, please read issue " +
+			"https://github.com/spring-projects/spring-framework/issues/24179", replaceWith = ReplaceWith("None"))
 	fun pathExtension(predicate: (String?) -> Boolean): RequestPredicate =
 			RequestPredicates.pathExtension(predicate)
 

spring-webflux/src/test/java/org/springframework/web/reactive/function/server/RequestPredicatesTests.java

@@ -296,6 +296,7 @@ void multipleAccepts() {
 		assertThat(predicate.test(request)).isFalse();
 	}
 
+	@SuppressWarnings("removal")
 	@Test
 	void pathExtension() {
 		RequestPredicate predicate = RequestPredicates.pathExtension("txt");
@@ -319,6 +320,7 @@ void pathExtension() {
 		assertThat(predicate.test(request)).isFalse();
 	}
 
+	@SuppressWarnings("removal")
 	@Test
 	void pathExtensionPredicate() {
 		List<String> extensions = List.of("foo", "bar");

spring-webflux/src/test/java/org/springframework/web/reactive/function/server/ToStringVisitorTests.java

@@ -29,7 +29,6 @@
 import static org.springframework.web.reactive.function.server.RequestPredicates.method;
 import static org.springframework.web.reactive.function.server.RequestPredicates.methods;
 import static org.springframework.web.reactive.function.server.RequestPredicates.path;
-import static org.springframework.web.reactive.function.server.RequestPredicates.pathExtension;
 import static org.springframework.web.reactive.function.server.RequestPredicates.queryParam;
 import static org.springframework.web.reactive.function.server.RouterFunctions.route;
 
@@ -69,8 +68,6 @@ void predicates() {
 
 		testPredicate(path("/foo"), "/foo");
 
-		testPredicate(pathExtension("foo"), "*.foo");
-
 		testPredicate(contentType(MediaType.APPLICATION_JSON), "Content-Type: application/json");
 
 		ToStringVisitor visitor = new ToStringVisitor();

spring-webflux/src/test/kotlin/org/springframework/web/reactive/function/server/CoRouterFunctionDslTests.kt

@@ -333,6 +333,7 @@ class CoRouterFunctionDslTests {
 				null
 			}
 		}
+		@Suppress("DEPRECATION")
 		GET(pathExtension { it == "properties" }) {
 			ok().bodyValueAndAwait("foo=bar")
 		}

spring-webflux/src/test/kotlin/org/springframework/web/reactive/function/server/RouterFunctionDslTests.kt

@@ -265,6 +265,7 @@ class RouterFunctionDslTests {
 				Mono.empty()
 			}
 		}
+		@Suppress("DEPRECATION")
 		GET(pathExtension { it == "properties" }) {
 			ok().bodyValue("foo=bar")
 		}