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