Package org.apache.shiro.web.servlet

Class OncePerRequestFilter

java.lang.Object

org.apache.shiro.web.servlet.ServletContextSupport

org.apache.shiro.web.servlet.AbstractFilter

org.apache.shiro.web.servlet.NameableFilter

org.apache.shiro.web.servlet.OncePerRequestFilter

All Implemented Interfaces:

Filter, Nameable

Direct Known Subclasses:

AbstractShiroFilter, AdviceFilter

public abstract class OncePerRequestFilter
extends NameableFilter

Filter base class that guarantees to be just executed once per request, on any servlet container. It provides a doFilterInternal(javax.servlet.ServletRequest, javax.servlet.ServletResponse, javax.servlet.FilterChain) method with HttpServletRequest and HttpServletResponse arguments.

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.

Controlling filter execution

1.2 introduced the isEnabled(javax.servlet.ServletRequest, javax.servlet.ServletResponse) method and isEnabled() property to allow explicit control over whether the filter executes (or allows passthrough) for any given request.

NOTE This class was initially borrowed from the Spring framework but has continued modifications.

Since:

0.1

Field Summary

Fields

Modifier and Type	Field	Description
static String	ALREADY_FILTERED_SUFFIX	Suffix that gets appended to the filter name for the "already filtered" request attribute.

Fields inherited from class org.apache.shiro.web.servlet.AbstractFilter

filterConfig

Constructor Summary

Constructors

Constructor	Description
OncePerRequestFilter()

Method Summary

Modifier and Type	Method	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(ServletRequest request, ServletResponse response, FilterChain chain)	Same contract as for doFilter(javax.servlet.ServletRequest, javax.servlet.ServletResponse, javax.servlet.FilterChain), but guaranteed to be invoked only once per request.
protected String	getAlreadyFilteredAttributeName()	Return name of the request attribute that identifies that a request has already been filtered.
boolean	isEnabled()	Returns true if this filter should generally* execute for any request, false if it should let the request/response pass through immediately to the next element in the FilterChain.
protected boolean	isEnabled(ServletRequest request, ServletResponse response)	Returns true if this filter should filter the specified request, false if it should let the request/response pass through immediately to the next element in the FilterChain.
boolean	isFilterOncePerRequest()	Returns true if this filter should only execute once per request.
void	setEnabled(boolean enabled)	Sets whether or not this filter generally executes for any request.
void	setFilterOncePerRequest(boolean filterOncePerRequest)	Sets whether this filter executes once per request or for every invocation of the filter.
protected boolean	shouldNotFilter(ServletRequest request)	Deprecated. in favor of overriding isEnabled(javax.servlet.ServletRequest, javax.servlet.ServletResponse) for custom behavior.

Methods inherited from class org.apache.shiro.web.servlet.NameableFilter

getName, setName, toStringBuilder

Methods inherited from class org.apache.shiro.web.servlet.AbstractFilter

destroy, getFilterConfig, getInitParam, init, onFilterConfigSet, setFilterConfig

Methods inherited from class org.apache.shiro.web.servlet.ServletContextSupport

getContextAttribute, getContextInitParam, getServletContext, removeContextAttribute, setContextAttribute, setServletContext, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ALREADY_FILTERED_SUFFIX

public static final String ALREADY_FILTERED_SUFFIX

Suffix that gets appended to the filter name for the "already filtered" request attribute.

See Also:

getAlreadyFilteredAttributeName(), Constant Field Values

Constructor Detail

OncePerRequestFilter

public OncePerRequestFilter()

Method Detail

isEnabled

public boolean isEnabled()

Returns true if this filter should generally* execute for any request, false if it should let the request/response pass through immediately to the next element in the FilterChain. The default value is true, as most filters would inherently need to execute when configured.

* This configuration property is for general configuration for any request that comes through the filter. The isEnabled(request,response) method actually determines whether or not if the filter is enabled based on the current request.

Returns:

true if this filter should generally execute, false if it should let the request/response pass through immediately to the next element in the FilterChain.

Since:

1.2

setEnabled

public void setEnabled(boolean enabled)

Sets whether or not this filter generally executes for any request. See the isEnabled() JavaDoc as to what general execution means.

Parameters:

enabled - whether or not this filter generally executes.

Since:

1.2

isFilterOncePerRequest

public boolean isFilterOncePerRequest()

Returns true if this filter should only execute once per request. If set to false this filter will execute each time it is invoked.

Returns:

true if this filter should only execute once per request.

Since:

1.10

setFilterOncePerRequest

public void setFilterOncePerRequest(boolean filterOncePerRequest)

Sets whether this filter executes once per request or for every invocation of the filter. It is recommended to leave this disabled if you are using a RequestDispatcher to forward or include request (JSP tags, programmatically, or via a framework).

Parameters:

filterOncePerRequest - Whether this filter executes once per request.

Since:

1.10

doFilter

public final void doFilter(ServletRequest request,
                           ServletResponse response,
                           FilterChain filterChain)
                    throws ServletException,
                           IOException

This doFilter implementation stores a request attribute for "already filtered", proceeding without filtering again if the attribute is already there.

Throws:

ServletException

IOException

See Also:

getAlreadyFilteredAttributeName(), shouldNotFilter(javax.servlet.ServletRequest), doFilterInternal(javax.servlet.ServletRequest, javax.servlet.ServletResponse, javax.servlet.FilterChain)

isEnabled

protected boolean isEnabled(ServletRequest request,
                            ServletResponse response)
                     throws ServletException,
                            IOException

Returns true if this filter should filter the specified request, false if it should let the request/response pass through immediately to the next element in the FilterChain.

This default implementation merely returns the value of isEnabled(), which is true by default (to ensure the filter always executes by default), but it can be overridden by subclasses for request-specific behavior if necessary. For example, a filter could be enabled or disabled based on the request path being accessed.

Helpful Hint: if your subclass extends PathMatchingFilter, you may wish to instead override the PathMatchingFilter.isEnabled(request,response,path,pathSpecificConfig) method if you want to make your enable/disable decision based on any path-specific configuration.

Parameters:

request - the incoming servlet request

response - the outbound servlet response

Returns:

true if this filter should filter the specified request, false if it should let the request/response pass through immediately to the next element in the FilterChain.

Throws:

IOException - in the case of any IO error

ServletException - in the case of any error

Since:

1.2

See Also:

PathMatchingFilter.isEnabled(javax.servlet.ServletRequest, javax.servlet.ServletResponse, String, Object)

getAlreadyFilteredAttributeName

protected String getAlreadyFilteredAttributeName()

Return name of the request attribute that identifies that a request has already been filtered.

The default implementation takes the configured name and appends ".FILTERED". If the filter is not fully initialized, it falls back to the implementation's class name.

Returns:

the name of the request attribute that identifies that a request has already been filtered.

See Also:

NameableFilter.getName(), ALREADY_FILTERED_SUFFIX

shouldNotFilter

@Deprecated
protected boolean shouldNotFilter(ServletRequest request)
                           throws ServletException

Deprecated.

in favor of overriding isEnabled(javax.servlet.ServletRequest, javax.servlet.ServletResponse) for custom behavior. This method will be removed in Shiro 2.0.

Can be overridden in subclasses for custom filtering control, returning true to avoid filtering of the given request.

The default implementation always returns false.

Parameters:

request - current HTTP request

Returns:

whether the given request should not be filtered

Throws:

ServletException - in case of errors

doFilterInternal

protected abstract void doFilterInternal(ServletRequest request,
                                         ServletResponse response,
                                         FilterChain chain)
                                  throws ServletException,
                                         IOException

Same contract as for doFilter(javax.servlet.ServletRequest, javax.servlet.ServletResponse, javax.servlet.FilterChain), but guaranteed to be invoked only once per request.

Parameters:

request - incoming ServletRequest

response - outgoing ServletResponse

chain - the FilterChain to execute

Throws:

ServletException - if there is a problem processing the request

IOException - if there is an I/O problem processing the request