org.apache.shiro.web.servlet
Class IniShiroFilter

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
                  org.apache.shiro.web.servlet.AbstractShiroFilter
                      org.apache.shiro.web.servlet.IniShiroFilter

All Implemented Interfaces:

Filter, Nameable

public class IniShiroFilter
extends AbstractShiroFilter

Main Servlet Filter that configures and enables all Shiro functions within a web application by using the INI configuration format.

The following is a fully commented example that documents how to configure it:

<filter>
 <filter-name>ShiroFilter</filter-name>
 <filter-class>org.apache.shiro.web.servlet.IniShiroFilter</filter-class>
 <init-param><param-name>config</param-name><param-value>
 #
 #NOTE:  This config looks pretty long - but its not - its only a few lines of actual config.
 #       Everything else is just heavily commented to explain things in-depth. Feel free to delete any
 #       comments that you don't want to read from your own configuration ;)
 #
 # Any commented values below that _don't_ start with 'example.pkg' are Shiro's defaults.  If you want to change any
 # values on those lines, you only need to uncomment the lines you want to change.
 #
 [main]
 # The 'main' section defines Shiro-wide configuration.
 #
 # Each section's configuration is essentially an object graph definition in a .properties style (name/value pair)
 # format.  The beans defined would be those that are used to construct the application's SecurityManager.  It is
 # essentially 'poor man's' dependency injection via a .properties format.
 #
 # --- Defining Realms ---
 #
 # Any Realm defined here will automatically be injected into Shiro's default SecurityManager created at start up.
 # For example:
 #
 # myRealm = example.pkg.security.MyRealm
 #
 # This would instantiate the example.pkg.security.MyRealm class with a default no-arg constructor and inject it into
 # the SecurityManager.  More than one realm can be defined if needed.  You can create graphs and reference
 # other beans ('$' bean reference notation) while defining Realms and other objects:
 #
 # connectionFactory = example.pkg.ConnectionFactory
 # connectionFactory.driverClassName = a.jdbc.Driver
 # connectionFactory.username = aUsername
 # connectionFactory.password = aPassword
 # connectionFactory.minConnections = 3
 # connectionFactory.maxConnections = 10
 # ... etc...
 #
 # myJdbcRealm = example.pkg.jdbc.MyJdbcRealm
 # myJdbcRealm.connectionFactory = $connectionFactory
 # ... etc ...
 #
 # --- Realm Factories ---
 #
 # If the INI style isn't robust enough for your needs, you also have the option of implementing the
 # org.apache.shiro.realm.RealmFactory interface with more complex construction
 # logic.  Then you can declare the implementation here instead.  The realms it returns will be injected in to the
 # SecurityManager just as the individual Realms are.  For example:
 #
 # aRealmFactory = example.pkg.ClassThatImplementsRealmFactory
 #
 # --- SessionManager properties ---
 #
 # Except for Realms and RealmFactories, all other objects should be defined and set on the SecurityManager directly.
 # The default 'securityManager' bean is an instance of DefaultWebSecurityManager, so you
 # can set any of its corresponding properties as necessary:
 #
 # someObject = some.fully.qualified.ClassName
 # someObject.propertyN = foo
 # ...
 # securityManager.someObject = $someObject
 #
 # For example, if you wanted to change Shiro's default session mechanism, you can change the 'sessionMode' property.
 # By default, Shiro's Session infrastructure in a web environment will use the
 # Servlet container's HttpSession.  However, if you need to share session state across client types
 # (e.g. Web MVC plus Java Web Start or Flash), or are doing distributed/shared Sessions for
 # Single Sign On, HttpSessions aren't good enough.  You'll need to use Shiro's more powerful
 # (and client-agnostic) session management.  You can enable this by uncommenting the following line
 # and changing 'http' to 'native'
 #
 #securityManager.sessionMode = http
 #
 [filters]
 # This section defines the 'pool' of all Filters available to the url path definitions in the [urls] section below.
 #
 # The following commented values are already provided by Shiro by default and are immediately usable
 # in the [urls] definitions below.  If you like, you may override any values by uncommenting only the lines
 # you need to change.
 #
 # Each Filter is configured based on its functionality and/or protocol.  You should read each
 # Filter's JavaDoc to fully understand what each does and how it works as well as how it would
 # affect the user experience.
 #
 # Form-based Authentication filter:
 #authc = FormAuthenticationFilter
 #authc.loginUrl = /login.jsp
 #authc.usernameParam = username
 #authc.passwordParam = password
 #authc.rememberMeParam = rememberMe
 #authc.successUrl  = /login.jsp
 #authc.failureKeyAttribute = FormAuthenticationFilter.DEFAULT_ERROR_KEY_ATTRIBUTE_NAME
 #
 # Http BASIC Authentication filter:
 #authcBasic = BasicHttpAuthenticationFilter
 #authcBasic.applicationName = application
 #
 # Roles filter: requires the requesting user to have one or more roles for the request to continue.
 # If they do not have the specified roles, they are redirected to the specified URL.
 #roles = RolesAuthorizationFilter
 #roles.unauthorizedUrl =
 # (note the above url is null by default, which will cause an HTTP 403 (Access Denied) response instead
 # of redirecting to a page.  If you want to show a 'nice page' instead, you should specify that url.
 #
 # Permissions filter: requires the requesting user to have one or more permissions for the request to
 # continue, and if they do not, redirects them to the specified URL.
 #perms = PermissionsAuthorizationFilter
 #perms.unauthorizedUrl =
 # (note the above url is null by default, which will cause an HTTP 403 (Access Denied) response instead
 # of redirecting to a page.  If you want to show a 'nice page' instead, you should specify that url.  Many
 # applications like to use the same url specified in roles.unauthorizedUrl above.
 #
 #
 # Define your own filters here as you would any other object as described in the '[main]' section above (properties,
 # $references, etc).  To properly handle url path matching (see the [urls] section below), your
 # filter should extend the PathMatchingFilter abstract class.
 #
 [urls]
 # This section defines url path mappings.  Each mapping entry must be on a single line and conform to the
 # following representation:
 #
 # ant_path_expression = path_specific_filter_chain_definition
 #
 # For any request that matches a specified path, the corresponding value defines a comma-delimited chain of
 # filters to execute for that request.
 #
 # This is incredibly powerful in that you can define arbitrary filter chains for any given request pattern
 # to greatly customize the security experience.
 #
 # The path_specific_filter_chain_definition must match the following format:
 #
 # filter1[optional_config1], filter2[optional_config2], ..., filterN[optional_configN]
 #
 # where 'filterN' is the name of an filter defined above in the [filters] section and
 # '[optional_configN]' is an optional bracketed string that has meaning for that particular filter for
 # _that particular path_.  If the filter does not need specific config for that url path, you may
 # discard the brackets so filterN[] just becomes filterN.
 #
 # And because filter tokens define chains, order matters!  Define the tokens for each path pattern
 # in the order you want them to filter (comma-delimited).
 #
 # Finally, each filter is free to handle the response however it wants if its necessary
 # conditions are not met (redirect, HTTP error code, direct rendering, etc).  Otherwise, it is expected to allow
 # the request to continue through the chain on to the final destination view.
 #
 # Examples:
 #
 # To illustrate chain configuration, look at the /account/** mapping below.  This says
 # "apply the above 'authcBasic' filter to any request matching the '/account/**' pattern".  Since the
 # 'authcBasic' filter does not need any path-specific config, it doesn't have any config brackets [].
 #
 # The /remoting/** definition on the other hand uses the 'roles' and 'perms' filters which do use
 # bracket notation.  That definition says:
 #
 # "To access /remoting/** urls, ensure that the user is first authenticated ('authcBasic'), then ensure that user
 # has the 'b2bClient' role, and then finally ensure that they have the 'remote:invoke:lan,wan' permission."
 #
 # (Note that because elements within brackets [ ] are comma-delimited themselves, we needed to quote any config
 # value which may require a comma. If we didn't do that, the permission filter below would interpret
 # the text between the brackets as two permissions: 'remote:invoke:lan' and 'wan' instead of the
 # single desired 'remote:invoke:lan,wan' token.  So, you can use quotes wherever you need to escape internal
 # commas.)
 #
 /account/** = authcBasic
 /remoting/** = authcBasic, roles[b2bClient], perms["remote:invoke:lan,wan"]
 </param-value></init-param>
 </filter>
 

 <filter-mapping>
     <filter-name>ShiroFilter</filter-name>
     <url-pattern>/*</url-pattern>
 </filter-mapping>

Since:

1.0

Field Summary

static String	CONFIG_INIT_PARAM_NAME
static String	CONFIG_PATH_INIT_PARAM_NAME

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

ALREADY_FILTERED_SUFFIX

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

filterConfig

Constructor Summary

IniShiroFilter()

Method Summary

protected void	applyFilterChainResolver(Ini ini, Map<String,?> defaults)
protected void	applyInitParams()
protected Map<String,?>	applySecurityManager(Ini ini)
protected void	configure()
protected Ini	convertConfigToIni(String config)
protected Ini	convertPathToIni(String path)
String	getConfig() Returns the actual INI configuration text to use to build the SecurityManager and FilterChainResolver used by the web application or null if the configPath should be used to load a fallback INI source.
String	getConfigPath() Returns the config path to be used to load a .ini file for configuration if a configuration is not specified via the config attribute.
void	init()
protected Ini	loadIniFromConfig()
protected Ini	loadIniFromPath()
void	setConfig(String config) Sets the actual INI configuration text to use to build the SecurityManager and FilterChainResolver used by the web application.
void	setConfigPath(String configPath) Sets the config path to be used to load a .ini file for configuration if a configuration is not specified via the config attribute.

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

createDefaultSecurityManager, createSubject, doFilterInternal, executeChain, getExecutionChain, getFilterChainResolver, getSecurityManager, isHttpSessions, onFilterConfigSet, prepareServletRequest, prepareServletResponse, setFilterChainResolver, setSecurityManager, updateSessionLastAccessTime, wrapServletRequest, wrapServletResponse

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

doFilter, getAlreadyFilteredAttributeName, shouldNotFilter

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, 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

CONFIG_INIT_PARAM_NAME

public static final String CONFIG_INIT_PARAM_NAME

See Also:

Constant Field Values

CONFIG_PATH_INIT_PARAM_NAME

public static final String CONFIG_PATH_INIT_PARAM_NAME

See Also:

Constant Field Values

Constructor Detail

IniShiroFilter

public IniShiroFilter()

Method Detail

getConfig

public String getConfig()

Returns the actual INI configuration text to use to build the SecurityManager and FilterChainResolver used by the web application or null if the configPath should be used to load a fallback INI source.

This value is null by default, but it will be automatically set to the value of the 'config' init-param if it exists in the FilterConfig provided by the servlet container at startup.

Returns:

the actual INI configuration text to use to build the SecurityManager and FilterChainResolver used by the web application or null if the configPath should be used to load a fallback INI source.

setConfig

public void setConfig(String config)

Sets the actual INI configuration text to use to build the SecurityManager and FilterChainResolver used by the web application. If this value is null, the configPath will be checked to see if a .ini file should be loaded instead.

This value is null by default, but it will be automatically set to the value of the 'config' init-param if it exists in the FilterConfig provided by the servlet container at startup.

Parameters:

config - the actual INI configuration text to use to build the SecurityManager and FilterChainResolver used by the web application.

getConfigPath

public String getConfigPath()

Returns the config path to be used to load a .ini file for configuration if a configuration is not specified via the config attribute.

This value is null by default, but it will be automatically set to the value of the 'configPath' init-param if it exists in the FilterConfig provided by the servlet container at startup.

Returns:

the config path to be used to load a .ini file for configuration if a configuration is not specified via the config attribute.

setConfigPath

public void setConfigPath(String configPath)

Sets the config path to be used to load a .ini file for configuration if a configuration is not specified via the config attribute.

This value is null by default, but it will be automatically set to the value of the 'configPath' init-param if it exists in the FilterConfig provided by the servlet container at startup.

Parameters:

configPath - the config path to be used to load a .ini file for configuration if a configuration is not specified via the config attribute.

init

public void init()
          throws Exception

Overrides:

init in class AbstractShiroFilter

Throws:

Exception

applyInitParams

protected void applyInitParams()
                        throws Exception

Throws:

Exception

configure

protected void configure()
                  throws Exception

Throws:

Exception

loadIniFromConfig

protected Ini loadIniFromConfig()

loadIniFromPath

protected Ini loadIniFromPath()

applySecurityManager

protected Map<String,?> applySecurityManager(Ini ini)

applyFilterChainResolver

protected void applyFilterChainResolver(Ini ini,
                                        Map<String,?> defaults)

convertConfigToIni

protected Ini convertConfigToIni(String config)

convertPathToIni

protected Ini convertPathToIni(String path)