Deprecate use of PathMatcher and UrlPathHelper in web

Closes gh-34018

Author: rstoyanchev

framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc

@@ -157,9 +157,7 @@ Kotlin::
 ----
 ======
 
-Note that you need to enable the use of matrix variables. In the MVC Java configuration,
-you need to set a `UrlPathHelper` with `removeSemicolonContent=false` through
-xref:web/webmvc/mvc-config/path-matching.adoc[Path Matching]. In the MVC XML namespace, you can set
+Note that you need to enable the use of matrix variables. In the MVC XML namespace, you can set
 `<mvc:annotation-driven enable-matrix-variables="true"/>`.
 
 

spring-test/src/main/java/org/springframework/test/web/servlet/setup/RouterFunctionMockMvcBuilder.java

@@ -188,9 +188,9 @@ public RouterFunctionMockMvcBuilder setAsyncRequestTimeout(long timeout) {
 	}
 
 	/**
-	 * Enable URL path matching with parsed
-	 * {@link org.springframework.web.util.pattern.PathPattern PathPatterns}
-	 * instead of String pattern matching with a {@link org.springframework.util.PathMatcher}.
+	 * Configure the parser to use for
+	 * {@link org.springframework.web.util.pattern.PathPattern PathPatterns}.
+	 * <p>By default, this is a default instance of {@link PathPatternParser}.
 	 * @param parser the parser to use
 	 */
 	public RouterFunctionMockMvcBuilder setPatternParser(@Nullable PathPatternParser parser) {

spring-test/src/main/java/org/springframework/test/web/servlet/setup/StandaloneMockMvcBuilder.java

@@ -37,6 +37,7 @@
 import org.springframework.format.support.FormattingConversionService;
 import org.springframework.http.converter.HttpMessageConverter;
 import org.springframework.mock.web.MockServletContext;
+import org.springframework.util.PathMatcher;
 import org.springframework.util.PropertyPlaceholderHelper;
 import org.springframework.util.PropertyPlaceholderHelper.PlaceholderResolver;
 import org.springframework.util.StringValueResolver;
@@ -297,9 +298,9 @@ public StandaloneMockMvcBuilder setFlashMapManager(FlashMapManager flashMapManag
 	}
 
 	/**
-	 * Enable URL path matching with parsed
-	 * {@link org.springframework.web.util.pattern.PathPattern PathPatterns}
-	 * instead of String pattern matching with a {@link org.springframework.util.PathMatcher}.
+	 * Configure the parser to use for
+	 * {@link org.springframework.web.util.pattern.PathPattern PathPatterns}.
+	 * <p>By default, this is a default instance of {@link PathPatternParser}.
 	 * @param parser the parser to use
 	 * @since 5.3
 	 */
@@ -313,7 +314,11 @@ public StandaloneMockMvcBuilder setPatternParser(@Nullable PathPatternParser par
 	 * Set if ";" (semicolon) content should be stripped from the request URI. The value,
 	 * if provided, is in turn set on
 	 * {@link org.springframework.web.util.UrlPathHelper#setRemoveSemicolonContent(boolean)}.
+	 * @deprecated use of {@link PathMatcher} and {@link UrlPathHelper} is deprecated
+	 * for use at runtime in web modules in favor of parsed patterns with
+	 * {@link PathPatternParser}.
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public StandaloneMockMvcBuilder setRemoveSemicolonContent(boolean removeSemicolonContent) {
 		this.removeSemicolonContent = removeSemicolonContent;
 		return this;
@@ -428,6 +433,7 @@ protected Map<String, Object> extendMvcSingletons(@Nullable ServletContext servl
 	/** Using the MVC Java configuration as the starting point for the "standalone" setup. */
 	private class StandaloneConfiguration extends WebMvcConfigurationSupport {
 
+		@SuppressWarnings("removal")
 		public RequestMappingHandlerMapping getHandlerMapping(
 				FormattingConversionService mvcConversionService,
 				ResourceUrlProvider mvcResourceUrlProvider) {

spring-test/src/test/java/org/springframework/test/web/servlet/samples/spr/EncodedUriTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 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.
@@ -105,6 +105,7 @@ String getCircuit(@PathVariable String id, Model model) {
 	@Component
 	static class HandlerMappingConfigurer implements BeanPostProcessor, PriorityOrdered {
 
+		@SuppressWarnings("removal")
 		@Override
 		public Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
 			if (bean instanceof RequestMappingHandlerMapping requestMappingHandlerMapping) {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2022 the original author or authors.
+ * Copyright 2002-2024 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.
@@ -141,7 +141,11 @@ private void initUrlPathHelper() {
 	 * parsed {@code PathPatterns} are used instead.
 	 * For further details on that, see {@link #setAllowInitLookupPath(boolean)}.
 	 * <p>By default this is {@link UrlPathHelper#defaultInstance}.
+	 * @deprecated use of {@link PathMatcher} and {@link UrlPathHelper} is deprecated
+	 * for use at runtime in web modules in favor of parsed patterns with
+	 * {@link PathPatternParser}.
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public void setUrlPathHelper(UrlPathHelper urlPathHelper) {
 		Assert.notNull(urlPathHelper, "UrlPathHelper must not be null");
 		this.urlPathHelper = urlPathHelper;
@@ -167,7 +171,11 @@ public void setUrlPathHelper(UrlPathHelper urlPathHelper) {
 	 * @param allowInitLookupPath whether to disable lazy initialization
 	 * and fail if not already resolved
 	 * @since 5.3
+	 * @deprecated use of {@link PathMatcher} and {@link UrlPathHelper} is deprecated
+	 * for use at runtime in web modules in favor of parsed patterns with
+	 * {@link PathPatternParser}.
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public void setAllowInitLookupPath(boolean allowInitLookupPath) {
 		this.allowInitLookupPath = allowInitLookupPath;
 	}
@@ -194,7 +202,11 @@ public void setLookupPathAttributeName(String name) {
 	 * String pattern matching even when a
 	 * {@link ServletRequestPathUtils#parseAndCache parsed} {@code RequestPath}
 	 * is available.
+	 * @deprecated use of {@link PathMatcher} and {@link UrlPathHelper} is deprecated
+	 * for use at runtime in web modules in favor of parsed patterns with
+	 * {@link PathPatternParser}.
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public void setPathMatcher(PathMatcher pathMatcher) {
 		this.pathMatcher = pathMatcher;
 	}

spring-web/src/test/java/org/springframework/web/cors/UrlBasedCorsConfigurationSourceTests.java

@@ -71,6 +71,7 @@ void unmodifiableConfigurationsMap() {
 				.isThrownBy(() -> source.getCorsConfigurations().put("/**", new CorsConfiguration()));
 	}
 
+	@SuppressWarnings("removal")
 	@Test
 	void allowInitLookupPath() {
 		CorsConfiguration config = new CorsConfiguration();

spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/InterceptorRegistration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2024 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.
@@ -29,7 +29,9 @@
 import org.springframework.web.servlet.HandlerInterceptor;
 import org.springframework.web.servlet.handler.MappedInterceptor;
 import org.springframework.web.util.ServletRequestPathUtils;
+import org.springframework.web.util.UrlPathHelper;
 import org.springframework.web.util.pattern.PathPattern;
+import org.springframework.web.util.pattern.PathPatternParser;
 
 /**
  * Assists with the creation of a {@link MappedInterceptor}.
@@ -114,7 +116,11 @@ public InterceptorRegistration excludePathPatterns(List<String> patterns) {
 	 * String pattern matching even when a
 	 * {@link ServletRequestPathUtils#parseAndCache parsed} {@code RequestPath}
 	 * is available.
+	 * @deprecated use of {@link PathMatcher} and {@link UrlPathHelper} is deprecated
+	 * for use at runtime in web modules in favor of parsed patterns with
+	 * {@link PathPatternParser}.
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public InterceptorRegistration pathMatcher(PathMatcher pathMatcher) {
 		this.pathMatcher = pathMatcher;
 		return this;
@@ -140,6 +146,7 @@ protected int getOrder() {
 	 * Build the underlying interceptor. If URL patterns are provided, the returned
 	 * type is {@link MappedInterceptor}; otherwise {@link HandlerInterceptor}.
 	 */
+	@SuppressWarnings("removal")
 	protected Object getInterceptor() {
 
 		if (this.includePatterns == null && this.excludePatterns == null) {

spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/PathMatchConfigurer.java

@@ -65,12 +65,6 @@ public class PathMatchConfigurer {
 	 * Set the {@link PathPatternParser} to parse {@link PathPattern patterns}
 	 * with for URL path matching. Parsed patterns provide a more modern and
 	 * efficient alternative to String path matching via {@link AntPathMatcher}.
-	 * <p><strong>Note:</strong> This property is mutually exclusive with the
-	 * following other, {@code AntPathMatcher} related properties:
-	 * <ul>
-	 * <li>{@link #setUrlPathHelper(UrlPathHelper)}
-	 * <li>{@link #setPathMatcher(PathMatcher)}
-	 * </ul>
 	 * <p>By default, as of 6.0, a {@link PathPatternParser} with default
 	 * settings is used, which enables parsed {@link PathPattern patterns}.
 	 * Set this property to {@code null} to fall back on String path matching via
@@ -110,9 +104,13 @@ public PathMatchConfigurer addPathPrefix(String prefix, Predicate<Class<?>> pred
 	 * {@link #setPatternParser(PathPatternParser)}. If set, it enables use of
 	 * String path matching, unless a {@code PathPatternParser} is also
 	 * explicitly set in which case this property is ignored.
-	 * <p>By default this is an instance of {@link UrlPathHelper} with default
+	 * <p>By default, this is an instance of {@link UrlPathHelper} with default
 	 * settings.
+	 * @deprecated use of {@link PathMatcher} and {@link UrlPathHelper} is deprecated
+	 * for use at runtime in web modules in favor of parsed patterns with
+	 * {@link PathPatternParser}.
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public PathMatchConfigurer setUrlPathHelper(UrlPathHelper urlPathHelper) {
 		this.urlPathHelper = urlPathHelper;
 		this.preferPathMatcher = true;
@@ -125,9 +123,12 @@ public PathMatchConfigurer setUrlPathHelper(UrlPathHelper urlPathHelper) {
 	 * {@link #setPatternParser(PathPatternParser)}. If set, it enables use of
 	 * String path matching, unless a {@code PathPatternParser} is also
 	 * explicitly set in which case this property is ignored.
-	 * <p>By default this is an instance of {@link AntPathMatcher} with default
+	 * <p>By default, this is an instance of {@link AntPathMatcher} with default
 	 * settings.
+	 * @deprecated use of {@link PathMatcher} is deprecated for use at runtime
+	 * in web modules in favor of parsed patterns with {@link PathPatternParser}.
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public PathMatchConfigurer setPathMatcher(PathMatcher pathMatcher) {
 		this.pathMatcher = pathMatcher;
 		this.preferPathMatcher = true;
@@ -143,7 +144,10 @@ public PathMatchConfigurer setPathMatcher(PathMatcher pathMatcher) {
 	 * {@link PathMatcher} related option is explicitly set.
 	 * </ul>
 	 * @since 6.0
+	 * @deprecated use of {@link PathMatcher} is deprecated for use at runtime
+	 * in web modules in favor of parsed patterns with {@link PathPatternParser}.
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	protected boolean preferPathMatcher() {
 		return (this.patternParser == null && this.preferPathMatcher);
 	}
@@ -160,18 +164,24 @@ protected boolean preferPathMatcher() {
 		return this.pathPrefixes;
 	}
 
+	@Deprecated(since = "7.0", forRemoval = true)
 	public @Nullable UrlPathHelper getUrlPathHelper() {
 		return this.urlPathHelper;
 	}
 
+	@Deprecated(since = "7.0", forRemoval = true)
 	public @Nullable PathMatcher getPathMatcher() {
 		return this.pathMatcher;
 	}
 
 	/**
 	 * Return the configured UrlPathHelper or a default, shared instance otherwise.
 	 * @since 5.3
+	 * @deprecated use of {@link PathMatcher} and {@link UrlPathHelper} is deprecated
+	 * for use at runtime in web modules in favor of parsed patterns with
+	 * {@link PathPatternParser}.
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	protected UrlPathHelper getUrlPathHelperOrDefault() {
 		if (this.urlPathHelper != null) {
 			return this.urlPathHelper;
@@ -185,7 +195,10 @@ protected UrlPathHelper getUrlPathHelperOrDefault() {
 	/**
 	 * Return the configured PathMatcher or a default, shared instance otherwise.
 	 * @since 5.3
+	 * @deprecated use of {@link PathMatcher} is deprecated for use at runtime
+	 * in web modules in favor of parsed patterns with {@link PathPatternParser}.
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	protected PathMatcher getPathMatcherOrDefault() {
 		if (this.pathMatcher != null) {
 			return this.pathMatcher;

spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/ResourceHandlerRegistry.java

@@ -100,7 +100,10 @@ public ResourceHandlerRegistry(ApplicationContext applicationContext, ServletCon
 	 * {@link #ResourceHandlerRegistry(ApplicationContext, ServletContext, ContentNegotiationManager)}
 	 * that also accepts the {@link UrlPathHelper} used for mapping requests to static resources.
 	 * @since 4.3.13
+	 * @deprecated in favor of
+	 * {@link #ResourceHandlerRegistry(ApplicationContext, ServletContext, ContentNegotiationManager)}
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public ResourceHandlerRegistry(ApplicationContext applicationContext, ServletContext servletContext,
 			@Nullable ContentNegotiationManager contentNegotiationManager, @Nullable UrlPathHelper pathHelper) {
 
@@ -167,6 +170,7 @@ public ResourceHandlerRegistry setOrder(int order) {
 		return new SimpleUrlHandlerMapping(urlMap, this.order);
 	}
 
+	@SuppressWarnings("removal")
 	private ResourceHttpRequestHandler getRequestHandler(ResourceHandlerRegistration registration) {
 		ResourceHttpRequestHandler handler = registration.getRequestHandler();
 		if (this.pathHelper != null) {

spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/WebMvcConfigurationSupport.java

@@ -391,7 +391,12 @@ public PathPatternParser mvcPatternParser() {
 	 * <p><b>Note:</b> This is only used when parsed patterns are not
 	 * {@link PathMatchConfigurer#setPatternParser enabled}.
 	 * @since 4.1
+	 * @deprecated use of {@link PathMatcher} and {@link UrlPathHelper} is deprecated
+	 * for use at runtime in web modules in favor of parsed patterns with
+	 * {@link PathPatternParser}.
 	 */
+	@SuppressWarnings("removal")
+	@Deprecated(since = "7.0", forRemoval = true)
 	@Bean
 	public UrlPathHelper mvcUrlPathHelper() {
 		return getPathMatchConfigurer().getUrlPathHelperOrDefault();
@@ -404,7 +409,12 @@ public UrlPathHelper mvcUrlPathHelper() {
 	 * <p><b>Note:</b> This is only used when parsed patterns are not
 	 * {@link PathMatchConfigurer#setPatternParser enabled}.
 	 * @since 4.1
+	 * @deprecated use of {@link PathMatcher} and {@link UrlPathHelper} is deprecated
+	 * for use at runtime in web modules in favor of parsed patterns with
+	 * {@link PathPatternParser}.
 	 */
+	@SuppressWarnings("removal")
+	@Deprecated(since = "7.0", forRemoval = true)
 	@Bean
 	public PathMatcher mvcPathMatcher() {
 		return getPathMatchConfigurer().getPathMatcherOrDefault();
@@ -474,6 +484,7 @@ protected void configureContentNegotiation(ContentNegotiationConfigurer configur
 		return mapping;
 	}
 
+	@SuppressWarnings("removal")
 	private void initHandlerMapping(
 			@Nullable AbstractHandlerMapping mapping, FormattingConversionService conversionService,
 			ResourceUrlProvider resourceUrlProvider) {
@@ -554,6 +565,7 @@ public RouterFunctionMapping routerFunctionMapping(
 	 * resource handlers. To configure resource handling, override
 	 * {@link #addResourceHandlers}.
 	 */
+	@SuppressWarnings("removal")
 	@Bean
 	public @Nullable HandlerMapping resourceHandlerMapping(
 			@Qualifier("mvcContentNegotiationManager") ContentNegotiationManager contentNegotiationManager,
@@ -585,6 +597,7 @@ protected void addResourceHandlers(ResourceHandlerRegistry registry) {
 	 * A {@link ResourceUrlProvider} bean for use with the MVC dispatcher.
 	 * @since 4.1
 	 */
+	@SuppressWarnings("removal")
 	@Bean
 	public ResourceUrlProvider mvcResourceUrlProvider() {
 		ResourceUrlProvider urlProvider = new ResourceUrlProvider();