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 pre-processing 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
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 pre-processing 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 cycle (i.e. a request where nothing goes wrong
and all is well), the workflow of a HandlerInterceptor will be as
follows:

Action Request:

DispatcherPortlet maps the action request to a 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.

preHandleAction(..)
is called; if the invocation of this method returns true then this workflow continues.

DispatcherPortlet maps the render request to a 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.

preHandleRender(..)
is called; if the invocation of this method returns true then this workflow continues.

Method Detail

preHandleAction

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.

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)

preHandleRender

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.

postHandleRender

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.

preHandleResource

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.

postHandleResource

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.

preHandleEvent

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.

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)