From d03ea0bf19512d81496a002d105b8c5f51a68dfb Mon Sep 17 00:00:00 2001 From: rstoyanchev Date: Mon, 13 May 2024 11:38:58 +0100 Subject: [PATCH] Update docs on HandlerInterceptor Closes gh-32729 --- .../web/webmvc/mvc-config/interceptors.adoc | 12 ++---- .../handlermapping-interceptor.adoc | 41 ++++++++----------- .../web/servlet/HandlerInterceptor.java | 14 +++++-- 3 files changed, 32 insertions(+), 35 deletions(-) diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/interceptors.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/interceptors.adoc index 36c7d32956..aa9f1f8a42 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/interceptors.adoc +++ b/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: ---- -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. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc index 95aa38fbd3..f153256002 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc +++ b/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: +All `HandlerMapping` implementations support handler interception which is useful when +you want to apply functionality across requests. A `HandlerInterceptor` can implement the +following: -* `preHandle(..)`: Before the actual handler is run -* `postHandle(..)`: After the handler is run -* `afterCompletion(..)`: After the complete request has finished +* `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. -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. +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. diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerInterceptor.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerInterceptor.java index d904cb6d25..524e4505da 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerInterceptor.java +++ b/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 @@ import org.springframework.web.method.HandlerMethod; * *

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. * *

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 @@ import org.springframework.web.method.HandlerMethod; * 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. * + *

Note: 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