1 /* 2 * Copyright 2002-2015 the original author or authors. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package org.springframework.web.servlet; 18 19 import javax.servlet.http.HttpServletRequest; 20 import javax.servlet.http.HttpServletResponse; 21 22 import org.springframework.web.method.HandlerMethod; 23 24 /** 25 * Workflow interface that allows for customized handler execution chains. 26 * Applications can register any number of existing or custom interceptors 27 * for certain groups of handlers, to add common preprocessing behavior 28 * without needing to modify each handler implementation. 29 * 30 * <p>A HandlerInterceptor gets called before the appropriate HandlerAdapter 31 * triggers the execution of the handler itself. This mechanism can be used 32 * for a large field of preprocessing aspects, e.g. for authorization checks, 33 * or common handler behavior like locale or theme changes. Its main purpose 34 * is to allow for factoring out repetitive handler code. 35 * 36 * <p>In an async processing scenario, the handler may be executed in a separate 37 * thread while the main thread exits without rendering or invoking the 38 * {@code postHandle} and {@code afterCompletion} callbacks. When concurrent 39 * handler execution completes, the request is dispatched back in order to 40 * proceed with rendering the model and all methods of this contract are invoked 41 * again. For further options and details see 42 * {@code org.springframework.web.servlet.AsyncHandlerInterceptor} 43 * 44 * <p>Typically an interceptor chain is defined per HandlerMapping bean, 45 * sharing its granularity. To be able to apply a certain interceptor chain 46 * to a group of handlers, one needs to map the desired handlers via one 47 * HandlerMapping bean. The interceptors themselves are defined as beans 48 * in the application context, referenced by the mapping bean definition 49 * via its "interceptors" property (in XML: a <list> of <ref>). 50 * 51 * <p>HandlerInterceptor is basically similar to a Servlet Filter, but in 52 * contrast to the latter it just allows custom pre-processing with the option 53 * of prohibiting the execution of the handler itself, and custom post-processing. 54 * Filters are more powerful, for example they allow for exchanging the request 55 * and response objects that are handed down the chain. Note that a filter 56 * gets configured in web.xml, a HandlerInterceptor in the application context. 57 * 58 * <p>As a basic guideline, fine-grained handler-related preprocessing tasks are 59 * candidates for HandlerInterceptor implementations, especially factored-out 60 * common handler code and authorization checks. On the other hand, a Filter 61 * is well-suited for request content and view content handling, like multipart 62 * forms and GZIP compression. This typically shows when one needs to map the 63 * filter to certain content types (e.g. images), or to all requests. 64 * 65 * @author Juergen Hoeller 66 * @since 20.06.2003 67 * @see HandlerExecutionChain#getInterceptors 68 * @see org.springframework.web.servlet.handler.HandlerInterceptorAdapter 69 * @see org.springframework.web.servlet.handler.AbstractHandlerMapping#setInterceptors 70 * @see org.springframework.web.servlet.handler.UserRoleAuthorizationInterceptor 71 * @see org.springframework.web.servlet.i18n.LocaleChangeInterceptor 72 * @see org.springframework.web.servlet.theme.ThemeChangeInterceptor 73 * @see javax.servlet.Filter 74 */ 75 public interface HandlerInterceptor { 76 77 /** 78 * Intercept the execution of a handler. Called after HandlerMapping determined 79 * an appropriate handler object, but before HandlerAdapter invokes the handler. 80 * <p>DispatcherServlet processes a handler in an execution chain, consisting 81 * of any number of interceptors, with the handler itself at the end. 82 * With this method, each interceptor can decide to abort the execution chain, 83 * typically sending a HTTP error or writing a custom response. 84 * @param request current HTTP request 85 * @param response current HTTP response 86 * @param handler chosen handler to execute, for type and/or instance evaluation 87 * @return {@code true} if the execution chain should proceed with the 88 * next interceptor or the handler itself. Else, DispatcherServlet assumes 89 * that this interceptor has already dealt with the response itself. 90 * @throws Exception in case of errors 91 */ 92 boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) 93 throws Exception; 94 95 /** 96 * Intercept the execution of a handler. Called after HandlerAdapter actually 97 * invoked the handler, but before the DispatcherServlet renders the view. 98 * Can expose additional model objects to the view via the given ModelAndView. 99 * <p>DispatcherServlet processes a handler in an execution chain, consisting 100 * of any number of interceptors, with the handler itself at the end. 101 * With this method, each interceptor can post-process an execution, 102 * getting applied in inverse order of the execution chain. 103 * @param request current HTTP request 104 * @param response current HTTP response 105 * @param handler handler (or {@link HandlerMethod}) that started async 106 * execution, for type and/or instance examination 107 * @param modelAndView the {@code ModelAndView} that the handler returned 108 * (can also be {@code null}) 109 * @throws Exception in case of errors 110 */ 111 void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) 112 throws Exception; 113 114 /** 115 * Callback after completion of request processing, that is, after rendering 116 * the view. Will be called on any outcome of handler execution, thus allows 117 * for proper resource cleanup. 118 * <p>Note: Will only be called if this interceptor's {@code preHandle} 119 * method has successfully completed and returned {@code true}! 120 * <p>As with the {@code postHandle} method, the method will be invoked on each 121 * interceptor in the chain in reverse order, so the first interceptor will be 122 * the last to be invoked. 123 * @param request current HTTP request 124 * @param response current HTTP response 125 * @param handler handler (or {@link HandlerMethod}) that started async 126 * execution, for type and/or instance examination 127 * @param ex exception thrown on handler execution, if any 128 * @throws Exception in case of errors 129 */ 130 void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) 131 throws Exception; 132 133 }