com.interface21.web.servlet
Interface HandlerInterceptor

All Known Implementing Classes:

LocaleChangeInterceptor, UserRoleAuthorizationInterceptor, ThemeChangeInterceptor

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 allow for factoring out 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 of s).

HandlerInterceptor is basically similar to a Servlet 2.3 Filter, but in contrast to the latter it just allows custom preprocessing with the option prohibiting the execution of the handler itself. Filters are more powerful, for example they allow for exchanging the request and response objects that are handed down the chain, and for custom postprocessing. 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.

Since:

20.06.2003

Author:

Juergen Hoeller

See Also:

HandlerExecutionChain.getInterceptors(), AbstractHandlerMapping.setInterceptors(java.util.List), UserRoleAuthorizationInterceptor, LocaleChangeInterceptor, ThemeChangeInterceptor, javax.servlet.Filter

Method Summary

boolean

preHandle(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Object handler) Intercept the execution of a handler.

Method Detail

preHandle

public boolean preHandle(javax.servlet.http.HttpServletRequest request,
                         javax.servlet.http.HttpServletResponse response,
                         java.lang.Object handler)
                  throws javax.servlet.ServletException,
                         java.io.IOException

Intercept the execution of a handler. Called after HandlerMapping determined an appropriate handler object, but before HandlerAdapter invokes the handler.

DispatcherServlet processes a handler in an execution chain, consisting of any number of interceptors, with the handler itself at the end. Each interceptor can decide to abort the execution chain, typically sending a HTTP error or writing a custom response.

Parameters:

request - current HTTP request

response - current HTTP response

handler - chosen handler to execute, for type and/or instance evaluation

Returns:

if the execution chain should proceed with the next interceptor resp. the handler itself, else DispatcherServlet assumes that this interceptor has already dealed with the response

Throws:

javax.servlet.ServletException - if there is an internal error

java.io.IOException - in case of an I/O error when writing the response