Package org.springframework.web.servlet

# Interface HandlerInterceptor

All Known Subinterfaces:
  `AsyncHandlerInterceptor`

All Known Implementing Classes:
  `ConversionServiceExposingInterceptor`, `LocaleChangeInterceptor`, `MappedInterceptor`, `ResourceUrlProviderExposingInterceptor`, `ThemeChangeInterceptor`, `UserRoleAuthorizationInterceptor`, `WebContentInterceptor`, `WebRequestHandlerInterceptorAdapter`

public interface HandlerInterceptor
Workflow interface that allows for customized handler execution chains. Applications can register any number of existing or custom interceptors for certain groups of handlers, to add common preprocessing behavior without needing to modify each handler implementation.

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, 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 `postHandle` and `afterCompletion` callbacks. When concurrent handler execution completes, the request is dispatched back in order to proceed with rendering the model and all methods of this contract are invoked again. For further options and details see `org.springframework.web.servlet.AsyncHandlerInterceptor`

Typically an interceptor chain is defined per HandlerMapping bean, sharing its granularity. To be able to apply a certain interceptor chain to a group of handlers, one needs to map the desired handlers via one HandlerMapping bean. The interceptors themselves are defined as beans in the application context, referenced by the mapping bean definition via its "interceptors" property (in XML: a <list> of <ref>).

HandlerInterceptor is basically similar to a Servlet Filter, but in contrast to the latter it just allows custom pre-processing with the option of prohibiting the execution of the handler itself, and custom post-processing. Filters are more powerful, for example they allow for exchanging the request and response objects that are handed down the chain. Note that a filter gets configured in web.xml, a HandlerInterceptor in the application context.

As a basic guideline, fine-grained handler-related preprocessing tasks are candidates for HandlerInterceptor implementations, especially factored-out common handler code and authorization checks. On the other hand, a Filter is well-suited for request content and view content handling, like multipart forms and GZIP compression. This typically shows when one needs to map the filter to certain content types (for example, 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.

Since:
  20.06.2003
Author:
  Juergen Hoeller
See Also:
  - `HandlerExecutionChain.getInterceptors()`
  - `AbstractHandlerMapping.setInterceptors(java.lang.Object...)`
  - `UserRoleAuthorizationInterceptor`
  - `LocaleChangeInterceptor`
  - `ThemeChangeInterceptor`
  - `Filter`

## Method Summary

Modifier and Type
Method
Description
`default void`
`afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex)`
Callback after completion of request processing, that is, after rendering the view.
`default void`
`postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView)`
Interception point after successful execution of a handler.
`default boolean`
`preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)`
Interception point before the execution of a handler.

## Method Details

### preHandle

default boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception
Interception point before the execution of a handler. Called after HandlerMapping determined an appropriate handler object, but before HandlerAdapter invokes the handler.

DispatcherServlet processes a handler in an execution chain, consisting of any number of interceptors, with the handler itself at the end. With this method, each interceptor can decide to abort the execution chain, typically sending an HTTP error or writing a custom response.

Note: special considerations apply for asynchronous request processing. For more details see `AsyncHandlerInterceptor`.

The default implementation returns `true`.

Parameters:
  `request` - current HTTP request
  `response` - current HTTP response
  `handler` - chosen handler to execute, for type and/or instance evaluation
Returns:
  `true` if the execution chain should proceed with the next interceptor or the handler itself. Else, DispatcherServlet assumes that this interceptor has already dealt with the response itself.
Throws:
  `Exception` - in case of errors

### postHandle

default void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, @Nullable ModelAndView modelAndView) throws Exception
Interception point after successful execution of a handler. Called after HandlerAdapter actually invoked the handler, but before the DispatcherServlet renders the view. Can expose additional model objects to the view via the given ModelAndView.

DispatcherServlet processes a handler in an execution chain, consisting of any number of interceptors, with the handler itself at the end. With this method, each interceptor can post-process an execution, getting applied in inverse order of the execution chain.

Note: special considerations apply for asynchronous request processing. For more details see `AsyncHandlerInterceptor`.

The default implementation is empty.

Parameters:
  `request` - current HTTP request
  `response` - current HTTP response
  `handler` - the handler (or `HandlerMethod`) that started asynchronous execution, for type and/or instance examination
  `modelAndView` - the `ModelAndView` that the handler returned (can also be `null`)
Throws:
  `Exception` - in case of errors

### afterCompletion

default void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, @Nullable Exception ex) throws Exception
Callback after completion of request processing, that is, after rendering the view. Will be called on any outcome of handler execution, thus allows for proper resource cleanup.

Note: Will only be called if this interceptor's `preHandle` method has successfully completed and returned `true`!

As with the `postHandle` method, the method will be invoked on each interceptor in the chain in reverse order, so the first interceptor will be the last to be invoked.

Note: special considerations apply for asynchronous request processing. For more details see `AsyncHandlerInterceptor`.

The default implementation is empty.

Parameters:
  `request` - current HTTP request
  `response` - current HTTP response
  `handler` - the handler (or `HandlerMethod`) that started asynchronous execution, for type and/or instance examination
  `ex` - any exception thrown on handler execution, if any; this does not include exceptions that have been handled through an exception resolver
Throws:
  `Exception` - in case of errors