Update docs on HandlerInterceptor

Closes gh-32729

Author: rstoyanchev

framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/interceptors.adoc

@@ -52,14 +52,10 @@ The following example shows how to achieve the same configuration in XML:
 	</mvc:interceptors>
 ----
 
-NOTE: Interceptors are not ideally suited as a security layer due to the potential
-for a mismatch with annotated controller path matching, which can also match trailing
-slashes and path extensions transparently, along with other path matching options. Many
-of these options have been deprecated but the potential for a mismatch remains.
-Generally, we recommend using Spring Security which includes a dedicated
-https://docs.spring.io/spring-security/reference/servlet/integrations/mvc.html#mvc-requestmatcher[MvcRequestMatcher]
-to align with Spring MVC path matching and also has a security firewall that blocks many
-unwanted characters in URL paths.
+WARNING: Interceptors are not ideally suited as a security layer due to the potential for
+a mismatch with annotated controller path matching. Generally, we recommend using Spring
+Security, or alternatively a similar approach integrated with the Servlet filter chain,
+and applied as early as possible.
 
 NOTE: The XML config declares interceptors as `MappedInterceptor` beans, and those are in
 turn detected by any `HandlerMapping` bean, including those from other frameworks.

framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc

@@ -1,34 +1,29 @@
 [[mvc-handlermapping-interceptor]]
 = Interception
 
-All `HandlerMapping` implementations support handler interceptors that are useful when
-you want to apply specific functionality to certain requests -- for example, checking for
-a principal. Interceptors must implement `HandlerInterceptor` from the
-`org.springframework.web.servlet` package with three methods that should provide enough
-flexibility to do all kinds of pre-processing and post-processing:
-
-* `preHandle(..)`: Before the actual handler is run
-* `postHandle(..)`: After the handler is run
-* `afterCompletion(..)`: After the complete request has finished
-
-The `preHandle(..)` method returns a boolean value. You can use this method to break or
-continue the processing of the execution chain. When this method returns `true`, the
-handler execution chain continues. When it returns false, the `DispatcherServlet`
-assumes the interceptor itself has taken care of requests (and, for example, rendered an
-appropriate view) and does not continue executing the other interceptors and the actual
-handler in the execution chain.
+All `HandlerMapping` implementations support handler interception which is useful when
+you want to apply functionality across requests. A `HandlerInterceptor` can implement the
+following:
+
+* `preHandle(..)` -- callback before the actual handler is run that returns a boolean.
+If the method returns `true`, execution continues; if it returns `false`, the rest of the
+execution chain is bypassed and the handler is not called.
+* `postHandle(..)` -- callback after the handler is run.
+* `afterCompletion(..)` -- callback after the complete request has finished.
+
+NOTE: For `@ResponseBody` and `ResponseEntity` controller methods, the response is written
+and committed within the `HandlerAdapter`, before `postHandle` is called. That means it is
+too late to change the response, such as to add an extra header. You can implement
+`ResponseBodyAdvice` and declare it as an
+xref:web/webmvc/mvc-controller/ann-advice.adoc[Controller Advice] bean or configure it
+directly on `RequestMappingHandlerAdapter`.
 
 See xref:web/webmvc/mvc-config/interceptors.adoc[Interceptors] in the section on MVC configuration for examples of how to
 configure interceptors. You can also register them directly by using setters on individual
 `HandlerMapping` implementations.
 
-`postHandle` method is less useful with `@ResponseBody` and `ResponseEntity` methods for
-which the response is written and committed within the `HandlerAdapter` and before
-`postHandle`. That means it is too late to make any changes to the response, such as adding
-an extra header. For such scenarios, you can implement `ResponseBodyAdvice` and either
-declare it as an xref:web/webmvc/mvc-controller/ann-advice.adoc[Controller Advice] bean or configure it directly on
-`RequestMappingHandlerAdapter`.
-
-
-
+WARNING: Interceptors are not ideally suited as a security layer due to the potential for
+a mismatch with annotated controller path matching. Generally, we recommend using Spring
+Security, or alternatively a similar approach integrated with the Servlet filter chain,
+and applied as early as possible.
 

spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerInterceptor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 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.
@@ -30,9 +30,9 @@
  *
  * <p>A HandlerInterceptor gets called before the appropriate HandlerAdapter
  * triggers the execution of the handler itself. This mechanism can be used
- * for a large field of preprocessing aspects, e.g. for authorization checks,
- * or common handler behavior like locale or theme changes. Its main purpose
- * is to allow for factoring out repetitive handler code.
+ * for a large field of preprocessing aspects, or common handler behavior
+ * like locale or theme changes. Its main purpose is to allow for factoring
+ * out repetitive handler code.
  *
  * <p>In an asynchronous processing scenario, the handler may be executed in a
  * separate thread while the main thread exits without rendering or invoking the
@@ -63,6 +63,12 @@
  * forms and GZIP compression. This typically shows when one needs to map the
  * filter to certain content types (e.g. images), or to all requests.
  *
+ * <p><strong>Note:</strong> Interceptors are not ideally suited as a security
+ * layer due to the potential for a mismatch with annotated controller path matching.
+ * Generally, we recommend using Spring Security, or alternatively a similar
+ * approach integrated with the Servlet filter chain, and applied as early as
+ * possible.
+ *
  * @author Juergen Hoeller
  * @since 20.06.2003
  * @see HandlerExecutionChain#getInterceptors