001/* 002 * Copyright 2002-2019 the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * https://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.springframework.web.servlet; 018 019import javax.servlet.http.HttpServletRequest; 020import javax.servlet.http.HttpServletResponse; 021 022import org.springframework.lang.Nullable; 023import org.springframework.web.method.HandlerMethod; 024 025/** 026 * Workflow interface that allows for customized handler execution chains. 027 * Applications can register any number of existing or custom interceptors 028 * for certain groups of handlers, to add common preprocessing behavior 029 * without needing to modify each handler implementation. 030 * 031 * <p>A HandlerInterceptor gets called before the appropriate HandlerAdapter 032 * triggers the execution of the handler itself. This mechanism can be used 033 * for a large field of preprocessing aspects, e.g. for authorization checks, 034 * or common handler behavior like locale or theme changes. Its main purpose 035 * is to allow for factoring out repetitive handler code. 036 * 037 * <p>In an asynchronous processing scenario, the handler may be executed in a 038 * separate thread while the main thread exits without rendering or invoking the 039 * {@code postHandle} and {@code afterCompletion} callbacks. When concurrent 040 * handler execution completes, the request is dispatched back in order to 041 * proceed with rendering the model and all methods of this contract are invoked 042 * again. For further options and details see 043 * {@code org.springframework.web.servlet.AsyncHandlerInterceptor} 044 * 045 * <p>Typically an interceptor chain is defined per HandlerMapping bean, 046 * sharing its granularity. To be able to apply a certain interceptor chain 047 * to a group of handlers, one needs to map the desired handlers via one 048 * HandlerMapping bean. The interceptors themselves are defined as beans 049 * in the application context, referenced by the mapping bean definition 050 * via its "interceptors" property (in XML: a <list> of <ref>). 051 * 052 * <p>HandlerInterceptor is basically similar to a Servlet Filter, but in 053 * contrast to the latter it just allows custom pre-processing with the option 054 * of prohibiting the execution of the handler itself, and custom post-processing. 055 * Filters are more powerful, for example they allow for exchanging the request 056 * and response objects that are handed down the chain. Note that a filter 057 * gets configured in web.xml, a HandlerInterceptor in the application context. 058 * 059 * <p>As a basic guideline, fine-grained handler-related preprocessing tasks are 060 * candidates for HandlerInterceptor implementations, especially factored-out 061 * common handler code and authorization checks. On the other hand, a Filter 062 * is well-suited for request content and view content handling, like multipart 063 * forms and GZIP compression. This typically shows when one needs to map the 064 * filter to certain content types (e.g. images), or to all requests. 065 * 066 * @author Juergen Hoeller 067 * @since 20.06.2003 068 * @see HandlerExecutionChain#getInterceptors 069 * @see org.springframework.web.servlet.handler.HandlerInterceptorAdapter 070 * @see org.springframework.web.servlet.handler.AbstractHandlerMapping#setInterceptors 071 * @see org.springframework.web.servlet.handler.UserRoleAuthorizationInterceptor 072 * @see org.springframework.web.servlet.i18n.LocaleChangeInterceptor 073 * @see org.springframework.web.servlet.theme.ThemeChangeInterceptor 074 * @see javax.servlet.Filter 075 */ 076public interface HandlerInterceptor { 077 078 /** 079 * Intercept the execution of a handler. Called after HandlerMapping determined 080 * an appropriate handler object, but before HandlerAdapter invokes the handler. 081 * <p>DispatcherServlet processes a handler in an execution chain, consisting 082 * of any number of interceptors, with the handler itself at the end. 083 * With this method, each interceptor can decide to abort the execution chain, 084 * typically sending an HTTP error or writing a custom response. 085 * <p><strong>Note:</strong> special considerations apply for asynchronous 086 * request processing. For more details see 087 * {@link org.springframework.web.servlet.AsyncHandlerInterceptor}. 088 * <p>The default implementation returns {@code true}. 089 * @param request current HTTP request 090 * @param response current HTTP response 091 * @param handler chosen handler to execute, for type and/or instance evaluation 092 * @return {@code true} if the execution chain should proceed with the 093 * next interceptor or the handler itself. Else, DispatcherServlet assumes 094 * that this interceptor has already dealt with the response itself. 095 * @throws Exception in case of errors 096 */ 097 default boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) 098 throws Exception { 099 100 return true; 101 } 102 103 /** 104 * Intercept the execution of a handler. Called after HandlerAdapter actually 105 * invoked the handler, but before the DispatcherServlet renders the view. 106 * Can expose additional model objects to the view via the given ModelAndView. 107 * <p>DispatcherServlet processes a handler in an execution chain, consisting 108 * of any number of interceptors, with the handler itself at the end. 109 * With this method, each interceptor can post-process an execution, 110 * getting applied in inverse order of the execution chain. 111 * <p><strong>Note:</strong> special considerations apply for asynchronous 112 * request processing. For more details see 113 * {@link org.springframework.web.servlet.AsyncHandlerInterceptor}. 114 * <p>The default implementation is empty. 115 * @param request current HTTP request 116 * @param response current HTTP response 117 * @param handler the handler (or {@link HandlerMethod}) that started asynchronous 118 * execution, for type and/or instance examination 119 * @param modelAndView the {@code ModelAndView} that the handler returned 120 * (can also be {@code null}) 121 * @throws Exception in case of errors 122 */ 123 default void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, 124 @Nullable ModelAndView modelAndView) throws Exception { 125 } 126 127 /** 128 * Callback after completion of request processing, that is, after rendering 129 * the view. Will be called on any outcome of handler execution, thus allows 130 * for proper resource cleanup. 131 * <p>Note: Will only be called if this interceptor's {@code preHandle} 132 * method has successfully completed and returned {@code true}! 133 * <p>As with the {@code postHandle} method, the method will be invoked on each 134 * interceptor in the chain in reverse order, so the first interceptor will be 135 * the last to be invoked. 136 * <p><strong>Note:</strong> special considerations apply for asynchronous 137 * request processing. For more details see 138 * {@link org.springframework.web.servlet.AsyncHandlerInterceptor}. 139 * <p>The default implementation is empty. 140 * @param request current HTTP request 141 * @param response current HTTP response 142 * @param handler the handler (or {@link HandlerMethod}) that started asynchronous 143 * execution, for type and/or instance examination 144 * @param ex any exception thrown on handler execution, if any; this does not 145 * include exceptions that have been handled through an exception resolver 146 * @throws Exception in case of errors 147 */ 148 default void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, 149 @Nullable Exception ex) throws Exception { 150 } 151 152}