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