HandlerInterceptor


1   /*
2    * Copyright 2002-2006 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  /**
23   * Workflow interface that allows for customized handler execution chains.
24   * Applications can register any number of existing or custom interceptors
25   * for certain groups of handlers, to add common preprocessing behavior
26   * without needing to modify each handler implementation.
27   *
28   * <p>A HandlerInterceptor gets called before the appropriate HandlerAdapter
29   * triggers the execution of the handler itself. This mechanism can be used
30   * for a large field of preprocessing aspects, e.g. for authorization checks,
31   * or common handler behavior like locale or theme changes. Its main purpose
32   * is to allow for factoring out repetitive handler code.
33   *
34   * <p>Typically an interceptor chain is defined per HandlerMapping bean,
35   * sharing its granularity. To be able to apply a certain interceptor chain
36   * to a group of handlers, one needs to map the desired handlers via one
37   * HandlerMapping bean. The interceptors themselves are defined as beans
38   * in the application context, referenced by the mapping bean definition
39   * via its "interceptors" property (in XML: a &lt;list&gt; of &lt;ref&gt;).
40   *
41   * <p>HandlerInterceptor is basically similar to a Servlet 2.3 Filter, but in
42   * contrast to the latter it just allows custom pre-processing with the option
43   * of prohibiting the execution of the handler itself, and custom post-processing.
44   * Filters are more powerful, for example they allow for exchanging the request
45   * and response objects that are handed down the chain. Note that a filter
46   * gets configured in web.xml, a HandlerInterceptor in the application context.
47   *
48   * <p>As a basic guideline, fine-grained handler-related preprocessing tasks are
49   * candidates for HandlerInterceptor implementations, especially factored-out
50   * common handler code and authorization checks. On the other hand, a Filter
51   * is well-suited for request content and view content handling, like multipart
52   * forms and GZIP compression. This typically shows when one needs to map the
53   * filter to certain content types (e.g. images), or to all requests.
54   *
55   * @author Juergen Hoeller
56   * @since 20.06.2003
57   * @see HandlerExecutionChain#getInterceptors
58   * @see org.springframework.web.servlet.handler.HandlerInterceptorAdapter
59   * @see org.springframework.web.servlet.handler.AbstractHandlerMapping#setInterceptors
60   * @see org.springframework.web.servlet.handler.UserRoleAuthorizationInterceptor
61   * @see org.springframework.web.servlet.i18n.LocaleChangeInterceptor
62   * @see org.springframework.web.servlet.theme.ThemeChangeInterceptor
63   * @see javax.servlet.Filter
64   */
65  public interface HandlerInterceptor {
66  
67      /**
68       * Intercept the execution of a handler. Called after HandlerMapping determined
69       * an appropriate handler object, but before HandlerAdapter invokes the handler.
70       * <p>DispatcherServlet processes a handler in an execution chain, consisting
71       * of any number of interceptors, with the handler itself at the end.
72       * With this method, each interceptor can decide to abort the execution chain,
73       * typically sending a HTTP error or writing a custom response.
74       * @param request current HTTP request
75       * @param response current HTTP response
76       * @param handler chosen handler to execute, for type and/or instance evaluation
77       * @return <code>true</code> if the execution chain should proceed with the
78       * next interceptor or the handler itself. Else, DispatcherServlet assumes
79       * that this interceptor has already dealt with the response itself.
80       * @throws Exception in case of errors
81       */
82      boolean preHandle(HttpServletRequest   request, HttpServletResponse   response, Object   handler)
83          throws Exception  ;
84  
85      /**
86       * Intercept the execution of a handler. Called after HandlerAdapter actually
87       * invoked the handler, but before the DispatcherServlet renders the view.
88       * Can expose additional model objects to the view via the given ModelAndView.
89       * <p>DispatcherServlet processes a handler in an execution chain, consisting
90       * of any number of interceptors, with the handler itself at the end.
91       * With this method, each interceptor can post-process an execution,
92       * getting applied in inverse order of the execution chain.
93       * @param request current HTTP request
94       * @param response current HTTP response
95       * @param handler chosen handler to execute, for type and/or instance examination
96       * @param modelAndView the <code>ModelAndView</code> that the handler returned
97       * (can also be <code>null</code>)
98       * @throws Exception in case of errors
99       */
100     void postHandle(
101             HttpServletRequest   request, HttpServletResponse   response, Object   handler, ModelAndView modelAndView)
102             throws Exception  ;
103 
104     /**
105      * Callback after completion of request processing, that is, after rendering
106      * the view. Will be called on any outcome of handler execution, thus allows
107      * for proper resource cleanup.
108      * <p>Note: Will only be called if this interceptor's <code>preHandle</code>
109      * method has successfully completed and returned <code>true</code>!
110      * @param request current HTTP request
111      * @param response current HTTP response
112      * @param handler chosen handler to execute, for type and/or instance examination
113      * @param ex exception thrown on handler execution, if any
114      * @throws Exception in case of errors
115      */
116     void afterCompletion(
117             HttpServletRequest   request, HttpServletResponse   response, Object   handler, Exception   ex)
118             throws Exception  ;
119 
120 }
121
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags