站内搜索: 请输入搜索关键词
当前页面: 在线文档首页 > Spring Framework 2.1.0 API 文档英文版

HandlerInterceptor (Spring Framework API 2.1) - Spring Framework 2.1.0 API 文档英文版

Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
The Spring Framework
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.springframework.web.portlet
Interface HandlerInterceptor

All Known Implementing Classes:
HandlerInterceptorAdapter, ParameterMappingInterceptor, UserRoleAuthorizationInterceptor, WebRequestHandlerInterceptorAdapter
public interface HandlerInterceptor

Workflow interface that allows for customized handler execution chains. Applications can register any number of existing or custom interceptors for certain groups of handlers, to add common preprocessing behavior without needing to modify each handler implementation.

A HandlerInterceptor gets called before the appropriate HandlerAdapter triggers the execution of the handler itself. This mechanism can be used for a large field of preprocessing aspects, e.g. for authorization checks, or common handler behavior like locale or theme changes. Its main purpose is to permit the factoring out of otherwise repetitive handler code.

Typically an interceptor chain is defined per HandlerMapping bean, sharing its granularity. To be able to apply a certain interceptor chain to a group of handlers, one needs to map the desired handlers via one HandlerMapping bean. The interceptors themselves are defined as beans in the application context, referenced by the mapping bean definition via its "interceptors" property (in XML: a <list> of <ref> elements).

A HandlerInterceptor is basically similar to a Servlet 2.3 Filter, but in contrast to the latter it allows custom pre-processing with the option to prohibit the execution of the handler itself, and custom post-processing. Filters are more powerful; for example they allow for exchanging the request and response objects that are handed down the chain. Note that a filter gets configured in web.xml, a HandlerInterceptor in the application context.

As a basic guideline, fine-grained handler-related preprocessing tasks are candidates for HandlerInterceptor implementations, especially factored-out common handler code and authorization checks. On the other hand, a Filter is well-suited for request content and view content handling, like multipart forms and GZIP compression. This typically shows when one needs to map the filter to certain content types (e.g. images), or to all requests. Be aware that filters cannot be applied to portlet requests (they only operate on servlet requests), so for portlet requests interceptors are essential.

If we assume a "sunny day" request (i.e. a request where nothing goes wrong and all is well), the workflow of a HandlerInterceptor will be as follows:

  1. (DispatcherServlet maps a request to particular handler and assembles a handler execution chain consisting of the handler that is to be invoked and all of the HandlerInterceptor instances that apply to the request.)
  2. preHandleAction(..) is called; if the invocation of this method returns true then this workflow continues
  3. The target handler handles the action phase of the request (via HandlerAdapter.handleAction(..))
  4. afterActionCompletion(..) is called
  5. preHandleRender(..) is called; if the invocation of this method returns true then this workflow continues
  6. The target handler handles the render phase of the request (via HandlerAdapter.handleRender(..))
  7. postHandleRender(..) is called
  8. afterRenderCompletion(..) is called

Since:
2.0
Author:
Juergen Hoeller, John A. Lewis
See Also:
HandlerExecutionChain.getInterceptors(), HandlerMapping, AbstractHandlerMapping.setInterceptors(java.lang.Object[]), HandlerExecutionChain

Method Summary
 void afterActionCompletion(ActionRequest request, ActionResponse response, Object handler, Exception ex)
          Callback after completion of request processing in the action phase, that is, after rendering the view.
 void afterRenderCompletion(RenderRequest request, RenderResponse response, Object handler, Exception ex)
          Callback after completion of request processing, that is, after rendering the view.
 void postHandleRender(RenderRequest request, RenderResponse response, Object handler, ModelAndView modelAndView)
          Intercept the execution of a handler in the render phase.
 boolean preHandleAction(ActionRequest request, ActionResponse response, Object handler)
          Intercept the execution of a handler in the action phase.
 boolean preHandleRender(RenderRequest request, RenderResponse response, Object handler)
          Intercept the execution of a handler in the render phase.
 

Method Detail

preHandleAction

boolean preHandleAction(ActionRequest request,
                        ActionResponse response,
                        Object handler)
                        throws Exception
Intercept the execution of a handler in the action phase.

Called after a HandlerMapping determines an appropriate handler object to handle an ActionRequest, but before said HandlerAdapter actually invokes the handler.

DispatcherPortlet processes a handler in an execution chain, consisting of any number of interceptors, with the handler itself at the end. With this method, each interceptor can decide to abort the execution chain, typically throwing an exception or writing a custom response.

Parameters:
request - current portlet action request
response - current portlet action response
handler - chosen handler to execute, for type and/or instance evaluation
Returns:
true if the execution chain should proceed with the next interceptor or the handler itself. Else, DispatcherPortlet assumes that this interceptor has already dealt with the response itself
Throws:
Exception - in case of errors

afterActionCompletion

void afterActionCompletion(ActionRequest request,
                           ActionResponse response,
                           Object handler,
                           Exception ex)
                           throws Exception
Callback after completion of request processing in the action phase, that is, after rendering the view. Will be called on any outcome of handler execution, thus allowing for proper resource cleanup.

Note: Will only be called if this interceptor's preHandleAction(javax.portlet.ActionRequest, javax.portlet.ActionResponse, Object) method has successfully completed and returned true!

Parameters:
request - current portlet action request
response - current portlet action response
handler - chosen handler to execute, for type and/or instance examination
ex - exception thrown on handler execution, if any (only included as additional context information for the case where a handler threw an exception; request execution may have failed even when this argument is null)
Throws:
Exception - in case of errors

preHandleRender

boolean preHandleRender(RenderRequest request,
                        RenderResponse response,
                        Object handler)
                        throws Exception
Intercept the execution of a handler in the render phase.

Called after a HandlerMapping determines an appropriate handler object to handle a RenderRequest, but before said HandlerAdapter actually invokes the handler.

DispatcherPortlet processes a handler in an execution chain, consisting of any number of interceptors, with the handler itself at the end. With this method, each interceptor can decide to abort the execution chain, typically throwing an exception or writing a custom response.

Parameters:
request - current portlet render request
response - current portlet render response
handler - chosen handler to execute, for type and/or instance evaluation
Returns:
true if the execution chain should proceed with the next interceptor or the handler itself. Else, DispatcherPortlet assumes that this interceptor has already dealt with the response itself
Throws:
Exception - in case of errors

postHandleRender

void postHandleRender(RenderRequest request,
                      RenderResponse response,
                      Object handler,
                      ModelAndView modelAndView)
                      throws Exception
Intercept the execution of a handler in the render phase.

Called after a HandlerAdapter actually invoked the handler, but before the DispatcherPortlet renders the view. Can thus expose additional model objects to the view via the given ModelAndView.

DispatcherPortlet processes a handler in an execution chain, consisting of any number of interceptors, with the handler itself at the end. With this method, each interceptor can post-process an execution, getting applied in inverse order of the execution chain.

Parameters:
request - current portlet render request
response - current portlet render response
handler - chosen handler to execute, for type and/or instance examination
modelAndView - the ModelAndView that the handler returned (can also be null)
Throws:
Exception - in case of errors

afterRenderCompletion

void afterRenderCompletion(RenderRequest request,
                           RenderResponse response,
                           Object handler,
                           Exception ex)
                           throws Exception
Callback after completion of request processing, that is, after rendering the view. Will be called on any outcome of handler execution, thus allowing for proper resource cleanup.

Note: Will only be called if this interceptor's preHandleRender(javax.portlet.RenderRequest, javax.portlet.RenderResponse, Object) method has successfully completed and returned true!

Parameters:
request - current portlet render request
response - current portlet render response
handler - chosen handler to execute, for type and/or instance examination
ex - exception thrown on handler execution, if any
Throws:
Exception - in case of errors
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
The Spring Framework
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2002-2007 The Spring Framework.