org.apache.shiro.spring.web

Class ShiroFilterFactoryBean

java.lang.Object

org.apache.shiro.spring.web.ShiroFilterFactoryBean

All Implemented Interfaces:

org.springframework.beans.factory.config.BeanPostProcessor, org.springframework.beans.factory.FactoryBean

public class ShiroFilterFactoryBean
extends Object
implements org.springframework.beans.factory.FactoryBean, org.springframework.beans.factory.config.BeanPostProcessor

FactoryBean to be used in Spring-based web applications for defining the master Shiro Filter.

Usage

Declare a DelegatingFilterProxy in web.xml, matching the filter name to the bean id:

 <filter>
   <filter-name>shiroFilter</filter-name>
   <filter-class>org.springframework.web.filter.DelegatingFilterProxy<filter-class>
   <init-param>
    <param-name>targetFilterLifecycle</param-name>
     <param-value>true</param-value>
   </init-param>
 </filter>
 

Then, in your spring XML file that defines your web ApplicationContext:

 <bean id="shiroFilter" class="org.apache.shiro.spring.web.ShiroFilterFactoryBean">
    <property name="securityManager" ref="securityManager"/>
    <!-- other properties as necessary ... -->
 </bean>
 

Filter Auto-Discovery

While there is a filters property that allows you to assign a filter beans to the 'pool' of filters available when defining filter chains, it is optional.

This implementation is also a BeanPostProcessor and will acquire any Filter beans defined independently in your Spring application context. Upon discovery, they will be automatically added to the map keyed by the bean ID. That ID can then be used in the filter chain definitions, for example:

 <bean id="myCustomFilter" class="com.class.that.implements.javax.servlet.Filter"/>
 ...
 <bean id="shiroFilter" class="org.apache.shiro.spring.web.ShiroFilterFactoryBean">
    ...
    <property name="filterChainDefinitions">
        <value>
            /some/path/** = authc, myCustomFilter
        </value>
    </property>
 </bean>
 

Global Property Values

Most Shiro servlet Filter implementations exist for defining custom Filter chain definitions. Most implementations subclass one of the AccessControlFilter, AuthenticationFilter, AuthorizationFilter classes to simplify things, and each of these 3 classes has configurable properties that are application-specific.

A dilemma arises where, if you want to for example set the application's 'loginUrl' for any Filter, you don't want to have to manually specify that value for each filter instance definied.

To prevent configuration duplication, this implementation provides the following properties to allow you to set relevant values in only one place:

• setLoginUrl(String)
• setSuccessUrl(String)
• setUnauthorizedUrl(String)

Then at startup, any values specified via these 3 properties will be applied to all configured Filter instances so you don't have to specify them individually on each filter instance. To ensure your own custom filters benefit from this convenience, your filter implementation should subclass one of the 3 mentioned earlier.

Since:

1.0

See Also:

DelegatingFilterProxy

Constructor Summary

Constructors

Constructor and Description
ShiroFilterFactoryBean()

Method Summary

Modifier and Type	Method and Description
protected FilterChainManager	createFilterChainManager()
protected AbstractShiroFilter	createInstance() This implementation: Ensures the required securityManager property has been set Creates a FilterChainManager instance that reflects the configured filters and filter chain definitions Wraps the FilterChainManager with a suitable FilterChainResolver since the Shiro Filter implementations do not know of FilterChainManagers Sets both the SecurityManager and FilterChainResolver instances on a new Shiro Filter instance and returns that filter instance.
Map<String,String>	getFilterChainDefinitionMap() Returns the chainName-to-chainDefinition map of chain definitions to use for creating filter chains intercepted by the Shiro Filter.
Map<String,javax.servlet.Filter>	getFilters() Returns the filterName-to-Filter map of filters available for reference when defining filter chain definitions.
String	getLoginUrl() Returns the application's login URL to be assigned to all acquired Filters that subclass AccessControlFilter or null if no value should be assigned globally.
Object	getObject() Lazily creates and returns a AbstractShiroFilter concrete instance via the createInstance() method.
Class	getObjectType() Returns AbstractShiroFilter.class
SecurityManager	getSecurityManager() Sets the application SecurityManager instance to be used by the constructed Shiro Filter.
String	getSuccessUrl() Returns the application's after-login success URL to be assigned to all acquired Filters that subclass AuthenticationFilter or null if no value should be assigned globally.
String	getUnauthorizedUrl() Returns the application's after-login success URL to be assigned to all acquired Filters that subclass AuthenticationFilter or null if no value should be assigned globally.
boolean	isSingleton() Returns true always.
Object	postProcessAfterInitialization(Object bean, String beanName) Does nothing - only exists to satisfy the BeanPostProcessor interface and immediately returns the bean argument.
Object	postProcessBeforeInitialization(Object bean, String beanName) Inspects a bean, and if it implements the Filter interface, automatically adds that filter instance to the internal filters map that will be referenced later during filter chain construction.
void	setFilterChainDefinitionMap(Map<String,String> filterChainDefinitionMap) Sets the chainName-to-chainDefinition map of chain definitions to use for creating filter chains intercepted by the Shiro Filter.
void	setFilterChainDefinitions(String definitions) A convenience method that sets the filterChainDefinitionMap property by accepting a Properties-compatible string (multi-line key/value pairs).
void	setFilters(Map<String,javax.servlet.Filter> filters) Sets the filterName-to-Filter map of filters available for reference when creating filter chain definitions.
void	setLoginUrl(String loginUrl) Sets the application's login URL to be assigned to all acquired Filters that subclass AccessControlFilter.
void	setSecurityManager(SecurityManager securityManager) Sets the application SecurityManager instance to be used by the constructed Shiro Filter.
void	setSuccessUrl(String successUrl) Sets the application's after-login success URL to be assigned to all acquired Filters that subclass AuthenticationFilter.
void	setUnauthorizedUrl(String unauthorizedUrl) Sets the application's 'unauthorized' URL to be assigned to all acquired Filters that subclass AuthorizationFilter.

Methods inherited from class java.lang.Object

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

Constructor Detail

ShiroFilterFactoryBean

public ShiroFilterFactoryBean()

Method Detail

getSecurityManager

public SecurityManager getSecurityManager()

Sets the application SecurityManager instance to be used by the constructed Shiro Filter. This is a required property - failure to set it will throw an initialization exception.

Returns:

the application SecurityManager instance to be used by the constructed Shiro Filter.

setSecurityManager

public void setSecurityManager(SecurityManager securityManager)

Sets the application SecurityManager instance to be used by the constructed Shiro Filter. This is a required property - failure to set it will throw an initialization exception.

Parameters:

securityManager - the application SecurityManager instance to be used by the constructed Shiro Filter.

getLoginUrl

public String getLoginUrl()

Returns the application's login URL to be assigned to all acquired Filters that subclass AccessControlFilter or null if no value should be assigned globally. The default value is null.

Returns:

the application's login URL to be assigned to all acquired Filters that subclass AccessControlFilter or null if no value should be assigned globally.

See Also:

setLoginUrl(java.lang.String)

setLoginUrl

public void setLoginUrl(String loginUrl)

Sets the application's login URL to be assigned to all acquired Filters that subclass AccessControlFilter. This is a convenience mechanism: for all configured filters, as well for any default ones (authc, user, etc), this value will be passed on to each Filter via the AccessControlFilter.setLoginUrl(String) method*. This eliminates the need to configure the 'loginUrl' property manually on each filter instance, and instead that can be configured once via this attribute.

*If a filter already has already been explicitly configured with a value, it will not receive this value. Individual filter configuration overrides this global convenience property.

Parameters:

loginUrl - the application's login URL to apply to as a convenience to all discovered AccessControlFilter instances.

See Also:

AccessControlFilter.setLoginUrl(String)

getSuccessUrl

public String getSuccessUrl()

Returns the application's after-login success URL to be assigned to all acquired Filters that subclass AuthenticationFilter or null if no value should be assigned globally. The default value is null.

Returns:

the application's after-login success URL to be assigned to all acquired Filters that subclass AuthenticationFilter or null if no value should be assigned globally.

See Also:

setSuccessUrl(java.lang.String)

setSuccessUrl

public void setSuccessUrl(String successUrl)

Sets the application's after-login success URL to be assigned to all acquired Filters that subclass AuthenticationFilter. This is a convenience mechanism: for all configured filters, as well for any default ones (authc, user, etc), this value will be passed on to each Filter via the AuthenticationFilter.setSuccessUrl(String) method*. This eliminates the need to configure the 'successUrl' property manually on each filter instance, and instead that can be configured once via this attribute.

*If a filter already has already been explicitly configured with a value, it will not receive this value. Individual filter configuration overrides this global convenience property.

Parameters:

successUrl - the application's after-login success URL to apply to as a convenience to all discovered AccessControlFilter instances.

See Also:

AuthenticationFilter.setSuccessUrl(String)

getUnauthorizedUrl

public String getUnauthorizedUrl()

Returns the application's after-login success URL to be assigned to all acquired Filters that subclass AuthenticationFilter or null if no value should be assigned globally. The default value is null.

Returns:

the application's after-login success URL to be assigned to all acquired Filters that subclass AuthenticationFilter or null if no value should be assigned globally.

See Also:

setSuccessUrl(java.lang.String)

setUnauthorizedUrl

public void setUnauthorizedUrl(String unauthorizedUrl)

Sets the application's 'unauthorized' URL to be assigned to all acquired Filters that subclass AuthorizationFilter. This is a convenience mechanism: for all configured filters, as well for any default ones (roles, perms, etc), this value will be passed on to each Filter via the AuthorizationFilter.setUnauthorizedUrl(String) method*. This eliminates the need to configure the 'unauthorizedUrl' property manually on each filter instance, and instead that can be configured once via this attribute.

*If a filter already has already been explicitly configured with a value, it will not receive this value. Individual filter configuration overrides this global convenience property.

Parameters:

unauthorizedUrl - the application's 'unauthorized' URL to apply to as a convenience to all discovered AuthorizationFilter instances.

See Also:

AuthorizationFilter.setUnauthorizedUrl(String)

getFilters

public Map<String,javax.servlet.Filter> getFilters()

Returns the filterName-to-Filter map of filters available for reference when defining filter chain definitions. All filter chain definitions will reference filters by the names in this map (i.e. the keys).

Returns:

the filterName-to-Filter map of filters available for reference when defining filter chain definitions.

setFilters

public void setFilters(Map<String,javax.servlet.Filter> filters)

Sets the filterName-to-Filter map of filters available for reference when creating filter chain definitions.

Note: This property is optional: this FactoryBean implementation will discover all beans in the web application context that implement the Filter interface and automatically add them to this filter map under their bean name.

For example, just defining this bean in a web Spring XML application context:

 <bean id="myFilter" class="com.class.that.implements.javax.servlet.Filter">
 ...
 </bean>

Will automatically place that bean into this Filters map under the key 'myFilter'.

Parameters:

filters - the optional filterName-to-Filter map of filters available for reference when creating (java.util.Map) filter chain definitions.

getFilterChainDefinitionMap

public Map<String,String> getFilterChainDefinitionMap()

Returns the chainName-to-chainDefinition map of chain definitions to use for creating filter chains intercepted by the Shiro Filter. Each map entry should conform to the format defined by the FilterChainManager.createChain(String, String) JavaDoc, where the map key is the chain name (e.g. URL path expression) and the map value is the comma-delimited string chain definition.

Returns:

he chainName-to-chainDefinition map of chain definitions to use for creating filter chains intercepted by the Shiro Filter.

setFilterChainDefinitionMap

public void setFilterChainDefinitionMap(Map<String,String> filterChainDefinitionMap)

Sets the chainName-to-chainDefinition map of chain definitions to use for creating filter chains intercepted by the Shiro Filter. Each map entry should conform to the format defined by the FilterChainManager.createChain(String, String) JavaDoc, where the map key is the chain name (e.g. URL path expression) and the map value is the comma-delimited string chain definition.

Parameters:

filterChainDefinitionMap - the chainName-to-chainDefinition map of chain definitions to use for creating filter chains intercepted by the Shiro Filter.

setFilterChainDefinitions

public void setFilterChainDefinitions(String definitions)

A convenience method that sets the filterChainDefinitionMap property by accepting a Properties-compatible string (multi-line key/value pairs). Each key/value pair must conform to the format defined by the FilterChainManager.createChain(String,String) JavaDoc - each property key is an ant URL path expression and the value is the comma-delimited chain definition.

Parameters:

definitions - a Properties-compatible string (multi-line key/value pairs) where each key/value pair represents a single urlPathExpression-commaDelimitedChainDefinition.

getObject

public Object getObject()
                 throws Exception

Lazily creates and returns a AbstractShiroFilter concrete instance via the createInstance() method.

Specified by:

getObject in interface org.springframework.beans.factory.FactoryBean

Returns:

the application's Shiro Filter instance used to filter incoming web requests.

Throws:

Exception - if there is a problem creating the Filter instance.

getObjectType

public Class getObjectType()

Returns AbstractShiroFilter.class

Specified by:

getObjectType in interface org.springframework.beans.factory.FactoryBean

Returns:

AbstractShiroFilter.class

isSingleton

public boolean isSingleton()

Returns true always. There is almost always only ever 1 Shiro Filter per web application.

Specified by:

isSingleton in interface org.springframework.beans.factory.FactoryBean

Returns:

true always. There is almost always only ever 1 Shiro Filter per web application.

createFilterChainManager

protected FilterChainManager createFilterChainManager()

createInstance

protected AbstractShiroFilter createInstance()
                                      throws Exception

This implementation:

1. Ensures the required securityManager property has been set
2. Creates a FilterChainManager instance that reflects the configured filters and filter chain definitions
3. Wraps the FilterChainManager with a suitable FilterChainResolver since the Shiro Filter implementations do not know of FilterChainManagers
4. Sets both the SecurityManager and FilterChainResolver instances on a new Shiro Filter instance and returns that filter instance.

Returns:

a new Shiro Filter reflecting any configured filters and filter chain definitions.

Throws:

Exception - if there is a problem creating the AbstractShiroFilter instance.

postProcessBeforeInitialization

public Object postProcessBeforeInitialization(Object bean,
                                              String beanName)
                                       throws org.springframework.beans.BeansException

Inspects a bean, and if it implements the Filter interface, automatically adds that filter instance to the internal filters map that will be referenced later during filter chain construction.

Specified by:

postProcessBeforeInitialization in interface org.springframework.beans.factory.config.BeanPostProcessor

Throws:

org.springframework.beans.BeansException

postProcessAfterInitialization

public Object postProcessAfterInitialization(Object bean,
                                             String beanName)
                                      throws org.springframework.beans.BeansException

Does nothing - only exists to satisfy the BeanPostProcessor interface and immediately returns the bean argument.

Specified by:

postProcessAfterInitialization in interface org.springframework.beans.factory.config.BeanPostProcessor

Throws:

org.springframework.beans.BeansException