org.springframework.web.portlet.HandlerInterceptor Maven / Gradle / Ivy
/*
* Copyright 2002-2006 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.web.portlet;
import javax.portlet.ActionRequest;
import javax.portlet.ActionResponse;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;
/**
* 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
* {@link org.springframework.web.portlet.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
* {@link org.springframework.web.portlet.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
* {@link org.springframework.web.portlet.handler.AbstractHandlerMapping#setInterceptors "interceptors"}
* property (in XML: a <list> of <ref> elements).
*
*
A HandlerInterceptor is basically similar to a Servlet 2.3
* {@link javax.servlet.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:
*
*
* - (
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.)
* - {@link org.springframework.web.portlet.HandlerInterceptor#preHandleAction(javax.portlet.ActionRequest, javax.portlet.ActionResponse, Object) preHandleAction(..)}
* is called; if the invocation of this method returns
true then
* this workflow continues
* - The target handler handles the action phase of the request (via
* {@link org.springframework.web.portlet.HandlerAdapter#handleAction(javax.portlet.ActionRequest, javax.portlet.ActionResponse, Object) HandlerAdapter.handleAction(..)})
* - {@link org.springframework.web.portlet.HandlerInterceptor#afterActionCompletion(javax.portlet.ActionRequest, javax.portlet.ActionResponse, Object, Exception) afterActionCompletion(..)}
* is called
* - {@link org.springframework.web.portlet.HandlerInterceptor#preHandleRender(javax.portlet.RenderRequest, javax.portlet.RenderResponse, Object) preHandleRender(..)}
* is called; if the invocation of this method returns
true then
* this workflow continues
* - The target handler handles the render phase of the request (via
* {@link org.springframework.web.portlet.HandlerAdapter#handleRender(javax.portlet.RenderRequest, javax.portlet.RenderResponse, Object) HandlerAdapter.handleRender(..)})
* - {@link org.springframework.web.portlet.HandlerInterceptor#postHandleRender(javax.portlet.RenderRequest, javax.portlet.RenderResponse, Object, ModelAndView) postHandleRender(..)}
* is called
* - {@link org.springframework.web.portlet.HandlerInterceptor#afterRenderCompletion(javax.portlet.RenderRequest, javax.portlet.RenderResponse, Object, Exception) afterRenderCompletion(..)}
* is called
*
*
* @author Juergen Hoeller
* @author John A. Lewis
* @since 2.0
* @see HandlerExecutionChain#getInterceptors
* @see org.springframework.web.portlet.HandlerMapping
* @see org.springframework.web.portlet.handler.AbstractHandlerMapping#setInterceptors
* @see org.springframework.web.portlet.HandlerExecutionChain
*/
public interface HandlerInterceptor {
/**
* Intercept the execution of a handler in the action phase.
* Called after a HandlerMapping determines an appropriate handler object
* to handle an {@link ActionRequest}, but before said HandlerAdapter actually
* invokes the handler.
*
{@link 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.
* @param request current portlet action request
* @param response current portlet action response
* @param handler chosen handler to execute, for type and/or instance evaluation
* @return 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
*/
boolean preHandleAction(ActionRequest request, ActionResponse response, Object handler)
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
* {@link #preHandleAction(javax.portlet.ActionRequest, javax.portlet.ActionResponse, Object)}
* method has successfully completed and returned true!
* @param request current portlet action request
* @param response current portlet action response
* @param handler chosen handler to execute, for type and/or instance examination
* @param 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
*/
void afterActionCompletion(
ActionRequest request, ActionResponse response, Object handler, Exception ex)
throws Exception;
/**
* Intercept the execution of a handler in the render phase.
*
Called after a HandlerMapping determines an appropriate handler object
* to handle a {@link RenderRequest}, but before said HandlerAdapter actually
* invokes the handler.
*
{@link 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.
* @param request current portlet render request
* @param response current portlet render response
* @param handler chosen handler to execute, for type and/or instance evaluation
* @return 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
*/
boolean preHandleRender(RenderRequest request, RenderResponse response, Object handler)
throws Exception;
/**
* Intercept the execution of a handler in the render phase.
*
Called after a {@link HandlerAdapter} actually invoked the handler, but
* before the DispatcherPortlet renders the view. Can thus expose
* additional model objects to the view via the given {@link 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.
* @param request current portlet render request
* @param response current portlet render response
* @param handler chosen handler to execute, for type and/or instance examination
* @param modelAndView the ModelAndView that the handler returned
* (can also be null)
* @throws Exception in case of errors
*/
void postHandleRender(
RenderRequest request, RenderResponse response, Object handler, ModelAndView modelAndView)
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
* {@link #preHandleRender(javax.portlet.RenderRequest, javax.portlet.RenderResponse, Object)}
* method has successfully completed and returned true!
* @param request current portlet render request
* @param response current portlet render response
* @param handler chosen handler to execute, for type and/or instance examination
* @param ex exception thrown on handler execution, if any
* @throws Exception in case of errors
*/
void afterRenderCompletion(
RenderRequest request, RenderResponse response, Object handler, Exception ex)
throws Exception;
}