public abstract class OncePerRequestFilter extends GenericFilterBean
doFilterInternal(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, javax.servlet.FilterChain)
method with HttpServletRequest and HttpServletResponse arguments.
As of Servlet 3.0, a filter may be invoked as part of a
REQUEST
or
ASYNC
dispatches that occur in
separate threads. A filter can be configured in web.xml
whether it
should be involved in async dispatches. However, in some cases servlet
containers assume different default configuration. Therefore sub-classes can
override the method shouldNotFilterAsyncDispatch()
to declare
statically if they should indeed be invoked, once, during both types
of dispatches in order to provide thread initialization, logging, security,
and so on. This mechanism complements and does not replace the need to
configure a filter in web.xml
with dispatcher types.
Subclasses may use isAsyncDispatch(HttpServletRequest)
to
determine when a filter is invoked as part of an async dispatch, and use
isAsyncStarted(HttpServletRequest)
to determine when the request
has been placed in async mode and therefore the current dispatch won't be
the last one for the given request.
Yet another dispatch type that also occurs in its own thread is
ERROR
. Subclasses can override
shouldNotFilterErrorDispatch()
if they wish to declare statically
if they should be invoked once during error dispatches.
The getAlreadyFilteredAttributeName()
method determines how to
identify that a request is already filtered. The default implementation is
based on the configured name of the concrete filter instance.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
ALREADY_FILTERED_SUFFIX
Suffix that gets appended to the filter name for the
"already filtered" request attribute.
|
logger
Constructor and Description |
---|
OncePerRequestFilter() |
Modifier and Type | Method and Description |
---|---|
void |
doFilter(ServletRequest request,
ServletResponse response,
FilterChain filterChain)
This
doFilter implementation stores a request attribute for
"already filtered", proceeding without filtering again if the
attribute is already there. |
protected abstract void |
doFilterInternal(HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain)
Same contract as for
doFilter , but guaranteed to be
just invoked once per request within a single request thread. |
protected java.lang.String |
getAlreadyFilteredAttributeName()
Return the name of the request attribute that identifies that a request
is already filtered.
|
protected boolean |
isAsyncDispatch(HttpServletRequest request)
The dispatcher type
javax.servlet.DispatcherType.ASYNC introduced
in Servlet 3.0 means a filter can be invoked in more than one thread over
the course of a single request. |
protected boolean |
isAsyncStarted(HttpServletRequest request)
Whether request processing is in asynchronous mode meaning that the
response will not be committed after the current thread is exited.
|
protected boolean |
shouldNotFilter(HttpServletRequest request)
Can be overridden in subclasses for custom filtering control,
returning
true to avoid filtering of the given request. |
protected boolean |
shouldNotFilterAsyncDispatch()
The dispatcher type
javax.servlet.DispatcherType.ASYNC introduced
in Servlet 3.0 means a filter can be invoked in more than one thread
over the course of a single request. |
protected boolean |
shouldNotFilterErrorDispatch()
Whether to filter error dispatches such as when the servlet container
processes and error mapped in
web.xml . |
addRequiredProperty, afterPropertiesSet, createEnvironment, destroy, getEnvironment, getFilterConfig, getFilterName, getServletContext, init, initBeanWrapper, initFilterBean, setBeanName, setEnvironment, setServletContext
public static final java.lang.String ALREADY_FILTERED_SUFFIX
public final void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain) throws ServletException, java.io.IOException
doFilter
implementation stores a request attribute for
"already filtered", proceeding without filtering again if the
attribute is already there.protected boolean isAsyncDispatch(HttpServletRequest request)
javax.servlet.DispatcherType.ASYNC
introduced
in Servlet 3.0 means a filter can be invoked in more than one thread over
the course of a single request. This method returns true
if the
filter is currently executing within an asynchronous dispatch.request
- the current requestWebAsyncManager.hasConcurrentResult()
protected boolean isAsyncStarted(HttpServletRequest request)
request
- the current requestWebAsyncManager.isConcurrentHandlingStarted()
protected java.lang.String getAlreadyFilteredAttributeName()
The default implementation takes the configured name of the concrete filter instance and appends ".FILTERED". If the filter is not fully initialized, it falls back to its class name.
protected boolean shouldNotFilter(HttpServletRequest request) throws ServletException
true
to avoid filtering of the given request.
The default implementation always returns false
.
request
- current HTTP requestServletException
- in case of errorsprotected boolean shouldNotFilterAsyncDispatch()
javax.servlet.DispatcherType.ASYNC
introduced
in Servlet 3.0 means a filter can be invoked in more than one thread
over the course of a single request. Some filters only need to filter
the initial thread (e.g. request wrapping) while others may need
to be invoked at least once in each additional thread for example for
setting up thread locals or to perform final processing at the very end.
Note that although a filter can be mapped to handle specific dispatcher
types via web.xml
or in Java through the ServletContext
,
servlet containers may enforce different defaults with regards to
dispatcher types. This flag enforces the design intent of the filter.
The default return value is "true", which means the filter will not be invoked during subsequent async dispatches. If "false", the filter will be invoked during async dispatches with the same guarantees of being invoked only once during a request within a single thread.
protected boolean shouldNotFilterErrorDispatch()
web.xml
. The default return value
is "true", which means the filter will not be invoked in case of an error
dispatch.protected abstract void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, java.io.IOException
doFilter
, but guaranteed to be
just invoked once per request within a single request thread.
See shouldNotFilterAsyncDispatch()
for details.
Provides HttpServletRequest and HttpServletResponse arguments instead of the default ServletRequest and ServletResponse ones.
ServletException
java.io.IOException